Viewing the status of an IBM Watson IoT Platform - Message Gateway server and services by using REST Administration APIs

System administrators can display the status of the IBM® Watson IoT Platform - Message Gateway server and services by using REST Administration APIs.

About this task

You can use the IBM Watson IoT Platform - Message Gateway REST API GET method to display details about the status of the IBM Watson IoT Platform - Message Gateway server, including information about High Availability (HA), cluster membership, the protocol plug-in server process, the MQ Connectivity process, and SNMP. If IBM Watson IoT Platform - Message Gateway is running in a Docker container, the information that is returned also includes the Docker container UUID.

You can choose to display status information separately of the following services by using the IBM Watson IoT Platform - Message Gateway REST API GET method and specifying the name of the service:
  • Server
  • Cluster
  • High availability
  • MQ Connectivity process
  • Protocol plug-in server process
  • SNMP

Procedure

To display the status of an IBM Watson IoT Platform - Message Gateway server, use the IBM Watson IoT Platform - Message Gateway REST API GET method with the following URI:

http://<admin-endpoint-IP:Port>/ima/v1/service/status/<ServiceName>

where:
ServiceName
Optional.
Specifies the service name.
You can specify only one service name.
If no service name is specified, status information for the server and all services is returned.
Valid service names are:
  • Server

    Returns status information about the IBM Watson IoT Platform - Message Gateway server.

  • Cluster

    Returns cluster status information.

  • HighAvailability

    Returns HA status information.

  • MQConnectivity

    Returns MQ Connectivity process status information.

  • Plugin

    Returns protocol plug-in server process status information.

  • SNMP

    Returns SNMP status information.

Results

The following information is returned.
Note: Some status fields are returned only when the service is enabled and active.
Server status information:
Name
The user-specified name of the server.
If no name has been specified, the default is returned: the value of ServerUID if the server is a cluster member, or hostname:<AdminEndpointPort> if the server is not a cluster member.
UID
System-generated unique server identifier.
Status
Whether the server is running or stopped, or the stage that the server has reached during initialization. Possible values, and their meanings, are:
Running
The server is running.
Stopped
The server is stopped.
Initializing.
The server is initializing.
StoreStarting
The store is starting.
EngineStarting
The messaging engine is starting.
State
Numeric value that represents the state of the server.
StateDescription
Description of the state of the server. Each description corresponds to a value in the State status field. Possible values, and their meanings, are:
Initializing
The server is initializing.
Running (Production)
The server is running in production mode.
Stopping
The server is stopping.
Initialized
The server initialization process is complete.
TransportStarted
The transport layer in the server has started.
StoreStarted
The store has started
EngineStarted
The messaging engine has started.
MessagingStarted
The server is ready for message processing.
Running (Maintenance)
The server is running in maintenance mode.
Standby
The server is the standby server in an HA pair.
StoreStarting
The store is starting.
EngineStarting
The messaging engine is starting.
ServerTime
Current local time at the server.
UpTimeSeconds
Number of seconds that the server has been running since the last restart.
UpTimeDescription
The amount of time, expressed as days, hours, minutes, and seconds that the server has been running since the last restart.
Version
The build identifier and version of the server.
ErrorCode
The error code if the server is in an error state.
ErrorMessage
The error message that is associated with the error code if the server is in an error state.
Container
The Docker container UUID.
This field is returned only if the server is running in a Docker container.
Cluster status information:
Status
The status of the server in the cluster. Possible values, and their meanings, are:
Active
The server is a configured member of a cluster.
Inactive
The server is not a cluster member, or it is not enabled for cluster membership.
Standby
The server is the standby server in a clustered HA pair.
Enabled
Whether the server is enabled for cluster membership. For more information about configuring cluster membership, see Configuring the cluster membership of an IBM Watson IoT Platform - Message Gateway server. Possible values, and their meanings, are:
true
The server is enabled for cluster membership.
false
The server is not enabled for cluster membership.

If Status is Active, then the following fields are returned by the REST API GET method:

Name
The name of the cluster of which the server is a member.
ConnectedServers
The number of known cluster members that are currently active, and to which this server is able to connect.
DisconnectedServers
The number of known cluster members that this server is unable to connect to.
The server might be unable to connect to a known cluster member because the known cluster member is not running or is in maintenance mode, or there might be network connectivity problems.
HA status information:
Status
Whether HA is running or not. Possible values, and their meanings, are:
Active
HA is enabled and is running.
Inactive
HA is not running. If HA is enabled, the HA service attempts to restart if the server is restarted.
Enabled
Whether HA is enabled or not. For more information about configuring your system for high availability, see Configuring your system for high availability. Possible values, and their meanings, are:
true
HA is enabled.
false
HA is not enabled. The HA service does not attempt to restart if the server is restarted.

If Status is Active, then the following fields are returned by the REST API GET method:

