"describeMqSessions" (jsonAction)
Use the "describeMqSessions" action to view information about a client's MQ or MQ API 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"
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}{
"api": "mq",
"action": "describeMqSessions",
"params":
{
"clientNames": [
"a unique MQTT or MQ API client name"
],
"includeSubscribedTopics": true,
"includePublishedTopics": true,
"includeStats": true
},
"apiVersion": "1.0",
"debug": "max",
"requestId": "optionalUniqueRequestIdFromTheClient",
"authToken": "replaceWithAuthTokenFromCreateSession"
} {
"requestId": "clientRequestId",
"result": {
"data": [
{
"clientName": "a unique MQ API client identifier",
"sessionType": "mqApi",
"connectionStatus": "disconnected|connected|connectedTemporarily",
"connectionDateTime": "2024-12-06T23:45:47",
"disconnectionDateTime": "2024-12-06T23:22:34",
"disconnectionReason": "Disconnection reason string",
"lastFailedConnectionDateTime": "2024-12-06T23:22:34",
"lastFailedConnectionReason": "Connection failure reason string",
"internalSession": false,
"sessionStatus": "normal",
"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",
"label": {
"id": 423,
"group": "mylabelGroupName",
"name": "mylabelName",
"value": 99,
"enum": 0,
"sequence": 1.2,
"deprecated": false,
"description": "My label description.",
"metadata": {}
},
"stats": {
"sessionHealth": "healthy|unhealthy|offline",
"minHealthySendRatePerMinute": 10,
"maxHealthySendRatePerMinute": 1000,
"maxHealthyBacklogRatePerMinute": 10,
"minHealthySubscribedTopicFiltersCount": 10,
"maxHealthySubscribedTopicFiltersCount": 1000,
"firstMessagePublishedOn": "2024-12-06T23:45:47",
"lastMessagePublishedOn": "2024-12-06T23:45:47",
"totalMessagesPublished": 1634,
"publishRatePerMinute": 10,
"publishRatePerMinuteLast10Minutes": 9.34,
"publishRatePerMinuteSinceInSession": 5.73,
"publishRatePerHour": 43.47,
"firstMessageReceivedOn": "2024-12-06T23:45:47",
"lastMessageReceivedOn": "2024-12-06T23:45:47",
"totalMessagesReceived": 1634,
"receiveMessagesPerMinute": 10,
"receiveMessagesPerMinuteLast10Minutes": 9.34,
"receiveMessagesPerMinuteSinceInSession": 5.73,
"receiveMessagesPerHour": 43.47,
"currentDeliveryBacklogged": 1634,
"deliveryBacklogRatePerMinute": 132,
"deliveryBacklogRatePerMinuteLast10Minutes": 92.3,
"deliveryBacklogRatePerMinuteSinceInSession": 55.29,
"deliveryBacklogRatePerHour": 132,
"deliveryBacklogRatePerDay": 132,
},
"subscriberCount": 2,
"subscribedTopics": [
{
"topicFilter": "devices/#",
"topics": [
{
"topic": "devices/topic1"
},
{
"topic": "devices/topic2"
},
{
"topic": "devices/topic3"
}
]
},
{
"topicFilter": "test",
"topics": [
{
"topic": "test"
}
]
}
],
"publishedTopics": [
"test/topic1",
"topic2",
"topic3"
],
"metadata": {}
}
]
},
"errorCode": 0,
"errorMessage": "",
"debugInfo": {}
}Use the "describeMqSessions" action to view information about a client's MQTT session
"params" property summariesProperty | Description | Default | Type | Limits (inclusive) | ||
|---|---|---|---|---|---|---|
(optional) specifies the unique name that identifies the client to the FairCom MQ engine |
| string | 0 to 65,550 bytes | |||
(optional) indicates whether or not additional fields that are not the built-in integration table fields, transform fields, or MQTT fields will be included in the response |
| Boolean |
| |||
(optional) indicates whether or not the |
| Boolean |
| |||
(optional) indicates whether or not the |
| Boolean |
| |||
(optional) indicates whether or not the |
| Boolean |
|
The "clientName" property is an optional string of up to 65,550 characters. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.
Connection authorization is done using an account name with a password or a client certificate.
The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.
The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics.
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 FairCom server disconnects the other client and vice-versa.
Set the "includeOtherFields" property to true to include additional fields that are not the built-in integration table fields, transform fields, or MQTT fields. Otherwise, omit the property or set it to false or null.
Set the "includePublishedTopics" property to true for the response to include the "publishedTopics" property, which contains all topics a client's session has published since the session was created. To omit the list of published topics, omit this property or set it to false or null.
The "includeStats" property indicates whether or not the "stats" property will be returned in the response.
Set the "includeSubscribedTopics" property to true for the response to include the "subscribedTopics" property, which contains the topics a client's session is currently subscribed to. To omit the list of subscribed topics, omit this property or set it to false or null.
Property | Description | Type | Limits (inclusive) | |||
|---|---|---|---|---|---|---|
indicates if and how a client is connected to an MQ session | string |
| ||||
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 topics the client has published since the session was first created | array | |||||
specifies the status of the MQ session's health | string |
| ||||
specifies which type of session the requested client is currently running | string |
|
The "connectionStatus" property is returned by the "describeMqSessions" action to indicate if and how a client is connected to an MQ session. It has the following values:
"disconnected"indicates no device or software is connected to the MQ session."connected"indicates a device or software has established a permanent connection to the MQ session."connectedTemporarily"indicates a device or software has established a temporary connection to the MQ session. When the device or software disconnects, the server removes the data associated with the MQ session.
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 "publishedTopics" property returns a list of the topics the client has published since the session was first created.
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"
The "sessionType" property specifies which type of session the requested client is currently running. This property can return "mqApi", "mqtt", or "both".