"describeMqSessions"
Use the "describeMqSessions" action to view information about a client's MQTT session
The "describeMqSessions" action requires "clientNames" and returns information about the MQ sessions, which may be an MQTT or MQ API session.
Request examples
Minimal
{
"api": "mq",
"action": "describeMqSessions",
"params": {
"clientNames": [
"myClientIdentifier"
]
}
}Maximal
{
"api": "mq",
"action": "describeMqSessions",
"params":
{
"clientName": "a unique MQTT client identifier or empty string"
},
"apiVersion": "1.0",
"debug": "max",
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
} Response example
{
"requestId": "clientRequestId",
"result": {
"sessionPresent": false,
"clientName": "a unique MQTT client identifier",
"sessionExpiryInterval": 0,
"receiveMaximum": 65535,
"maximumQoS": 2,
"retainAvailable": true,
"maximumPacketSize": 268435460,
"topicAliasMaximum": 65535,
"reasonString": "",
"userProperties": [ {"key":"", "value":""} ],
"wildcardSubscriptionAvailable": true,
"subscriptionIdentifiersAvailable": true,
"sharedSubscriptionAvailable": true,
"brokerKeepAlive": 0,
"responseMessagePrefix": "uniqueTopicPrefixForResponseMessages/",
"brokerReference": "optional connection string to another broker",
"authenticationMethod": "",
"authenticationData": "encoded binary value for authentication",
"sessionHealth": "healthy|unhealthy|offline",
"minHealthySendRatePerMinute": 10,
"maxHealthySendRatePerMinute": 1000,
"maxHealhtyBacklogRatePerMinute": 10,
"minHealthySubscribedTopicFiltersCount": 10,
"maxHealthySubscribedTopicFiltersCount": 1000,
"subscriptions": [
{
"topicFilter": "some/topic/name/with/optional/wildcards",
"matchingTopics": [
{
"topic": "a/specific/non-wildcard/topic/name",
"databaseName": "faircom",
"ownerName": "admin",
"tableName": "mqtt_msg_topic1"
}
],
"subscriptionIdentifier": 268435455,
"receiveMyOwnMessages": false,
"receiveRetainedMessages": "onSubscription | onNewSubscription | never",
"receiveRetainedFlagAsPublished": true
}
],
},
"errorCode": 0,
"errorMessage": "",
"debugInfo": {}
}Use the "describeMqSessions" action to view information about a client's MQTT session
Property | Description | Default | Type | Limits (inclusive) | |||
|---|---|---|---|---|---|---|---|
specifies the unique name that identifies the client to the FairCom MQTT engine |
| string | 0 to 65,550 bytes | ||||
specifies the maximum number of backlog messages per minute for a session to be considered healthy |
| integer | |||||
specifies the maximum number of messages per minute for a session to be considered healthy |
| integer | |||||
specifies the maximum number of topic filters for a session to be considered healthy |
| integer | |||||
specifies the minimum number of messages per minute for a session to be considered healthy |
| integer | |||||
specifies the minimum number of topic filters for a session to be considered healthy |
| integer | |||||
specifies the status of the MQ session's health | No default value | enum |
|
The "clientName" property is an optional string of up to 65550 characters containing a client name that uniquely identifies the client to the FairCom MQTT engine.
The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the MQTT broker disconnects the other client and vice-versa.
The JSON MQ Message API behaves differently because it is stateless; it allows multiple processes to simultaneously use the same client identifier to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics.
The "maxHealthyBacklogRatePerMinute" property sets the maximum number of backlog messages per minute for a healthy session. A backlog message is one the server has not yet published to subscribers. The backlog of a topic grows when the incoming message rate exceeds the outgoing. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.
A connected session is healthy when its message backlog rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthyBacklogRatePerMinute" property and the "sessionHealth" property to report the health of a session.
The "maxHealthySendRatePerMinute" property sets the maximum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.
A connected session is healthy when its message send rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.
The "maxHealthySubscribedTopicFiltersCount" property sets the maximum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no upper bound.
A connected session is healthy when it has subscribed to at most the maximum number of topic filters. The "describeMqSessions" action returns the "maxHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.
A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "maxHealthySubscribedTopicFiltersCount" property does not limit the number of topics.
The "minHealthySendRatePerMinute" property sets the minimum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no lower bound.
A connected session is healthy when its message send rate exceeds the minimum. The "describeMqSessions" action returns the "minHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.
The "minHealthySubscribedTopicFiltersCount" property sets the minimum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no lower bound.
A connected session is healthy when it has subscribed to at least the minimum number of topic filters. The "describeMqSessions" action returns the "minHealthySubscribedTopicFiltersCount" property and the "sessionHealthy" property to report the health of a session.
A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "maxHealthySubscribedTopicFiltersCount" property does not limit the number of topics.
The "sessionHealth" property is included in the response to the "describeMqSessions" action. It is an enumerated string with the following values: "healthy", "unhealthy", and "offline":
"healthy"indicates the session is healthy, which occurs when a client is:Connected
Sends the expected number of messages per minute (see
"minHealthySendRatePerMinute").Sends less than or equal to the maximum number of messages per minute (see
"maxHealthySendRatePerMinute").Does not exceed the maximum backlog of unprocessed subscribed messages (see
"maxHealthyBacklogRatePerMinute").Subscribes to at least the minimum expected number of topic filters ( see
"minHealthySubscribedTopicFiltersCount").Subscribes to no more than the maximum number of expected number of topic filters (see
"maxHealthySubscribedTopicFiltersCount").
"unhealthy"indicates the session is unhealthy, which occurs when a client:Fails to send the expected number of messages per minute (see
"minHealthySendRatePerMinute").Sends more than the maximum number of messages per minute (see
"maxHealthySendRatePerMinute").Exceeds the maximum backlog of unprocessed subscribed messages (see
"maxHealthyBacklogRatePerMinute").Subscribes to less than the minimum number of expected number of topic filters ( see
"minHealthySubscribedTopicFiltersCount").Subscribes to more than the maximum number of expected number of topic filters (see
"maxHealthySubscribedTopicFiltersCount").
"offline"indicates a session is not connected.
The server excludes a metric from the calculation when it is set to the default value of 0.
The session health properties include:
"minHealthySendRatePerMinute""maxHealthySendRatePerMinute""maxHealthyBacklogRatePerMinute""minHealthySubscribedTopicFiltersCount""maxHealthySubscribedTopicFiltersCount"