Skip to main content

System Topics ($SYS)

MAPS Messaging publishes operational status and statistics under the $SYS/ namespace. Any supported protocol can read these topics (e.g., MQTT, AMQP 1.0, STOMP, NATS, CoAP via bridges).

Use cases: quick health checks, client/session counts, throughput/bytes, destination/endpoint stats, moving‑average trends.

Enabling / Disabling​

These are controlled in MessageDaemon.yaml:

  • EnableSystemTopics: true — publishes the standard $SYS set.
  • EnableSystemStatusTopics: true — publishes extended JSON status documents under $SYS/server/....
  • EnableSystemTopicAverages: true — adds moving‑average variants for selected metrics.

See Configuration → MessageDaemon for full descriptions of these flags.

Access Patterns (by protocol)​

  • MQTT: subscribe to "$SYS/#" (wildcard).
  • AMQP 1.0: receive from address "$SYS/..." (topic‑style).
  • STOMP: SUBSCRIBE to /topic/$SYS/#.
  • NATS: SUB $SYS.> (dot separator).
  • Bridged protocols: identical $SYS tree is exposed once bridged.

$SYS/ is read‑only (server‑generated); clients should not publish to it.

Core Topics (examples)​

Exact set may evolve; discover with a wildcard subscription on $SYS/#.

Broker/server

  • $SYS/broker/uptime — milliseconds since start
  • $SYS/broker/version — semantic version string
  • $SYS/broker/timestamp — server time (epoch ms)
  • $SYS/server/health — OK | Warning | Error

Clients

  • $SYS/clients/connected — current connections
  • $SYS/clients/maximum — peak concurrent since start
  • $SYS/clients/disconnectedTotal — total disconnects

Throughput & bytes

  • $SYS/messages/in/total — total msgs in
  • $SYS/messages/out/total — total msgs out
  • $SYS/bytes/in/total — bytes in
  • $SYS/bytes/out/total — bytes out

Endpoints / listeners (per endpoint)

  • $SYS/endpoint/{name}/connected
  • $SYS/endpoint/{name}/bytesInTotal
  • $SYS/endpoint/{name}/bytesOutTotal
  • $SYS/endpoint/{name}/messagesInTotal
  • $SYS/endpoint/{name}/messagesOutTotal
  • $SYS/endpoint/{name}/errorsTotal

Destinations (per namespace/queue/topic)

  • $SYS/destination/{dest}/enqueued
  • $SYS/destination/{dest}/dequeued
  • $SYS/destination/{dest}/pending
  • $SYS/destination/{dest}/consumers
  • $SYS/destination/{dest}/producers

Moving averages (when enabled)

  • For selected metrics, additional $SYS/... entries reflect moving averages over multiple windows (e.g., short/medium/long).

Extended Status (JSON)​

When EnableSystemStatusTopics: true, structured JSON documents are published under $SYS/server/... (for programmatic scraping and dashboards). Typical groups include:

  • broker (uptime, build, heap/non‑heap, CPU)
  • protocols (MQTT, AMQP, NATS, CoAP, etc.)
  • endpoints (per listener)
  • destinations (per queue/topic)
  • tasks (internal queues/schedulers)

Fields and groups may expand over time. Subscribe to $SYS/server/# to enumerate current documents.

Security & ACLs​

  • $SYS/ is readable by authenticated clients by default (unless you restrict it).
  • For multi‑tenant/hosted scenarios, deny external access to $SYS or allow only to trusted roles.
  • Example policy intent: allow read to $SYS/# for admins; deny to regular tenants.

Note: $SYS messages reflect internal state; treat as operational telemetry. Avoid exposing $SYS topics directly over the public Internet.

Performance Considerations​

  • Publishing frequency and moving‑average calculations are lightweight; impact is minimal under normal load.
  • High‑cardinality trees (many destinations/endpoints) will produce more $SYS messages. Use wildcard filters to limit client traffic as needed.

Quick Start (MQTT)​

# Subscribe to everything under $SYS
SUB $SYS/#

# You should see status lines such as:
$SYS/broker/uptime  1234567
$SYS/clients/connected  42
$SYS/messages/in/total  102938
$SYS/server/health  OK