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
  }
}