MQTT Broker System Topics ($SYS)

The Intelligence Hub broker publishes a set of $SYS topics that expose internal broker state in real time. $SYS is not part of the MQTT specification, but is a widely used broker convention supported by brokers such as Mosquitto and HiveMQ.

Status topics are refreshed every 10 seconds and published as retained messages, so clients receive the current value immediately upon subscribing. Subscribing to $SYS/# returns all system topics at once.

Status Topics

The following read-only topics expose live broker state.

Topic	Type	Description
`$SYS/broker/productInfo`	String	Product name and version.
`$SYS/broker/messageInfo`	JSON object	Message and byte throughput counters.
`$SYS/broker/clientInfo/count`	JSON number	Number of active client sessions.
`$SYS/broker/clientInfo/sessions`	JSON object	All active sessions, keyed by `clientId`.
`$SYS/broker/clientInfo/sessions/<clientId>`	JSON object	Session detail for a specific client.
`$SYS/broker/topicInfo/count`	JSON number	Number of tracked public topics.
`$SYS/broker/topicInfo/topics/<topicName>`	JSON object	Metadata about a specific topic.

$SYS/broker/productInfo

A plain string containing the product name and version.

Example payload:

HighByte IntelligenceHub 4.5.0

$SYS/broker/messageInfo

Message and byte throughput counters since broker start-up.

Field	Type	Description
`messagesReceived`	number	Total messages received from clients.
`messagesSent`	number	Total messages sent to clients.
`messagesRetained`	number	Number of retained messages currently stored by the broker.
`bytesRetained`	number	Total bytes of retained messages currently stored.
`messagesCached`	number	Number of messages currently cached for delivery.
`bytesCached`	number	Total bytes of messages currently cached for delivery.

Example payload:

{
  "messagesReceived": 0,
  "messagesSent": 42,
  "messagesRetained": 6,
  "bytesRetained": 863,
  "messagesCached": 51,
  "bytesCached": 8314
}

$SYS/broker/clientInfo/count

A single JSON number representing the count of active client sessions.

$SYS/broker/clientInfo/sessions

A JSON object containing all active client sessions, keyed by clientId.

Field	Type	Description
`clientId`	string	The MQTT client identifier.
`sessionId`	string	A unique identifier for this session instance.
`cleanSession`	boolean	Whether the client connected with the clean session flag set.
`createdTime`	string	ISO 8601 timestamp when the session was created.
`messagesReceived`	number	Total messages received from this client during the session.
`bytesReceived`	number	Total bytes received from this client during the session.
`messagesSent`	number	Total messages sent to this client during the session.
`bytesSent`	number	Total bytes sent to this client during the session.
`isConnected`	boolean	Whether the client is currently connected.
`endpointAddress`	string	The client’s remote IP address and port.
`sessionAge`	number	Seconds elapsed since the session was established.
`subscriptionFilters`	array	Topic filters to which the client is currently subscribed.

Example payload:

{
  "my-client": {
    "clientId": "my-client",
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cleanSession": true,
    "createdTime": "2026-05-27T19:31:11.533154319Z",
    "messagesReceived": 0,
    "bytesReceived": 57,
    "messagesSent": 12,
    "bytesSent": 732,
    "isConnected": true,
    "endpointAddress": "/192.168.1.100:52400",
    "sessionAge": 9,
    "subscriptionFilters": ["#", "$SYS/#"]
  }
}

Client session info is removed within 10 seconds of disconnect.

$SYS/broker/clientInfo/sessions/<clientId>

The same schema as an individual entry in $SYS/broker/clientInfo/sessions, scoped to a single client.

$SYS/broker/topicInfo/count

A single JSON number representing the count of public topics tracked since broker start-up.

$SYS/broker/topicInfo/topics/<topicName>

Metadata about a specific public topic, including the last publisher and message properties.

Field	Type	Description
`topic`	string	The full topic name.
`time`	string	ISO 8601 timestamp of the last message published to the topic.
`clientId`	string	Client ID of the last publisher.
`qos`	number	QoS level of the last message (0, 1, or 2).
`retain`	boolean	Whether the last message was published with the retain flag.

Example payload for $SYS/broker/topicInfo/topics/sensors/plant1/temperature:

{
  "topic": "sensors/plant1/temperature",
  "time": "2026-05-27T14:35:02.000Z",
  "clientId": "edge-gateway-01",
  "qos": 0,
  "retain": false
}

This topic tracks all topics to which messages have been published since the broker started, not subscriptions. For subscription visibility, use $SYS/broker/clientInfo/sessions.

Topic info persists across client disconnects. Use $SYS/broker/command/reset/topicInfo to clear stale entries.

Command Topics

Publishing to a command topic triggers a broker action. The payload content is ignored — any payload will activate the command.

Topic	Description	Auth Required
`$SYS/broker/command/reset/retained`	Clears all retained messages in the public namespace (`#`). `$SYS` messages are not affected.	Yes
`$SYS/broker/command/reset/topicInfo`	Clears all retained messages under `$SYS/broker/topicInfo`.	Yes

Anonymous access is not allowed for command topics. The publishing client must authenticate with a user that has the broker:publish or broker:* claim. Commands are processed within 10 seconds. After a reset, a log message is published with the clientId and count of messages removed.

$SYS topics are excluded from retained message resets triggered by $SYS/broker/command/reset/retained.

Use Cases

Monitoring connected clients

Subscribe to $SYS/broker/clientInfo/sessions to see all connected clients and their subscription filters in real time. The subscriptionFilters field shows exactly which topics each client is monitoring.

Discovering who publishes to a topic

Subscribe to $SYS/broker/topicInfo/topics/# to see metadata for every topic active since broker start-up, including the last publisher (clientId), QoS, and retain flag. This is the recommended approach for auditing what is being published and by whom.

Broker health monitoring

Subscribe to $SYS/broker/messageInfo to track message and byte throughput over time. Because status topics are retained, a single subscribe returns the current snapshot immediately without waiting for the next 10-second refresh.