Viewing cluster information by using REST Monitoring APIs

System administrators can view cluster monitoring statistics by using REST Monitoring APIs.

System administrators can view information about cluster members by using REST Monitoring API, or by using the Amlen WebUI. For more information about using the Amlen WebUI to view cluster information, see Viewing cluster information by using the GUI.

When you use the REST Monitoring API to view clustering monitoring statistics, the information is returned as an array of entries where each entry represents the status of a remote cluster member and the messages that are sent to and received from that remote cluster member.

On a cluster member, use the Eclipse Amlen REST API GET method with the following Eclipse Amlen configuration URI:

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

The following fields are returned for each of the other cluster members that are in the same cluster as the cluster member on which you are issuing the REST Monitoring API:
  • Cluster
    Array
    Each object in the array is a cluster member in the same cluster as the cluster member on which you are issuing the REST Monitoring API.
  • ServerName
    String
    The user-assigned name of the cluster member.
  • ServerUID
    String
    The randomly-generated unique identifier of the cluster member. The same value applies to both servers in a high availability (HA) pair.
  • Status
    String
    The status of the cluster member.
    The value of the Status field can be one of the following values:
    • Active
      The cluster member is sending and receiving messages and cluster control information.
    • Inactive
      The remote server is known to have been a member of the cluster at a previous point but is not connected to the current cluster.
      A status of Inactive commonly means that the server is not running or that there are network problems.
    • Connecting
      The cluster member has been identified by Discovery but is not yet sending messages.
      Cluster members normally remain in Connecting state for a short time. If a cluster member remains in Connecting state, it is likely that its configuration is incorrect.
  • StatusTime
    Date/Time
    The date and time when the status of the cluster member last changed. Specified in ISO8601 format.
    Status time information is useful in identifying cluster members that are inactive for long periods, and cluster members that frequently change state.
  • Health
    String
    An indication of the health of the cluster member. The health of the cluster member is primarily based on the amount of memory that is available on the cluster member.
    The value of the Health field can be one of the following values:
    • Unknown
      The health of the cluster member is unknown.
      A status of Unknown can be returned when the cluster member is not running but can also indicate that there is a problem with the network or configuration..
    • Green
      The health of the cluster member is good. The cluster member has sufficient memory to process messaging traffic.
    • Yellow
      A Health status of Yellow is a warning that the health of the cluster member is becoming bad.
      The cluster member is getting low on memory and will start to take actions to limit the amount of memory that is being used.
      Administer the cluster member to determine the cause of the low memory condition and take appropriate remedial action.
    • Red
      A Health status of Red indicates that the health of the cluster member is bad.
      The cluster member is low on memory and will start to take actions to limit the amount of memory that is being used. Such actions include discarding QoS1 and QoS2 messages.
      Administer the cluster member to determine the cause of the low memory condition and take appropriate remedial action.
  • Memory
    Numeric
    The percentage of memory that is being used on the cluster member.
  • HAStatus
    String
    The high availability (HA) status of the cluster member.
    The value of the HAStatus field can be one of the following values:
    • Unknown
      The HA status of the cluster member is unknown.
      A status of Unknown can be returned when there is no messaging traffic between this cluster member and the remote cluster member.
    • None
      The cluster member is not configured for HA.
    • Single
      The cluster member is configured as a member of an HA pair but is running without a standby.
    • Pair
      The cluster member is running as a member of an HA pair.
    • Error
      The cluster member is configured as a member of an HA pair but HA status of the cluster member is in error.
  • RetainedSync
    Boolean
    Indicates whether the cluster member has retained messages synchronized.
    A value of false indicates that the cluster member does not have retained messages synchronized; this is normal for a short time after a cluster member becomes active. A value of false that persists for longer than approximately 10 minutes might indicate that the cluster member is experiencing problems or that there is a problem with the communication between the remote cluster member and this cluster member. If a value of false persists for 30 minutes, the cluster members attempt to resynchronize retained messages automatically.
  • Reconnect
    Numeric
    The number of times the connection used for messaging between the remote cluster member and this cluster member has been re-established. If the remote cluster member goes down, the count is incremented by 2. A high value might indicate that the cluster member or the network is unstable.
  • ReadMsgs
    Numeric
    The number of incoming messages that are received from the remote cluster member.
    The value is reset when the cluster member starts.
  • ReadBytes
    Numeric
    The number of bytes in the incoming messages that are received from the remote cluster member.
    The value is reset when the cluster member starts.
  • WriteMsgs
    Numeric
    The number of outgoing messages that are sent to the remote cluster member.
    The value is reset when the cluster member starts.
  • WriteBytes
    Numeric
    The number of bytes in the outgoing messages that are sent to the remote cluster member.
    The value is reset when the cluster member starts.
  • ReadMsgRate
    Numeric
    The number of messages per second that are received from the remote cluster member.
  • Unreliable
    Queue object
    The information relates to unreliable messaging (QoS 0) from this cluster member to remote cluster members.
  • Reliable
    Queue object
    The information relates to reliable messaging (QoS 1 or QoS2) from this cluster member to remote cluster members.
