Subscribing to event message topics

You can subscribe to topics that return messages about the configuration, state, or operational status of your integration server, integration node, 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.

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 IBM MQ pub/sub broker. For more information about how you can use wildcards, see Special characters in topics. For more information about the use of topicRoot, see Topic semantics and usage.

You can subscribe to IBM® App Connect Enterprise 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

For messages published by an independent integration server, subscribe to the following topics:

  • For JSON publications:
    topicRoot/integration_server/Statistics/JSON/recordType/integrationServerName/messageFlowName
  • For XML publications:
    topicRoot/integration_server/StatisticsAccounting/recordType/integrationServerName/messageFlowName
where recordType specifies the type of record (SnapShot or Archive), and integrationServerName is the value that is specified by the --name parameter when the IntegrationServer process is started.
Note: For an IBM 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 INODE -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

For messages published by an independent integration server, subscribe to the following topics:

  • For JSON publications:
    topicRoot/integration_server/Statistics/JSON/Resource/integrationServerName
  • For XML publications:
    topicRoot/integration_server/ResourceStatistics/integrationServerName
where integrationServerName is the value that is specified by the --name parameter when the IntegrationServer process is started.
Note: For an IBM 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.

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 topics:
  • For JSON publications:
    topicRoot/integrationNodeName/MonitoringEvents/JSON/integrationServerName/applicationName/messageFlowName
  • For XML publications:
    topicRoot/integrationNodeName/Monitoring/integrationServerName/applicationName/messageFlowName
Where applicationName is the name of the deployment container, for example:
  • Application name.
  • RESTAPI name.
  • Integration Service name.
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.
For messages published by an independent integration server, subscribe to the following topic:
topicRoot/integration_server/Monitoring/integrationServerName/applicationName/messageFlowName
Admin events
You can publish Admin logs over the MQ Telemetry Transport (MQTT) messaging and IBM MQ by configuring the node.conf.yaml file to enable publishing. To publish admin events from your message flows, subscribe to the following topics:
  • topicRoot/integrationNodeName/AdminLog/JSON/
  • topicRoot/integrationNodeName/AdminLog/JSON/integrationServerName
For more information, see Publishing admin logs over MQTT and IBM MQ.
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
For messages published by an independent integration server, subscribe to the following topics:
  • Message flow is in a library within an application:
    topicRoot/integration_server/WorkloadManagement/AboveThreshold/integrationServerName/applicationName/libraryName/messageFlowName
  • Message flow is in a library that is not within an application:
    topicRoot/integration_server/WorkloadManagement/AboveThreshold/integrationServerName/libraryName/messageFlowName
  • Message flow is directly in an application (not in a library within the application):
    topicRoot/integration_server/WorkloadManagement/AboveThreshold/integrationServerName/applicationName/messageFlowName
  • Message flow is not in an application or a library:
    topicRoot/integration_server/WorkloadManagement/AboveThreshold/integrationServerName/messageFlowName

Results

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