Show server statistics by using REST Monitoring APIs

Purpose

URI

http://<admin-endpoint-IP:Port>/ima/v1/monitor/Server

Usage Notes

• The command must be capitalized as shown.
• This command returns the following statistics for all active endpoints:

  • Active connections

    The current count of connections that are open.

  • Total connections

    The total count of connections that were accepted by IBM Watson IoT Platform - Message Gateway since the server was started.

  • MsgRead

    The count of incoming messages on all connections.

  • MsgWrite

    The count of outgoing messages on all connections.

  • BytesRead

    The number of bytes of incoming data on all connections.

  • BytesWrite

    The number of bytes of outgoing data on all connections.

  • BadConnCount

    The count of client connections where a physical connection is established, but messages cannot be sent or received. This statistic includes connections where the following situations occur:

    • The connection times out without receiving data.
    • The SSL/TLS secure connection cannot be established.
    • The protocol is not known.
    • The protocol is not allowed for the endpoint.
    • A user name and password is required, but no user name and password is specified.
    • The user cannot be authenticated.
    • The user is not authorized to connect.

  • TotalEndpoints

    The number of active endpoints.

  • BufferedMessages

    This statistic provides an approximate count of the number of messages (including inflight messages) that are currently buffered on queues and subscriptions on the IBM Watson IoT Platform - Message Gateway server.

    You can use this information to understand:

    • If the number of buffered messages is growing, shrinking, or is constant over time.
    • If the number of buffered messages is higher than expected for your system at a point in time.
    • If your system is able to process the number of messages that are passing through it.

    You can also use this statistic in conjunction with the server memory usage statistics on the IBM Watson IoT Platform - Message Gateway Web UI dashboard to help with your capacity planning. Use this information to understand how many messages can be buffered on your server. For example, server memory usage might be at 50% with 4 million buffered messages, and at 60% with 8 million buffered messages.

  • RetainedMessages

    This statistic provides an approximate count of the number of retained messages (including inflight messages) that are currently waiting on topics on the IBM Watson IoT Platform - Message Gateway server. The messages are waiting to be delivered to new subscribers on those topics when their subscription is created for the first time.

    The RetainedMessages statistic does not represent the number of topics with a retained message, as a single topic might have multiple retained messages that are inflight.

    You can use this information to understand:

    • If the number of retained messages is growing, shrinking, or is constant over time.
    • If the number of retained messages is higher than expected for your system at a point in time.
    • If your system is able to process the number of messages that are passing through.

    You can also use this statistic in conjunction with the server memory usage statistics on the IBM Watson IoT Platform - Message Gateway Web UI dashboard to help with your capacity planning. Use this information to understand how many messages can be retained on the server. For example, the server memory usage might be at 50% with 4 million retained messages, and at 60% with 8 million retained messages.

  • ExpiredMessages

    This statistic provides a count of the number of expired messages on queues and subscriptions on the IBM Watson IoT Platform - Message Gateway server.

    You can use this information to understand:

    • If the number of expired messages is growing, shrinking, or is constant over time.
    • If the number of expired messages is higher than expected for your system at a point in time.
    • If your system is able to process the number of messages that are passing through it.

    You can also use this statistic in conjunction with the server memory usage statistics on the IBM Watson IoT Platform - Message Gateway Web UI dashboard to help with your capacity planning.

Related Commands

• Show topic related statistics by using REST Monitoring APIs

Example

The following example uses cURL to show how a GET method is used to view statistical information about server connections:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Server
 
 

The following example shows a successful example response to the GET method that was used to create statistical information about server connections:

{ "Version":"v1", "Server":  {"ActiveConnections":0,"TotalConnections":0,"MsgRead":0,"MsgWrite":0,"BytesRead":0,"BytesWrite":0,"BadConnCount":0,
"TotalEndpoints":3, "BufferedMessages":0,"RetainedMessages":0,"ExpiredMessages":0 }}