Show topic related statistics by using REST Monitoring APIs

Purpose

Reports topic-related monitoring data for topics that have been defined in topic monitors.

URI

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

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

Object configuration data

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.
    The default value is PublishedMsgsHighest.

Usage Notes

  • 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.
  • Before you can monitor a topic, you must create a topic monitor that specifies the topic string that you want to monitor. After you create the topic monitor, statistics about the topic string are recorded. You can create topic monitors by using REST Monitoring APIs. For more information about creating topic monitors, see Viewing topic monitoring statistics by using REST Monitoring APIs.
  • If the Eclipse Amlen server is restarted, monitored topic data is reset.
  • To reset the monitoring data for a particular topic string, you must delete and re-create the topic monitor.
  • 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
      Date/Time
      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.

Example

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