In the Message Flow editor, use
the Monitoring tab on the properties of a message
flow node to add one or more monitoring events.
About this task
An event source is a point in a message flow from which a
monitoring event can be emitted. Each event source has a set of
properties that control the contents of the monitoring events that
it emits. To create an event, complete the following steps.
Procedure
- In the Message Flow editor, select the relevant node to
display the properties for that node.
- Select the Monitoring tab.
- Click Add.
The Add
event window is displayed.
- In the Event Source field, select
the source of the event.
When you select the
event source, the corresponding value for
Event Source
Address is displayed as a read-only property. The event
source information is used to populate the attributes of the
wmb:eventPointData/wmb:messageFlowData/wmb:node
element
of the event.
Tip: If you decide to enable or disable
events by using the mqsichangeflowmonitoring command,
you must specify a value for Event Source Address,
not Event Name.
- In the Event Name field, select
either Literal or Data location.
Every monitoring event has a name that
is placed in the wmb:eventPointData/wmb:eventIdentity/@wmb:eventName
attribute
of the event. The default names are shown in the following table:
Event source |
Default event name |
Example |
Transaction start |
nodeLabel.TransactionStart |
MQInput.TransactionStart |
Transaction end |
nodeLabel.TransactionEnd |
MQInput.TransactionEnd |
Transaction rollback |
nodeLabel.TransactionRollback |
MQInput.TransactionRollback |
Terminal |
nodeLabel.terminal_label.Terminal |
MQInput.OutTerminal |
You can override the default value in the following ways:
- By specifying an alternative literal string.
- By specifying an XPath query. The query extracts the event name
from a field in the input message. Click Edit to
use the XPath Expression Builder.
- Optional: In the Event
Filter section, provide an XPath expression to control
whether the event is emitted.
Type in the expression
(for example, $Body/StockTrade/Details/Value > 10000
)
or click Edit to launch the XPath Expression
Builder.
The expression must evaluate to true or false, and can
reference fields in the message tree, or elsewhere in the message
assembly. The default value is
true()
, which
means that the event is always produced.
- Optional: Complete the Event Payload field
if the event must contain selected data fields that are extracted
from the message.
Click Add to
launch the Add Data Location dialog box.
You can then type in the location (for example, $LocalEnvironment/File/Name
)
or click Edit to launch the XPath Expression
Builder.
You can extract one or more fields from the message
data and include them with the event. The fields can be simple
or complex. Simple content is contained in the wmb:applicationData/wmb:simpleContent
field
of the event; complex data is contained in the wmb:applicationData/wmb:complexContent
field.
This
facility is used commonly for communicating significant business data
in a business event. If the event contains the input bit stream,
this facility can also be used to extract key fields. You can
then use another application to provide an audit trail or to
resubmit failed messages.
- Optional:
Select Include bitstream data in payload if
the event must capture message bitstream data.
If
you select this option, you must provide the following information:
- Content
- Select from Headers, Body, and All.
- Encoding
- Select from CData (the original text, without
encoding), HexBinary, and base64Binary.
When this option is
selected, it is possible that the bitstream that is included is not
the same as the message that is written from a transport output node.
Monitoring serializes the whole message tree, whereas transport output
nodes use the parts of the message tree that they recognize. The bitstream
that is included in a monitoring message is generated from all the
headers that occur before the first message body in the message tree.
Any headers that occur after the message body are not included.
- Optional: Select the Correlation tab
to provide details for event correlation.
Every monitoring event must contain at least one correlation attribute,
and can contain up to three. If you do not specify any correlation
information, the first event source in the message flow allocates
a unique identifier that all later event sources in the same transaction
use.
- In the Local transaction correlator field,
select one of the following options.
- Automatic
- The local correlator that is used by the most recent event for
this invocation of the message flow is used. If no local correlator
exists, a new unique value is generated.
- Specify location of correlator
- Enter a value, or click Edit to launch
the XPath Expression Builder. The local correlator is read from the
specified location in the message tree. Ensure that the specified
location contains a correlator value that is unique to this invocation
of the message flow.
- In the Parent transaction correlator field,
select one of the following options to extract a correlation field
from the parent transaction.
- Automatic
- The parent correlator that is used by the most recent event for
this invocation of the message flow is used. If no parent correlator
exists, no parent correlator is used.
- Specify location of correlator
- Enter a value, or click Edit to launch
the XPath Expression Builder. The parent correlator is read from the
specified location in the message tree. Ensure that the specified
location contains a suitable value for the parent correlator.
- In the Global transaction correlator field,
select one of the following options to extract a correlation field
from a global transaction.
- Automatic
- The global correlator that is used by the most recent event for
this invocation of the message flow is used. If no global correlator
exists, no global correlator is used.
- Specify location of correlator
- Enter a value, or click Edit to launch
the XPath Expression Builder. The global correlator is read from the
specified location in the message tree. Ensure that the specified
location contains a suitable value for the global correlator.
- Optional: On the Transaction tab,
choose how the emission of monitoring events by a message flow
is coordinated. You can choose to coordinate with the message
flow transaction, in an independent unit of work, or not in a
unit of work.
Select one of the following options.
- Message flow
- The event, and all other events with this setting,
are emitted only if the message flow commits its unit of
work successfully.
If the transaction start event is included
in the message flow unit of work, but the message processing
fails and this unit of work is not published, the transaction
start event is included in an independent unit of work.
This behavior ensures that your monitoring application receives
a pair of events (start and rollback), rather than receiving
a rollback event in isolation.
- Independent
- The event is emitted in a second unit of work,
independent of the main unit of work. The event, and all
other events with this setting, are emitted regardless of
whether the main unit of work commits successfully.
An
independent transaction can be started only if the main
transaction is either committed or rolled back. If the Commit
count property of the flow is greater than one,
or the Commit by message group property
is set, the events that are targeted for the independent
transaction are emitted out of sync point. A message is
also issued with this information.
- None
- The event is emitted out of sync point (not in any unit
of work.) The event is emitted when the message passes through
the event source, and is available for reading immediately.
Not all of these options are available
on all event types. The default and allowed values are shown
in the following table:
Event source |
Allowed values |
Default |
Transaction start |
- Message flow
- Independent
- None
|
Message flow |
Transaction end |
|
Message flow |
Transaction rollback |
|
Independent |
Terminal |
- Message flow
- Independent
- None
|
Message flow |
- Click Finish.
The Events table
in the Monitoring tab of the Properties view for the node is
updated with details of the event that you added, and the event
is enabled.
- Save the message flow.
- When all events are added to the flow, add the message
flow to the BAR file, and deploy
the BAR file.
Monitoring is inactive for the
flow; deploying the BAR file does not activate monitoring.
- Activate monitoring for the flow by using the mqsichangeflowmonitoring
-c command.
What to do next
The monitoring properties for a node show all monitoring
events that are defined for that node. You can edit the monitoring
properties of a node to do the following tasks:
- Enable or disable a monitoring event.
- Add, delete, or change the monitoring events for the node.