Show endpoint level statistics by using REST Monitoring APIs

Purpose

URI

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

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

Object configuration data

Provide endpoint object configuration data in the payload of the GET method by using the following schema. Content-type is set to application/json:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Endpoint?Name=EndpointName%26SubType=SubType%26Duration=Duration%26Monitoring-DataType=Monitoring-DataType

Name

Specifies the name of the endpoint to return statistics about.

If a name is not specified, aggregate statistics for all endpoints are returned.

SubType

Specifies the monitoring data to report.

This value can be one of the following values:

• Current®

  View the most recent statistics.

• History

  View older statistics.

The default value is Current.

Duration

Specifies the time span, in seconds, of the data to be reported.

The value must be in the range 1-86400.

The default value is 1800.

Monitoring-DataType

Specifies the type of data to order the results by.

This value can be one of the following values:

• ActiveConnections

  Orders the monitoring data by the number of connections that are active on the endpoint.

  This value is the default value.

• Connections

  Orders the monitoring data by the count of connections to the endpoint since Eclipse Amlen was last reset.

• BadConnections

  Orders the monitoring data by the count of failed connections to the endpoint since Eclipse Amlen was last reset.

• LostMsgs

  Orders the monitoring data by the count of messages that, when published, resulted in an error on the endpoint since Eclipse Amlen was last reset.

• ReadMsgs

  Orders the monitoring data by the count of the messages read on the endpoint since Eclipse Amlen was last reset.

• ReadBytes

  Orders the monitoring data by the count of the number of bytes read on the endpoint since Eclipse Amlen was last reset.

• WarnMsgs

  Orders the monitoring data by the count of messages that, when published, resulted in a warning on the endpoint since Eclipse Amlen was last reset.

• WriteMsgs

  Orders the monitoring data by the count of the number of messages that written on the endpoint since Eclipse Amlen was last reset.

• WriteBytes

  Orders the monitoring data by the count of the number of bytes written on the endpoint since Eclipse Amlen was last reset.

Usage Notes®

• Encode special endpoints that start with the character ! with %21 when using the REST API GET method.
• The command must be capitalized as shown.
• The command must use the double quotation marks as shown.
• The statistics that are produced can be up to 60 seconds out of date.
• The following fields are returned:

  • Name

    String

    The name of the endpoint.

  • IPAddr

    String

    The network interface address to which the endpoint is bound.

  • Enabled

    Boolean

    Indicates whether the endpoint is enabled. If the endpoint is enabled and the LastErrorCode is zero, this indicates that the endpoint is accepting connections.

  • Total

    Numeric

    The number of connections that completed through to the protocol handshake since configuration time.

  • Active

    Numeric

    The number of connections that are currently active.

  • Messages

    Numeric

    The number of messages that are sent or received since configuration time.

  • Bytes

    Numeric

    The number of bytes that are sent and received since configuration time.

  • LastErrorCode

    String

    This value provides an indication of the success of the last configuration of the endpoint. An endpoint is working if Enabled=1 and LastErrorCode=0. For more information about error codes, see Message catalog.

  • ConfigTime

    Date/time

    The time of the last major configuration of an endpoint and the time at which the statistics were reset. The ConfigTime is usually the time at which the endpoint is first enabled. If the endpoint is deleted and recreated, then the configuration time is updated. The ConfigTime is used by monitoring applications that keep time series statistics so that any discontinuity is identifiable.

  • BadConnections

    Numeric

    The count of connections that failed before the protocol handshake completed.

Example

The following example uses cURL to show how a GET method is used to create the most recent statistics for all endpoints:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Endpoint?SubType=Current  
 
 

The following example shows a successful example response to the GET method that was used to create the most recent statistics for all endpoints:

{ 
    "Version":"v1", 
      "Endpoint": [ 
        {
          "Name":"DemoEndpoint","IPAddr":"ALL","Enabled":false,"Total":0,"Active":0,
          "Messages":0,"Bytes":0,"LastErrorCode":0,
          "ConfigTime":"2015-12-11T18:29:15.519Z","ResetTime":"1970-01-01T00:00:00.000Z","BadConnections":0
        },
        {
          "Name":"DemoMqttEndpoint","IPAddr":"ALL","Enabled":false,"Total":0,"Active":0,
          "Messages":0,"Bytes":0,"LastErrorCode":0,
          "ConfigTime":"2015-12-11T18:29:15.519Z","ResetTime":null,"BadConnections":0
        },
        {
          "Name":"!MQConnectivityEndpoint","IPAddr":"/var/messagesight/data/MQConnectivityEndpoint_34109b4a50a7",
          "Enabled":true, "Total":0,"Active":0,"Messages":0,"Bytes":0,"LastErrorCode":0,
          "ConfigTime":"2016-04-27T16:42:33.464-05:00","ResetTime":null,"BadConnections":0
        } 
      ]  }

The following example uses cURL to show how a GET method is used to create the most recent statistics about an endpoint called DemoEndpoint:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Endpoint?Name=DemoEndpoint%26SubType=Current  
 
 

The following example shows a successful example response to the GET method that was used to create the most recent statistics about an endpoint called DemoEndpoint:

{ "Version":"v1", "Endpoint": [ {
    "Name":"DemoEndpoint","IPAddr":"ALL","Enabled":false,"Total":0,"Active":0,"Messages":0,"Bytes":0,"LastErrorCode":0,
"ConfigTime":"2015-12-11T18:29:15.519Z","ResetTime":"1970-01-01T00:00:00.000Z","BadConnections":0 } ]

The following example uses cURL to show how a GET method is used to create statistics about an internal pre-configured endpoint, !MQConnectivityEndpoint:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Endpoint?Name=%21MQConnectivityEndpoint 
 
 

The following example shows a successful example response to the GET method that was used to create statistics about !MQConnectivityEndpoint:

{ 
"Version":"v1", "Endpoint": [ { "Name":"!MQConnectivityEndpoint","IPAddr":"127.0.0.1",
"Enabled":true,"Total":0,"Active":0,"Messages":0,"Bytes":0,"LastErrorCode":0,"ConfigTime":"2016-04-27T16:42:33.464-05:00",
"ResetTime":null,"BadConnections":0 }]
}