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.

A monitoring profile is an XML document that specifies the event sources in a message flow that will emit events, and the properties of those events.

The monitoring profile XML must conform to XML schema file MonitoringProfile.xsd. You can find the MonitoringProfile.xsd file and a basic example monitoring profile XML file in the following samples directory of the IBM® Integration Bus installation:

Install_root/server/sample/RecordReplay/MonitoringProfile.xsd
Install_root/server/sample/RecordReplay/basicMonitoringProfile.xml

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>

The root element is p:monitoringProfile. It contains one or more p:eventSource elements, each of which specifies an event source and defines its properties. Each p:eventSource element contains:

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

Tip: If you have a deployed message flow that has monitoring properties configured using the Message Flow editor, you can use the mqsireportflowmonitoring command to create the equivalent monitoring profile XML file for the message flow. You can use this profile as a starting point for creating other monitoring profiles.

For instructions about how to create a monitoring profile XML, see Creating a monitoring profile.

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 integration node 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 schema

Monitoring 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>

Monitoring profile 2: Supply an alternative local correlator

<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>

Monitoring profile 3: Include two simple fields from the message

<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>

Monitoring profile 4: Include the bitstream, encoded as CDATA

By default, bitstreams are encoded in base64Binary format. The following monitoring profile changes the encoding to CDATA.

<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).