Correlation and monitoring events

A monitoring application uses correlation attributes to identify events that belong to the same business transaction.

A business transaction can be any of the following scenarios:

  • A single invocation of a message flow.
  • Multiple invocations of the same message flow from a parent application. The parent application might be another message flow.
  • Multiple invocations of various message flows from a parent application. The parent application might be another message flow.

Three correlation attributes are available for you to use in your events: local correlator, parent correlator and global correlator. The exact usage of the correlation attributes varies depending on the requirements. For example, a parent application can pass its transaction identifier to the child message flow (perhaps in a header) so that the child message flow can report it in the event as a parent correlator.

Every emitted monitoring event can contain a local correlator, a parent correlator, and a global correlator. Correlation information is placed in the following attributes of the event:
wmb:eventPointData/wmb:eventCorrelation/@wmb:localTransactionId
wmb:eventPointData/wmb:eventCorrelation/@wmb:parentTransactionId
wmb:eventPointData/wmb:eventCorrelation/@wmb:globalTransactionId

You can specify correlation information when you configure the event.

If you do not specify any correlation information when you configure your events, no correlation attributes will be used.

If you do specify correlation information, you must configure the correlation attributes to be used, and where they will read their value from. Typically you need to specify correlation information only for the first event source in the message flow; by default all later event sources retrieve the same value from the Environment tree.

The exact steps for specifying correlation information depend on whether you are using monitoring properties or a monitoring profile to configure your events, but the principle is the same for both techniques:
Local correlator

If you want to reuse the local correlator from the Environment tree, specify Automatic. If no local correlator exists yet, a new unique value will be generated and saved in the Environment tree.

If you want to use a value contained in a location in the message, specify the location of the correlator by supplying an XPath into the message tree. Ensure that the specified location contains a correlator value unique to this invocation of the message flow. The extracted value is saved in the Environment tree as the local correlator.

Parent correlator

If you want to reuse the parent correlator from the Environment tree, specify Automatic. If no parent correlator exists yet, no parent correlator will be used.

If you want to use a value contained in a location in the message, specify the location of the correlator by supplying an XPath into the message tree. Ensure that the specified location contains a suitable value for the parent correlator. The extracted value is saved in the Environment tree as the parent correlator.

Global correlator

If you want to reuse the global correlator from the Environment tree, specify Automatic. If no global correlator exists yet, no global correlator will be used.

If you want to use a value contained in a location in the message, specify the location of the correlator by supplying an XPath into the message tree. Ensure that the specified location contains a suitable value for the global correlator. The extracted value is saved in the Environment tree as the global correlator.

When a correlator value has been set, it is saved in the Environment tree. Later event sources can reuse the saved value by specifying Automatic. There is no need to use the same XPath in all the event sources in your message flow, and doing so might adversely affect performance.

The locations in the Environment tree used to save correlator values for use by later events are:

Environment.Monitoring.EventCorrelation.localTransactionId       
Environment.Monitoring.EventCorrelation.parentTransactionId       
Environment.Monitoring.EventCorrelation.globalTransactionId

 

The following message tree locations often contain a value that can be used as a correlator: 
$Root/MQMD/MsgId
$Root/MQMD/CorrelId
$Root/JMSTransport/Transport_Folders/Header_Values/JMSMessageID
$Root/JMSTransport/Transport_Folders/Header_Values/JMSCorrelationID
$LocalEnvironment/Destination/HTTP/RequestIdentifier
$LocalEnvironment/Wildcard/WildcardMatch
Tip: If the three available correlators are not sufficient, you can configure the event to extract other correlation fields from the message and place them in the wmb:applicationData/wmb:simpleContent section of the event.
Tip: The Collector node and the AggregateControl node do not preserve the Environment tree for later nodes in the message flow. If you want to use the same correlator value later in the flow, ensure that the correlator value is available in the message tree, and that the first event source after the Collector or AggregateControl node specifies the location of the correlator by supplying an XPath into the message tree.

Scenarios

Scenario 1: In this scenario, all three correlators are used to monitor data that starts in an external process. Several message flows then transform the data.
  • The globalTransactionID field contains an identifier from the message header or payload. This identifier correlates events from the external process and IBM® Integration Bus.
  • The parentTransactionID correlates events in IBM Integration Bus from different message flows.
  • The localTransactionID correlates events from the same message flow.
Scenario 2: In this scenario, the parentTransactionID field is used to correlate request and reply messages between two message flows:
  • The Request flow sends a purchaseOrder request to an external application for processing.
  • The Reply flow receives a confirmation reply from the external application when the purchaseOrder has been processed.

You need to correlate the request and replies belonging to the same purchase order. You can do this by setting the parentTransactionID to a field in the purchaseOrder, such as a purchaseOrderID, which is available in both the request and reply.