About this task
The following steps describe how to create
a monitoring profile XML. Follow these steps for each p:eventSource element.
- Specify the p:eventSource/@p:eventSourceAddress attribute.
This string uniquely identifies the
event source in the message flow. The string
must follow the fixed format for transaction events and terminal
events, as shown in the following table:
Event type |
Event source address |
Transaction Start event |
nodelabel.transaction.Start |
Transaction End event |
nodelabel.transaction.End |
Transaction Rollback event |
nodelabel.transaction.Rollback |
Terminal event |
nodelabel.terminal.<Terminal> |
Note: The nodelabel attribute is the label
of the node as known by the IBM® Integration Bus runtime components. The label
also indicates if the node is in a subflow.
For example, flow A contains an instance of
flow B as a subflow that is labeled myB. Flow
B contains an instance of a Compute
node that is labeled myCompute. The
nodelabel for the Compute node is
myB.myCompute.
In the emitted event, the address string of the
event source is set in the wmb:eventData/@wmb:eventSourceAddress attribute.
- Optional: In the p:eventPointDataQuery/p:eventIdentity/p:eventName
element, specify the name by which events from
this event source are known.
- If the event name is a fixed string, complete the
p:eventName/@p:literal attribute
- If the event name is extracted from a field in the message, complete
the p:eventName/@p:queryText attribute
by specifying an XPath query.
In the emitted event, the event name
is set in the wmb:eventPointData/wmb:eventIdentity/@wmb:eventName
attribute.
If the p:eventName element
is not supplied, @wmb:eventName in
the emitted event defaults to @p:eventSourceAddress.
- Optional: Complete the p:eventPointDataQuery/p:eventFilter/@p:queryText
attribute by specifying an XPath expression to
control whether the event is emitted. The expression
must evaluate to true (the event is emitted), or false
(the event is not emitted). The expression can reference
fields in the message tree, or elsewhere in the
message assembly. If an event does not contain an
eventFilter element, the event is always emitted.
By 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 facility can reduce the number
of events that are emitted, and reduce the
workload on your monitoring application.
- Optional: If the event is to contain selected
data fields that are extracted from the message,
complete the p:applicationDataQuery element. You can extract one or more fields from the message data and
include it with the event. The fields can be simple
or complex.
- For each simple data field, complete a p:simpleContent element:
- Complete the p:simpleContent/p:valueQuery/@p:queryText
attribute by specifying an XPath
query.
- Complete the p:simpleContent/@p:name,
@p:namespace, and
@p:dataType attributes.
The @p:dataType value
must be one of boolean, date,
dateTime, decimal,
duration, integer,
string, or time.
- For each complex data field, complete a
p:complexContent element:
- Complete the p:complexContent/p:payloadQuery/@p:queryText
attribute by specifying an XPath
query.
- Complete the p:complexContent/@p:name and
@p:namespace attributes.
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. You can then use
another application to provide an audit trail
or to resubmit failed messages.
In
the emitted event, the extracted data is set in the
wmb:applicationData/wmb:simpleContent and
wmb:applicationData/wmb:complexContent elements.
- Optional: If the event is to capture message
bitstream data, complete the p:bitstreamDataQuery element.
- Complete the @p:bitstreamContent attribute. The
attribute value must be one of headers,
body, or all.
- Complete the @p:encoding attribute. The attribute
value must be one of CDATA, base64Binary,
or hexBinary.
In the emitted event, the extracted bitstream
data is set in the wmb:bitstreamData/wmb:bitstream element.
- Optional: Complete the p:eventPointDataQuery/p:eventCorrelation element.
Every emitted monitoring event can contain
up to three correlation attributes. If no
correlation information is specified in the monitoring
profile, no correlation attributes are used.
- Complete the p:localTransactionId element.
- To reuse the local correlator from the environment tree, set
the p:localTransactionId/@p:sourceOfId
attribute to automatic.
If no local correlator exists
yet, a new unique value is generated and
saved in the environment tree.
- To use a value that is contained in a location in the
message, set the
p:localTransactionId/@p:sourceOfId
attribute to query,
then complete the p:localTransactionId/@p:queryText
attribute by specifying an
XPath query. Ensure that the
specified location contains a correlator value that is
unique to this invocation of the message
flow. The value is saved in
the environment tree.
- Complete the p:parentTransactionId element.
- To reuse the parent correlator from the environment tree,
set the p:parentTransactionId/@p:sourceOfId
attribute to automatic.
If no parent correlator exists,
no parent correlator is used.
- To use a value that is contained in a location in the
message, set the
p:parentTransactionId/@p:sourceOfId
attribute to query,
then complete the p:parentTransactionId/@p:queryText
attribute by specifying an
XPath query. Ensure that the
specified location contains a suitable value for the parent
correlator. The value is saved
in the environment tree.
- Complete the p:globalTransactionId element.
- To reuse the global correlator from the environment tree,
set the p:globalTransactionId/@p:sourceOfId
attribute to automatic.
If no global correlator exists,
no global correlator is used.
- To use a value that is contained in a location in the
message, set the
p:globalTransactionId/@p:sourceOfId
attribute to query,
then complete the p:globalTransactionId/@p:queryText
attribute by specifying an
XPath query. Ensure that the
specified location contains a suitable value for the global
correlator. The value is saved
in the environment tree.
- Complete the p:eventPointDataQuery/p:eventUOW element.
This element determines 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.
Set the
p:eventUOW/@p:unitOfWork attribute
to one of the following values:
- 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 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 allowed values
are shown in the following table.
Event Type |
Allowed values |
transaction.Start |
- messageFlow
- independent
- none
|
transaction.End |
|
transaction.Rollback |
|
terminal |
- messageFlow
- independent
- none
|
If you do not include the
eventUOW element
for an event source, transactionality for
all events that are issued from that source
(except transaction.rollback events) defaults to
messageFlow. Transactionality for transaction.rollback
events defaults to
independent.
What to do next
Apply the monitoring profile by completing the steps in
Applying a monitoring profile.