Show cluster statistics by using REST Monitoring APIs

Purpose

Reports cluster monitoring statistics and information. 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.

URI

Use the Eclipse Amlen REST API GET method with the following Eclipse Amlen monitoring URI:

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

Usage Notes®

Capitalization must be used as shown.
The following fields are returned:
- 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
       }
     }
  ]
}