Viewing topic monitoring statistics by using REST Monitoring APIs

System administrators can view topic-related statistics by using a REST Monitoring API.

The system administrator can reset the topic monitor data to zero either by stopping and restarting the Eclipse Amlen server, or by deleting and re-creating a specific topic string.

If the Eclipse Amlen server is restarted, then all monitored topic data is set to zero.

For more information about restarting the Eclipse Amlen server, see Starting and stopping the server.

If you want to set individual topic data to zero, then you must delete and re-create individual topic strings.

For more information about deleting and re-creating a topic string by using a REST Monitoring API, see step 1 in the following task information.

System administrators can view topic-related statistics by using a REST Monitoring API, by using the Amlen WebUI, or by using an external monitoring application. For more information about using the Amlen WebUI to view topic-related statistics, see Viewing topic-related statistics by using the GUI. For more information about using an external application to view topic-related statistics, see Viewing topic-related statistics by using an external application.

You must create a set of topics to monitor.
- To view the topics that you are monitoring, use the Eclipse Amlen REST API GET method with the following Eclipse Amlen URI:
```
http://<admin-endpoint-IP:Port>/ima/v1/configuration/TopicMonitor
```
- To add a topic string to the list of topics that you want to monitor, use the Eclipse Amlen REST API POST method with the following Eclipse Amlen URI:
```
http://<admin-endpoint-IP:Port>/ima/v1/configuration/ 
```
  and provide TopicMonitor object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json:
```
{"TopicMonitor":["TopicString/#"]}       
```
  where:
  - TopicString
    
    Specifies the name of the topic string that you want to add.
    
    The string must end with a multi-level wildcard (#), must contain no other wildcards, and must not start with $SYS. For example, EXAMPLE/L2/#. You can specify only the multi-level wildcard (#) to monitor all topics. To monitor a single topic, that topic must have no child topics. For example, /animals/dogs/labradors/# monitors only the topic /animals/dogs/labradors if labradors has no child topics.
- To remove a topic string from the list of topics that you are monitoring, use the Eclipse Amlen REST API DELETE method with the following Eclipse Amlen URI:
```
http://<admin-endpoint-IP:Port>/ima/v1/configuration/TopicMonitor/TopicString
```
where
- TopicString
  
  Specifies the name of the topic string that you want to remove.
Use the Eclipse Amlen REST API GET method with the following Eclipse Amlen monitoring URI:

http://<admin-endpoint-IP:Port>/ima/v1/monitor/Topic
Provide query parameters requesting the statistics that you want returned in the JSON payload. The following example uses cURL to create topic-related statistics:
```
curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Topic?TopicString=TopicString%26ResultCount=ResultCount%26Monitoring-DataType=Monitoring-DataType
```
where:
- TopicString
  
  Optional.
  
  TopicString is a filter, which you can use to match specific topic strings. TopicString can contain wildcards (*) to match 0 or more characters. The default value is *.
- ResultCount
  
  Optional.
  
  Specifies the maximum number of results to return. Options available for selection are 10, 25, 50, and 100. The default value is 25. If the number of topics that are being monitored is less than the Count specified, then only those topics that are being monitored are returned.
  
  Specifies the number of results to display.
- Monitoring-DataType
  
  Optional.
  
  Specifies the type of data to order the results by.
  This value can be one of the following values:
  
  PublishedMsgsHighest
  
  Topics with the most publications.
  
  PublishedMsgsLowest
  
  Topics with the least publications.
  
  SubscriptionsHighest
  
  Topics with the most subscribers.
  
  SubscriptionsLowest
  
  Topics with the least subscribers.
  
  RejectedMsgsHighest
  
  Topics with the most rejected messages.
  
  RejectedMsgsLowest
  
  Topics with the least rejected messages.
  
  FailedPublishesHighest
  
  Topics with the most rejected publishes.
  
  FailedPublishesLowest
  
  Topics with the least rejected publishes.
  
  AllUnsorted
  
  Lists all topics.
  
  Any value that is specified for ResultCount is ignored, so setting StatType to AllUnsorted can result in a large number of responses being generated.
  The default value is PublishedMsgsHighest.

The following fields are returned:

TopicString

String

The topic that is being monitored. The topic string always contains a wildcard.
Subscriptions

Numeric

The number of active subscriptions on the topics that are monitored. The figure shows all active subscriptions that match the wildcarded topic string.
ResetTime

String

The time at which the statistics for the topic were reset. The ResetTime is usually the time when the topic monitor is created.
PublishedMsgs

Numeric

The number of messages that are successfully published to a topic that matches the wildcarded topic string.
RejectedMsgs

Numeric

The number of messages that are rejected by one or more subscriptions where the quality of service level did not cause the publish request to fail.
FailedPublishes

Numeric

The number of publish requests that failed because the message is rejected by one or more subscriptions.

The following example uses cURL to create a topic monitor. This example shows you how to create two topic monitors in a single request:


curl -X POST \
   -H "Content-Type: application/json" \
   -d ' {
          "TopicMonitor": ["/p1/#","/p2/#"]
        }
      ' \
http://127.0.0.1:9089/ima/v1/configuration

The following example shows a successful example response to the GET method that was used to create two topic monitors in a single request:

{ "Version":"v1","Code":"CWLNA6011","Message":"The requested configuration change has completed successfully." }

The following example uses cURL to show how a GET method is used to create statistics about topics with the highest number of published messages:

 curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Topic?TopicString=*%26Monitoring-DataType=PublishedMsgsHighest

The following example shows a successful example response to the GET method that was used to create statistics about topics with the highest number of published messages::

{ "Version":"v1", "Topic": [ { "TopicString":"ROOT/#","Subscriptions":5,"ResetTime":"0","PublishedMsgs":50,
"RejectedMsgs":4,"FailedPublishes":2,"ResultCount":10 } ] }