The following information is returned for each of the two messaging types (unreliable and reliable) that are used to send messages from this cluster member to remote cluster members:
  • BufferedMsgs
    Numeric
    The number of messages that are currently awaiting delivery to the remote cluster member.
  • BufferedMsgsHWM
    Numeric
    The highest number of messages that awaited delivery to the remote cluster member.
  • BufferedBytes
    Numeric
    The number of bytes that are awaiting delivery to the remote cluster member.
  • MaxBytes
    Numeric
    The maximum number of bytes that are allowed for buffered messages.
  • SentMsgs
    Numeric
    The number of messages that have been successfully sent to the remote cluster member.
    For messages of QoS 1 or QoS 2, the count is incremented only after the message transfer is committed.
    The value is reset when the cluster member starts.
  • MsgSendRate
    Numeric
    The number of messages per second sent to the remote cluster member. This value represents the current rate of transmission.
  • DiscardedMsgs
    The number of messages that were discarded because the buffered data limit was reached. Refer to the value that is displayed in the MaxBytes field.
    The value is reset when the cluster member starts.
  • ExpiredMsgs
    Numeric
    The number of messages that were discarded because they exceeded the expiration time.
    The value is reset when the cluster member starts.
  • Suspend
    Numeric
    The number of messages that were suspended from being sent to the remote cluster member. In certain circumstances, messages are suspended when the remote cluster member cannot receive messages as quickly as this cluster member is sending them. Suspending the sending of messages allows the remote cluster member to process the messages that it has already received so that it can then continue to receive messages.
    A high suspend count indicates that the remote cluster member is having problems keeping up with the message rate from this cluster member.
    The value is reset when the cluster member starts.

The following example uses cURL to show how a GET method is used to create the most recent statistics about cluster members in a cluster that comprises 3 cluster members. The REST API GET method is used on cluster member server01.example.com. The information that is returned shows the status of cluster members server02.example.com and server03.example.com and also information about the flow of messages between server01.example.com and the 2 other cluster members. 

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

The following example shows a successful example response to the GET method that was used in the previous example. In this example, there is no active messaging traffic; consequently, the values for the rates are zero. 


{
  "Version": "v1",
  "Cluster": [
    {
       "ServerName": "server02.example.com",
       "ServerUID": "L8QUhQJZ",
       "Status": "Active",
       "StatusTime": "2015-12-09T15:54:52Z",
       "Health": "Green",
       "Memory": 0,
       "HAStatus": "None",
       "RetainedSync": true,
       "Reconnect": 4,
       "ReadMsg": 1048,
       "ReadBytes": 51836,
       "WriteMsg": 929,
       "WriteBytes": 46084,
       "ReadMsgRate": 0,
       "Reliable": {
         "BufferedMsgs": 0,
         "BufferedMsgsHWM": 16,
         "BufferedBytes": 0,
         "MaxBytes": 0,
         "SentMsgs": 357,
         "MsgSendRate": 0,
         "DiscardedMsgs": 0,
         "ExpiredMsgs": 0,
         "Suspend": 0
      },
       "Unreliable": {
         "BufferedMsgs": 0,
         "BufferedMsgsHWM": 1,
         "BufferedBytes": 0,
         "MaxBytes": 0,
         "SentMsgs": 567,
         "MsgSendRate": 0,
         "DiscardedMsgs": 0,
         "ExpiredMsgs": 0,
         "Suspend": 0
       }
     },
     {
       "ServerName": "server03.example.com",
       "ServerUID": "e5xZvtVd",
       "Status": "Active",
       "StatusTime": "2015-12-09T15:54:56Z",
       "Health": "Green",
       "Memory": 0,
       "HAStatus": "None",
       "RetainedSync": true,
       "Reconnect": 4,
       "ReadMsg": 1569,
       "ReadBytes": 94550,
       "WriteMsg": 2056,
       "WriteBytes": 101198,
       "ReadMsgRate": 0,
       "Reliable": {
         "BufferedMsgs": 0,
         "BufferedMsgsHWM": 15,
         "BufferedBytes": 0,
         "MaxBytes": 0,
         "SentMsgs": 616,
         "MsgSendRate": 0,
         "DiscardedMsgs": 0,
         "ExpiredMsgs": 0,
         "Suspend": 0
      },
       "Unreliable": {
         "BufferedMsgs": 0,
         "BufferedMsgsHWM": 1,
         "BufferedBytes": 0,
         "MaxBytes": 0,
         "SentMsgs": 1440,
         "MsgSendRate": 0,
         "DiscardedMsgs": 0,
         "ExpiredMsgs": 0,
         "Suspend": 0
       }
     }
  ]
}