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.
- Display the properties for the node.
- Select the Monitoring tab.
- Click Add.
The Add
entry window is displayed.
- Complete the Event Source field.
The field has a drop-down list of all events that can be
defined for this node. The event source information is used to populate
the attributes of the wmb:eventPointData/wmb:messageFlowData/wmb:node element
of the event.
When you have selected the event
source, the corresponding value for Event Source Address is
displayed as a read-only property.
Tip: If you later decide
to enable or disable events using the mqsichangeflowmonitoring command,
you must specify a value for Event Source Address,
not Event Name.
- Complete the Event Name details;
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 in these 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: Complete the
Event Filter section by providing an XPath expression to control whether
the event is emitted. Take one of the following steps:
- Type in the expression (for example, $Body/StockTrade/Details/Value
> 10000); or
- Click Edit to launch 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.
Using this facility, you can tailor
event emissions to your business requirements, by filtering out events
that do not match a set of rules. This can reduce the number of events
emitted, and reduce the workload on your monitoring application.
- Optional: Complete the Event Payload section
if the event is to contain selected data fields extracted from the
message. Click Add to launch the Add
Data Location dialog box. Take one of the following steps:
- Type in the location (for example, $LocalEnvironment/File/Name);
or
- Click Edit to launch XPath Expression Builder.
You can extract one or more fields from the message data
and include it 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 commonly used 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, allowing another
application to provide an audit trail or to resubmit failed messages.
- Optional: Select the Include bitstream data in payload field
if the event is to capture message bitstream data.
- Content
- Select from Headers, Body, All.
- Encoding
- Select from base64, HexBinary and CData (the
original text, without encoding).
- Optional: Select the Correlation tab,
to complete details for event correlation.
- Complete the Event Correlation details;
for information about correlation, see Correlation and monitoring events.
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
will use.
- Optional: Complete the Local transaction
correlator details.
- Automatic
- The local correlator used by the most recent event for this invocation
of the message flow will be used. If no local correlator exists yet,
a new unique value will be generated.
- Specify location of correlator
- Enter a value, or click Edit to launch the XPath Expression Builder. The local correlator will be read
from the specified location in the message tree. Ensure that the specified
location contains a correlator value unique to this invocation of
the message flow.
- Optional: Complete the Parent transaction
correlator details to extract a correlation field from
the parent transaction.
- Automatic
- The parent correlator used by the most recent event for this invocation
of the message flow will be used. If no parent correlator exists yet,
no parent correlator will be used.
- Specify location of correlator
- Enter a value, or click Edit to launch the XPath Expression Builder. The parent correlator will be read
from the specified location in the message tree. Ensure that the specified
location contains a suitable value for the parent correlator.
- Optional: Complete the Global transaction
correlator details to extract a correlation field from
a global transaction.
- Automatic
- The global correlator used by the most recent event for this invocation
of the message flow will be used. If no global correlator exists yet,
no global correlator will be used.
- Specify location of correlator
- Enter a value, or click Edit to launch the XPath Expression Builder. The global correlator will be read
from the specified location in the message tree. Ensure that the specified
location contains a suitable value for the global correlator.
- Optional: Choose whether the emission
of monitoring events by a message flow is coordinated with the message
flow transaction, or is in an independent unit of work, or is not
in a unit of work.
Click the
Transaction tab
and select the appropriate option for
Event Unit of Work.
- 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 specified to be 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 will be included
in an independent unit of work. This 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 whether or not the main unit of work
commits successfully.
An independent transaction can be started
only if the main transaction has been either committed or rolled back.
If the Commit count property of the flow is greater
than one, (Configurable message flow properties), or the Commit
by message group property is set (Receiving messages in a WebSphere MQ message group),
the events targeted for the independent transaction are instead emitted
out of sync point, and a message is output stating that this has been
done.
- 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 these options are available on all event
types. The defaults 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 just added; the event is enabled.
- Optional: Disable the event.
- Save the message flow.
Last updated Friday, 21 July 2017