Observability

ngz_iot_observe turns connection and broker behavior into bounded operational facts. Nginx owns per-worker counters; nginz-iotd aggregates cross-worker broker, ring, store, rule, and bridge state.

Stream configuration

stream {
  server {
    iot_observe on;
    iot_observe_cardinality_limit 256;
    iot_observe_labels deployment,node,listener;
  }
}

Only use allowlisted, bounded labels. Device IDs, client IDs, topics, and arbitrary tenant values can create unsafe metric cardinality and should stay in controlled event or audit views.

Available facts

The nginx boundary exposes $iot_observe_worker_connections and $iot_observe_worker_finalized. Daemon snapshots add ring depth and errors, session and routing health, durability frontiers, bridge outcomes, current generation and writer term, and redacted configuration state.

Snapshot health

A dedicated snapshot thread performs the writes outside the broker command path. Production readiness withdraws when required output is stale or unhealthy; configure observe.snapshot_interval_ms and admin.snapshot_max_age_ms together.

The operator console Observe page and the operator CLI (ngz-iot metrics) consume the same bounded counters. Do not export device IDs or topics as Prometheus labels.