Group
The name of the HA group to which the server belongs.
NewRole
The current role of the server in the HA pair. Possible values, and their meanings, are:
PRIMARY
The server is running as a primary node.
STANDBY
The server is running as the standby node.
HADISABLED
The server is disabled in the HA pair and is not restarted.
UNSYNC
The server is out of sync with the primary node. An attempt will be made to synchronize the server with the primary node.
UNSYNC_ERROR
The server has become unsynchronized due to an unrecoverable error.
UNKNOWN
If HA is enabled and the server is restarted, the initial role of the server is UNKNOWN until the role of the server is set during the synchronization process.
OldRole
The previous role of the server in the HA pair. Possible values, and their meanings, are:
PRIMARY
The server is running as a primary node.
STANDBY
The server is running as the standby node.
HADISABLED
The server is disabled in the HA pair and is not restarted.
UNSYNC
The server is out of sync with the primary node. An attempt will be made to synchronize the server with the primary node.
UNSYNC_ERROR
The server has become unsynchronized due to an unrecoverable error.
UNKNOWN
If HA is enabled and the server is restarted, the initial role of the server is UNKNOWN until the role of the server is set during the synchronization process.
ActiveNodes
The number of active nodes in the HA pair.
SyncNodes
The number of synchronized nodes in the HA pair.
PrimaryLastTime
The time when the server became the primary server in the HA pair.
This field is returned only on the primary server.
PctSyncCompletion
The progress, expressed as a percentage, that has been reached in the synchronization procedure on the primary node.
A value of -1 is presented if synchronization is not in process or if the server is not the primary server.
ReasonCode
The reason code if the server is in an error state.
MQ Connectivity process status information:
Status
The status of the MQ Connectivity process. Possible values, and their meanings, are:
Active
The MQ Connectivity process is running.
Inactive
The MQ Connectivity process is not running.
Enabled
Whether the MQ Connectivityprocess is enabled. You can enable and disable the MQ Connectivity process by setting the MQConnectivityEnabled configuration object. For more information, see Starting, restarting and stopping the MQ Connectivity process by using REST Administration APIs. Possible values, and their meanings, are:
true
The MQ Connectivity process is enabled.
false
The MQ Connectivity process is not enabled.
Protocol plug-in server status information:
Status
The status of the protocol plug-in server process. Possible values, and their meanings, are:
Active
The protocol plug-in server process is running.
Inactive
The protocol plug-in server process is not running.
Enabled
Whether the protocol plug-in server process is enabled. For more information about configuring a protocol plug-in, see Creating and updating a protocol plug-in. Possible values, and their meanings, are:
true
The protocol plug-in server process is enabled.
false
The protocol plug-in server process is not enabled.
SNMP status information:
Status
The status of the SNMP service. Possible values, and their meanings, are:
Active
SNMP is running.
Inactive
SNMP is not running.
Enabled
Whether SNMP is enabled. You can enable and disable SNMP by setting the SNMPEnabled configuration object. For more information, see Configuring SNMP. Possible values, and their meanings, are:
true
SNMP is enabled.
false
SNMP is not enabled.

Example

The following example shows a GET method to display the status of the IBM Watson IoT Platform - Message Gateway server by using cURL:

curl -X GET http://127.0.0.1:9089/ima/v1/service/status

The following example shows an example response to the GET method that was used to display the status of the IBM Watson IoT Platform - Message Gateway server:


{
  "Version":"v1",
  "Server": {
    "Name": "TestSystem:9089",
    "UID": "aFWxYf32",
    "Status": "Running",
    "State": 1,
    "StateDescription": "Running (production)",
    "ServerTime": "2016-03-04T14:46:53.081Z",
    "UpTimeSeconds": 4134,
    "UpTimeDescription": "0 days 1 hours 8 minutes 54 seconds",
    "Version": "2.0 20160304-0400",
    "ErrorCode": 0,
    "ErrorMessage": ""
  },
  "Container": {
    "UUID":"034c91ce828a4f5c2c21d7cd7f04628368b63bd308825ec2d9dab5096ff04ca0"
  },
  "HighAvailability": {
    "Status": "Inactive",
    "Enabled": false
  },  
  "Cluster": {
    "Status": "Inactive",
    "Enabled": false
  },  
  "Plugin": {
    "Status": "Inactive",
    "Enabled": false
  },  
  "MQConnectivity": {
    "Status": "Active",
    "Enabled": true
  },  
  "SNMP": {
    "Status": "Inactive",
    "Enabled": false
  }
}

The following example shows a GET method to display the status of only the IBM Watson IoT Platform - Message Gateway protocol plug-in server process by using cURL:

curl -X GET http://127.0.0.1:9089/ima/v1/service/status/Plugin

The following example shows an example response to the GET method that was used to display the status of the IBM Watson IoT Platform - Message Gateway protocol plug-in server process:


{ 
  "Version":"v1", 
  "Plugin": { 
    "Status": "Inactive",
    "Enabled": false
  }
}