See information about the latest product version
Monitoring profile
To customize events after a message flow has been deployed, but without redeploying the flow, use a monitoring profile configurable service. By using this service, you can apply a monitoring profile to one or more message flows.
Outline monitoring profile
Here is an outline monitoring profile that contains a single event source to illustrate the structure:
<p:monitoringProfile
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/6.1.0.3/monitoring/profile" p:version="2.0">
<p:eventSource p:enabled="true" p:eventSourceAddress="SOAPInput.transaction.Start">
<p:eventPointDataQuery>
<p:eventIdentity>
<p:eventName p:literal="" p:queryText=""/>
</p:eventIdentity>
<p:eventCorrelation>
<p:localTransactionId p:queryText="" p:sourceOfId="automatic"/>
<p:parentTransactionId p:queryText="" p:sourceOfId="automatic"/>
<p:globalTransactionId p:queryText="" p:sourceOfId="automatic"/>
</p:eventCorrelation>
<p:eventFilter p:queryText="true()"/> <p:eventUOW p:unitOfWork="messageFlow" /> </p:eventPointDataQuery>
<p:applicationDataQuery>
<p:simpleContent p:dataType="boolean" p:name="" p:targetNamespace="">
<p:valueQuery p:queryText=""/>
</p:simpleContent>
<p:complexContent p:name="" targetNamespace="">
<p:payloadQuery p:queryText=""/>
</p:complexContent>
</p:applicationDataQuery>
<p:bitstreamDataQuery p:bitstreamContent="all" p:encoding="base64Binary"/>
</p:eventSource>
</p:monitoringProfile>
- A p:eventPointDataQuery element that provides key information about the event.
- Optional: A p:applicationDataQuery element if the event payload will include data fields extracted from a message.
- Optional: A p:bitstreamDataQuery element if the event payload will include bitstream data from a message.
Creating a monitoring profile
To help you create monitoring profiles, the following sample contains an outline monitoring profile XML file and the monitoring profile XML schema file (MonitoringProfile.xsd):
Validate your monitoring profiles against the XML schema to ensure that they are correct.
You can view information about samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit or the online information center. You can run samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit.
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 is a string that uniquely identifies the event source in the message flow. It 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: nodelabel is the label of the node as known by the broker runtime components. If the node is in a subflow the label reflects this. For example, flow A contains an instance of flow B as a subflow labeled myB; flow B contains an instance of a Compute node 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: Specify the name by which events from this event source
will be known, in the p:eventPointDataQuery/p:eventIdentity/p:eventName element.
- If the event name is a fixed string, complete the p:eventName/@p:literal attribute
- If the event name is to be 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 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.
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 p:applicationDataQuery
element, if the event is to contain selected data fields extracted
from the message. 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, allowing 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.
- For each simple data field, complete a p:simpleContent
element:
- Optional: Complete the p:bitstreamDataQuery element,
if the event is to capture message bitstream data:
- 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.
For information about correlation, see Correlation and monitoring events.
Every emitted monitoring event can contain up to three correlation attributes. If no correlation information is specified in the monitoring profile, no correlation attributes will be used.
- Optional: Complete the p:localTransactionId element.
- If you want 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 will be generated and saved in the Environment tree.
- If you want to use a value 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 unique to this invocation of the message flow. The value is saved in the Environment tree.
- Optional: Complete the p:parentTransactionId element.
- If you want to reuse the parent correlator from the Environment tree, set the p:parentTransactionId/@p:sourceOfId attribute to 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, 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.
- Optional: Complete the p:globalTransactionId element.
- If you want to reuse the global correlator from the Environment tree, set the p:globalTransactionId/@p:sourceOfId attribute to 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, 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.
- Optional: Complete the p:localTransactionId element.
- Complete the p:eventPointDataQuery/p:eventUOW element.
This determines 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. Set the p:eventUOW/@p:unitOfWork attribute to one of the following values:
- messageFlow
- 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 allowed values are shown in the following table:If you do not include the eventUOW element for an event source, transactionality for all events issued from that source, except transaction.rollback events, defaults to messageFlow. Transactionality for transaction.rollback events defaults to independent.Event Type Allowed values transaction.Start - messageFlow
- independent
- none
transaction.End - messageFlow
- none
transaction.Rollback - independent
- none
terminal - messageFlow
- independent
- none
XPath queries and XML namespaces
If an XPath query contains a component that has an XML namespace, the XPath contains a namespace prefix for the namespace. For example, the following XPath refers to components in two different namespaces:
<p:localTransactionId p:sourceOfId="query" p:queryText="$Body/soapenv:Header/wsa:messageID" />
For the broker to resolve the namespace prefix, the namespace URL must also be provided. Supply a prefix mapping element for each namespace:
<p:localTransactionId p:sourceOfId="query" p:queryText="$Body/soapenv:Header/wsa:messageID">
<p:prefixMapping p:prefix="soapenv" p:URI="http://www.w3.org/2003/05/soap-envelope" />
<p:prefixMapping p:prefix="wsa" p:URI="http://www.w3.org/2005/08/addressing" />
</p:localTransactionId>
Monitoring profile examples
The following XML documents conform to the monitoring profile schemaMonitoring profile 1: Two event sources, each supplying an event name
<p:monitoringProfile
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/6.1.0.3/monitoring/profile" p:version="2.0">
<p:eventSource p:eventSourceAddress="SOAPInput.transaction.Start">
<p:eventPointDataQuery>
<p:eventIdentity>
<p:eventName p:literal="SOAP start event"/>
</p:eventIdentity>
</p:eventPointDataQuery>
</p:eventSource>
<p:eventSource p:eventSourceAddress="SOAPInput.transaction.End">
<p:eventPointDataQuery>
<p:eventIdentity>
<p:eventName p:literal="SOAP end event"/>
</p:eventIdentity>
</p:eventPointDataQuery>
</p:eventSource>
</p:monitoringProfile>
<p:monitoringProfile
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/6.1.0.3/monitoring/profile" p:version="2.0">
<p:eventSource p:eventSourceAddress="SOAPInput.transaction.Start">
<p:eventPointDataQuery>
<p:eventCorrelation>
<p:localTransactionId p:queryText="$Body/soapenv:Header/wsa:messageID" p:sourceOfId="query">
<p:prefixMapping p:prefix="soapenv" p:URI="http://www.w3.org/2003/05/soap-envelope"/>
<p:prefixMapping p:prefix="wsa" p:URI="http://www.w3.org/2005/08/addressing"/>
</p:localTransactionId>
</p:eventCorrelation>
</p:eventPointDataQuery>
</p:eventSource>
</p:monitoringProfile>
<p:monitoringProfile
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/6.1.0.3/monitoring/profile" p:version="2.0">
<p:eventSource p:eventSourceAddress="MQInput.terminal.out">
<p:applicationDataQuery>
<p:simpleContent p:dataType="integer" p:name="InvoiceNumber">
<p:valueQuery p:queryText="$Body/invoice/invoiceNo"/>
</p:simpleContent>
<p:simpleContent p:dataType="string" p:name="BatchID">
<p:valueQuery p:queryText="$Body/batch/batchNo"/>
</p:simpleContent>
</p:applicationDataQuery>
</p:eventSource>
</p:monitoringProfile>
<p:monitoringProfile
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/6.1.0.3/monitoring/profile" p:version="2.0">
<p:eventSource p:eventSourceAddress="MQInput.terminal.out">
<p:bitstreamDataQuery p:bitstreamContent="body" p:encoding="CDATA"/>
</p:eventSource>
</p:monitoringProfile>
CDATA
encoding is not suitable for all types of data. Use CDATA only when
@p:bitstreamContent="body". Do not use CDATA if your message bitstreams
might contain characters that are not allowed in XML (see http://www.w3.org/TR/2006/REC-xml-20060816/#charsets).