Monitoring client connectivity

The IoT tool collects and stores information about client activity such as when a device connects, disconnects, or sends messages. Use the client connection state API to query the activity of one or many device clients.

As an example, you can get information on when a client was last active and why it became disconnected, or you can view all clients that did not connect in the past day so that you can address any issues.

For a detailed description of the API details, see the swagger documentation in your local API documentation. For more information about accessing the local documentation, see APIs.

In IBM® Maximo Monitor, replace workspaceId with your workspace or tenant ID.

Note: Brief delay might occur between the time that a client connects or disconnects and the time that the connection status from the API reflects the correct status. To receive live notifications over MQTT when a client connects or disconnects, use the device monitoring topic.

Activate and deactivate the client connection state API

You must activate the client connection state API feature before you can start querying.

To find the current activation status for the client connection state feature, use the GET /config/clientstate API call in your local API documentation. For more information about accessing the local documentation, see APIs.

If a 403 response is returned, the feature is not active.

Note: Deactivating the feature deletes any stored client activity status documents and all devices must send another update before the connection state can be determined if you reactivate the feature later.

Use one of the two following methods to activate client connection state API:

  • Set the enabled parameter to true by using the PUT /config/clientstate API call with the following application/JSON body. For more information, see your local API documentation. For more information about accessing the local documentation, see APIs.
  • On the Settings page of the IoT tool user interface, set Activate Client Connection State API to On.

Query client connection status

With the client connection state API, you can retrieve and query the connection status for any clients that are connected or were earlier connected to the IoT tool.

The connection status includes the following information:

  • The connectivity status: connected or disconnected.
  • The time of the last connection in ISO 8601 format.
  • The time of the last disconnection in ISO 8601 format.
  • The last activity event such as MQTT publish or MQTT subscribe.
  • The time of the last activity in ISO 8601 format.
  • The device that caused a disconnection: client, server, or network
  • The MQTT reason code for a disconnection.
  • The time of the last publish in ISO 8601 format.

Connection state query examples

The following examples illustrate some common connection state queries.

  • Retrieve the client connection status for a single client:
    GET /clientconnectionstates/{clientId}
  • Retrieve the connection status of all clients:
    GET /clientconnectionstates
  • Retrieve all connected clients:
    GET /clientconnectionstates?connectionStatus=connected
  • Retrieve all clients that were active within the past two days: GET /clientconnectionstates?connectedAfter={currentTime-2D}

For more information about the API, including all of the available query filters, see the Client Connection State API in your local API documentation. For more information about accessing the local documentation, see APIs.

Monitoring client connection status

A brief delay might occur between the time that a client connects and the time that the connection status from the API reflects the correct status.

If constant monitoring is required, you can subscribe to the monitor topic to receive live connectivity status updates for the client. For more information, see Communicating with applications (MQTT).

Limits

The number of stored recent client states is based on the connection type:

Type Stored client states
Applications 100
Gateways 10,000
Devices 1,000,000
Note: Connections that last a long time might eventually be removed as new connections are made.

Troubleshooting client connectivity issues

the IoT tool provides a per-device log of connection information, which you can use to diagnose device connectivity problems or to provide more context to the information that is provided by the monitoring topic or connecting status API.

The connection log provides information such as:

  • Connection
    • Time
    • Authentication
    • IP address
  • Disconnection
    • Time
    • Reason code (if available)
  • Throttling of message throughput

The connection log API returns up to the last 10 log messages for the devices.

For more information, see the Connection Logs API in your local API documentation. For more information about accessing the local documentation, see APIs.

SDKs with client connectivity HTTP APIs are available for Node.js and for Python.