Viewing subscription-related statistics by using REST Monitoring APIs

System administrators can view subscription-related statistics by using REST Monitoring APIs.

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

Subscription-related monitoring statistics can be viewed by using a REST Monitoring API. To create subscription-related monitoring statistics, complete the following steps:
  1. Use the Eclipse Amlen REST API GET method with the following Eclipse Amlen configuration URI:

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

  2. 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
      The subscription name is the name that is associated with the subscription.

      Asterisk * matches 0 or more characters.

      The default value is *.

    • TopicString
      The topic string is the name of the topic that the subscription is subscribed to.

      Asterisk * matches 0 or more characters.

      The default value is *.

    • ClientID
      Specifies the client ID. The client ID is the id of the client that owns the subscription.

      Asterisk * matches 0 or more characters.

      The default value is *.

    • 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. Durable subscriptions survive a server restart unless the subscription is deleted.
      • Nondurable
        Returns monitoring data only for non-durable subscriptions. Non-durable subscriptions do not survive a server restart.
      • 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
        Subscriptions that receive the highest number of messages.
      • PublishedMsgsLowest
        Subscriptions that receive the lowest number of messages.
      • BufferedMsgsHighest
        Subscriptions with the highest number of published messages that are waiting to be sent to the client.
      • BufferedMsgsLowest
        Subscriptions with the lowest number of published messages that are waiting to be sent to the client.
      • BufferedPercentHighest
        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. 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.
      • BufferedPercentLowest
        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
        Subscriptions with the highest peaks of buffered messages as a percentage of the total number of messages that can be buffered. That is, the subscriptions that have come closest to reaching the maximum messages limit.
        The MaxMessages value in the messaging policy for a subscription defines the maximum number of messages that can be buffered.
      • BufferedHWMPercentLowest
        Subscriptions with the lowest peaks of buffered messages as a percentage of the total number of messages that can be buffered. That is, the subscriptions that have stayed furthest from the maximum messages limit.
        The MaxMessages value in the messaging policy for a subscription defines the maximum number of messages that can be buffered.
      • RejectedMsgsHighest
        Subscriptions with the highest number of rejected messages. Rejected messages are messages that could not be published to a subscription because the maximum number of buffered messages is reached.
      • RejectedMsgsLowest
        Subscriptions with the lowest number of rejected messages. Rejected messages are messages that could not be published to a subscription because the maximum number of buffered messages is reached.
      • DiscardedMsgsHighest
        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
        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
        Subscriptions with the highest number of expired messages.
      • ExpiredMsgsLowest
        Subscriptions with the lowest number of expired messages.
      • AllUnsorted
        Lists all durable and non-durable subscriptions.
        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.
    • ResultCount
      Specifies the number of results to display.

      Options available for selection are 10, 25, 50, and 100.

      The default value is 25.

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 buffered 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.
  • 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 name of the messaging policy that is in use by the subscription.
    For a globally shared subscription this will be a subscription policy name, otherwise it will be a topic policy name.
    Asterisk * matches 0 or more characters.
    The default value is *.

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