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.
- Server
- Cluster
- High availability
- MQ Connectivity process
- Protocol plug-in server process
- SNMP
Procedure
http://<admin-endpoint-IP:Port>/ima/v1/service/status/<ServiceName>
- ServiceName
- Optional.
Results
- Name
- The user-specified name of the server.
- 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.
- 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.
- 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.
- PctSyncCompletion
- The progress, expressed as a percentage, that has been reached in the synchronization procedure on the primary node.
- ReasonCode
- The reason code if the server is in an error state.
- 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.
- 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.
- 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
}
}