Show subscription related statistics by REST Monitoring APIs

Purpose

Reports subscription-related monitoring data.

URI

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

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

Object configuration data

Provide query parameters requesting the statistics that you want returned in the JSON payload. The following example uses cURL to create subscription-related statistics:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/
Subscription?SubName=SubName%26SubType=SubType%26ClientID=ClientID
%26TopicString=TopicString%26ResultCount=ResultCount%26StatType=StatType
%26MessagingPolicy=MessagingPolicy
where:
SubName
Specifies the name of a subscription to collect data about.
You can use an asterisk (*) to match 0 or more characters.
The default value is *
TopicString
Specifies a topic to collect subscription data about.
You can use an asterisk (*) to match 0 or more characters.
The default value is *
ClientID
Specifies a client ID to collect subscription data about.
You can use an asterisk (*) to match 0 or more characters.
The default value is *
MessagingPolicy
Specifies a messaging policy to collect subscription data about.
You can use an asterisk (*) to match 0 or more characters.
The default value is *
ResultCount
Specifies the maximum number of results to return
This value can be one of the following values: 10, 25, 50, 100.
The default value is 25.
SubType
Specifies the type of subscription to collect monitoring data about.
This value can be one of the following values:
  • Durable
    Returns monitoring data only for durable subscriptions.
  • Nondurable
    Returns monitoring data only for non-durable subscriptions.
  • All
    Returns monitoring data for both durable and non-durable subscriptions.
The default value is All.
StatType
Specifies the type of data to order the results by.
This value can be one of the following values:
  • PublishedMsgsHighest
    Orders the monitoring data by the subscriptions receiving the highest number of messages.
    This value is the default value.
  • PublishedMsgsLowest
    Orders the monitoring data by the subscriptions receiving the lowest number of messages.
  • BufferedMsgsHighest
    Orders the monitoring data by the subscriptions with the highest number of buffered messages.
  • BufferedMsgsLowest
    Orders the monitoring data by the subscriptions with the lowest number of buffered messages.
  • BufferedPercentHighest
    Orders the monitoring data by the subscriptions with the highest relative number of buffered messages as a percentage of the total number of messages that can be buffered.
    The MaxMessages value in the messaging policy for a subscription defines the maximum number of messages that can be buffered.
  • BufferedPercentLowest
    Orders the monitoring data by the subscriptions with the lowest relative number of buffered messages as a percentage of the total number of messages that can be buffered.
    The MaxMessages value in the messaging policy for a subscription defines the maximum number of messages that can be buffered.
  • BufferedHWMPercentHighest
    Orders the monitoring data by the subscriptions with the highest peaks of buffered messages as a percentage of the total number of messages that can be buffered.
    The MaxMessages value in the messaging policy for a subscription defines the maximum number of messages that can be buffered.
  • BufferedHWMPercentLowest
    Orders the monitoring data by the subscriptions with the lowest peaks of buffered messages as a percentage of the total number of messages that can be buffered.
    The MaxMessages value in the messaging policy for a subscription defines the maximum number of messages that can be buffered.
  • RejectedMsgsHighest
    Orders the monitoring data by the subscriptions with the highest number of rejected messages.
  • RejectedMsgsLowest
    Orders the monitoring data by the subscriptions with the lowest number of rejected messages.
  • DiscardedMsgsHighest
    Orders the monitoring data by the subscriptions with the highest number of discarded messages. Discarded messages are messages that could not be published to a subscription because the buffer is full.
  • DiscardedMsgsLowest
    Orders the monitoring data by the subscriptions with the lowest number of discarded messages. Discarded messages are messages that could not be published to a subscription because the buffer is full.
  • ExpiredMsgsHighest
    Orders the monitoring data by the subscriptions with the highest number of expired messages.
  • ExpiredMsgsLowest
    Orders the monitoring data by the subscriptions with the lowest number of expired messages.

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.
  • The following fields are returned:
    • SubName
      String
      The name that is associated with the subscription. This value can be an empty string for a non-durable subscription.
    • TopicString
      String
      The topic on which the subscription is subscribed.
    • ClientID
      String
      The Client ID of the client that owns the subscription.
    • IsDurable
      Boolean
      This value indicates whether the subscription is durable or non-durable. Durable subscriptions survive server restarts unless the subscription is explicitly deleted.
    • BufferedMsgs
      Numeric
      The number of published messages that are waiting to be sent to the client.
    • BufferedMsgsHWM
      Numeric
      The highest number of published messages since the server was started or the subscription was created, whichever is most recent.
    • BufferedPercent
      Numeric
      The percentage of the maximum buffered messages that the current buffered messages represent.
    • MaxMessages
      Numeric
      The maximum number of buffered messages that are allowed for this subscription. This value is a guideline, rather than an absolute limit. If the system is running under stress, then the number of buffered messages on a subscription might be slightly higher than the MaxMessages value.
    • PublishedMsgs
      Numeric
      The number of messages that are published to this subscription since the server was started or the subscription was created, whichever is most recent.
    • RejectedMsgs
      Numeric
      The number of messages that are rejected because the maximum number of buffered messages was reached when the messages were published to the subscription.
    • BufferedHWMPercent
      Numeric
      The peak number of buffered messages, as a percentage of the maximum number of messages that can be buffered.
    • IsShared
      Boolean
      This value indicates whether the subscription is shared.
    • Consumers
      Numeric
      The number of consumers that the subscription has.
    • DiscardedMsgs
      Numeric
      The number of messages that are not delivered because they were discarded when the buffer became full.
    • ExpiredMsgs
      Numeric
      The number of messages that are not delivered because they expired.
    • MessagingPolicy
      String
      The messaging policy that is in use by the subscription.

Example

The following example uses cURL to show how a GET method is used to create statistics about subscriptions that are subscribed to a topic called DemoTopic:

curl -X GET http://127.0.0.1:9089/ima/v1/monitor/Subscription?TopicString=DemoTopic

The following example shows a successful example response to the GET method that was used to create statistics about subscriptions that are subscribed to a topic called DemoTopic:

{ "Version":"v1", "Subscription": [{"SubName":"DemoSubscription","TopicString":"DemoTopic","ClientID":"Demo ID","IsDurable":"True","BufferedMsgs":0,
"BufferedMsgsHWM":0,"BufferedPercent":0.0,"MaxMessages":5123,"PublishedMsgs":0,"RejectedMsgs":0,"BufferedHWMPercent":0.0,
"IsShared":"False","Consumers":1,"DiscardedMsgs":0,"ExpiredMsgs":0, "MessagingPolicy":"DemoTopicPolicy }] }