Monitoring profiles

To customize events after a message flow is deployed, but without redeploying the flow, you can use a monitoring profile.

Before you can use a monitoring profile, you must deploy it to a policy project and then activate the monitoring profile on the message flow, application, or integration server. Activate the monitoring profile by using either the mqsichangeflowmonitoring command or the administration REST API.

You can also configure a default monitoring profile for an integration server, by setting properties in the Defaults section of the server.conf.yaml file. This profile is then used if a message flow has no monitoring events that are configured and no specific monitoring profile applied. For example:

Defaults:
    monitoringProfile: 'myIS1MonitoringProfile'       # Default Monitoring profile

A monitoring profile is an XML document that specifies the event sources in a message flow that emits events, and the properties of those events. The monitoring profile XML must conform to XML schema file MonitoringProfile.xsd, which you can find in the samples directory of the IBM App Connect Enterprise installation (Install_root/server/sample/Monitoring/MonitoringProfile.xsd). The XML file must have an extension of .monprofile.xml (for example, monitoringProfileName.monprofile.xml) and must be contained in a policy project.

The monitoring profile must be deployed before you start the message flows that use it. If a message flow is configured to use a monitoring profile that is not deployed, a warning is issued. You must manually stop and start the message flow after the monitoring profile is deployed in order for it to be used by the message flow. If you redeploy a monitoring profile, all message flows that use that monitoring profile are stopped and restarted to use the new values.

You can attach, change, or detach monitoring profiles from a message flow by using the mqsichangeflowmonitoring command. For more information, see Applying and activating a monitoring profile.

The following example of a monitoring profile XML document contains a single event source to illustrate the structure.

<p:monitoringProfile
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/10.0.0.0/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="">
                <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 includes data fields that are extracted from a message.
Optional: A p:bitstreamDataQuery element if the event payload includes bitstream data from a message.

Creating a monitoring profile

If you have a deployed message flow with monitoring properties that were configured by using the Message Flow editor in the IBM App Connect Enterprise Toolkit, you can use either the mqsireportflowmonitoring command or the administration REST API to extract those monitoring properties from the deployed flow and create the equivalent monitoring profile (.monprofile.xml file) for the message flow. You can then use this profile as a starting point for creating other monitoring profiles.

Alternatively, you can create the .monprofile.xml file manually, by following the steps described in 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. The namespace prefix in all prefixMapping elements in a monitoring profile must be unique. 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 prefixMapping 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/10.0.0.0/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/10.0.0.0/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/10.0.0.0/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/10.0.0.0/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).

Monitoring profile 5: One eventSource that applies to all transaction events for a message flow and includes the available bitstream as base64binary.

<p:monitoringProfile 
xmlns:p="http://www.ibm.com/xmlns/prod/websphere/messagebroker/10.0.0.0/monitoring/profile" p:version="2.0">
    <p:eventSource p:enabled="true" p:eventSourceAddress="transaction.all">
        <p:eventPointDataQuery>
            <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:eventPointDataQuery>
        <p:bitstreamDataQuery p:bitstreamContent="all" p:encoding="base64Binary"/>
    </p:eventSource>
</p:monitoringProfile>