Subscribing to event message topics

You can subscribe to topics that return messages about the configuration, state, or operational status of your integration node, integration server, or message flows.

About this task

A subscriber can send a subscription request to the pub/sub broker that specifies the event messages that the subscriber wants to receive. To receive IBM® Integration Bus event messages, use the following information to define the subscription requests.

The IBM Integration Bus event messages are published with a reserved topic root:

For an MQTT pub/sub broker, the topic root is IBM/IntegrationBus. For example,

IBM/IntegrationBus/integrationNodeName/Status/ExecutionGroup/integrationServerName

For an MQ pub/sub broker, the topic root is $SYS/Broker. For example,

$SYS/Broker/integrationNodeName/Status/ExecutionGroup/integrationServerName

Note: You can use wildcards when you subscribe to statistics reports. For example, to receive message flow statistics reports for all integration nodes and all integration servers, subscribe to the following topic:

topicRoot/+/StatisticsAccounting/#

where topicRoot is IBM/IntegrationBus for an MQTT pub/sub broker and $SYS/Broker for an MQ pub/sub broker. For more information about how you can use wildcards, see Special characters in topics.

You can subscribe to IBM Integration Bus messages in the following categories:

Message flow performance

If you enable message flow accounting and statistics collection for an integration node, the integration node publishes messages (JSON or XML publications) at an interval that you can control by setting the statsInterval property of the integration node. You can subscribe to these messages on the following topics:

For JSON publications:

topicRoot/integrationNodeName/Statistics/JSON/recordType/integrationServerName/messageFlowName

For XML publications:

topicRoot/integrationNodeName/StatisticsAccounting/recordType/integrationServerName/messageFlowName

where recordType specifies the type of record (SnapShot or Archive).

Note: For an MQ pub/sub broker, each message is a JMS TextMessage that contains the statistics report in XML format. If you want the message in a JMS BytesMessage format, use one of the following methods:

Set the environment variable MQSI_STATS_MQSTR=false.
Run the mqsichangeproperties command with the pubsub component to change the format. For example:
```
mqsichangeproperties IBNODE -b pubsub -o OperationalEvents/MQ -n format -v none
```
The pubsub component change overrides the use of environment variables. For more information, see Parameter values for the pubsub component.

Resource performance

If you enable resource statistics collection for one or more integration servers on an integration node, the integration node publishes messages (JSON or XML publications) at 20-second intervals. You can subscribe to these messages on the following topics:

For JSON publications:

topicRoot/integrationNodeName/Statistics/JSON/Resource/integrationServerName

For XML publications:

topicRoot/integrationNodeName/ResourceStatistics/integrationServerName

Note: For an MQ pub/sub broker, each message is a JMS TextMessage that contains the resource statistics report in XML format. If you want the message in a JMS BytesMessage format, use one of the following methods:

Set the environment variable MQSI_STATS_MQSTR=false.
Run the mqsichangeproperties command with the pubsub component to change the format.

For more information about how to interpret the resource statistics that are included in the publication, see Viewing resource statistics data.

Configuration changes

The integration node publishes messages (XML publications) when an entity is created, changed, or deleted on an integration server. You can subscribe to these messages on the following topic:

topicRoot/integrationNodeName/Configuration/ExecutionGroup/integrationServerName

For an example message, see Example: changes to the local configuration of the integration node.

State changes

The integration node publishes messages (XML publications) when an integration node, integration server, or message flow stops or starts. You can subscribe to these messages on the following topics:

State changes associated with an integration node:
```
topicRoot/integrationNodeName/Status
```
State changes associated with an integration server (including state changes to resources that are deployed to an integration server):
```
topicRoot/integrationNodeName/Status/ExecutionGroup/integrationServerName
```

For an example message, see Example: changes to state of an integration node or message flow.

Workload management

The message rate statistics are collected at a checkpoint that occurs every 20 seconds. The total message rate is calculated at this checkpoint, and if the total message rate exceeds the notification threshold, the out of range XML message is published. If the total message rate continues to stay above the notification threshold, then no further out of range messages are published.

If you enable the notification threshold, you can subscribe to the following topics:

Message flow is in a library within an application:

topicRoot/integrationNodeName/WorkloadManagement/AboveThreshold/integrationServerName/applicationName/libraryName/messageFlowName

Message flow is in a library that is not within an application:

topicRoot/integrationNodeName/WorkloadManagement/AboveThreshold/integrationServerName/libraryName/messageFlowName

Message flow is directly in an application (not in a library within the application):

topicRoot/integrationNodeName/WorkloadManagement/AboveThreshold/integrationServerName/applicationName/messageFlowName

Message flow is not in an application or a library:

topicRoot/integrationNodeName/WorkloadManagement/AboveThreshold/integrationServerName/messageFlowName

Monitoring

You can configure your message flow to emit event messages that can be used to support transaction monitoring and auditing, and business process monitoring; see Configuring monitoring for message flows. To receive event messages from your message flows, subscribe to the following topic:

topicRoot/Monitoring/integrationServerName/messageFlowName

Note: When you use the built-in MQTT pub/sub broker, Monitoring events are not published by default. You must enable the publication of Monitoring events to the built-in MQTT pub/sub broker.

Results

Subscribers receive statistics reports only from those integration nodes that are enabled to produce statistics.