Creating a monitoring profile

A monitoring profile XML file lists the event sources in the message flow that emits events, and defines the properties of each event.

Before you begin

A monitoring profile is an XML document that must be saved to a policy project. If you have a suitable policy project already, you can create a new XML file to save in that project. Otherwise, create a new policy project; for example, select New > Policy Project

About this task

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 the XML schema file MonitoringProfile.xsd, which you can find in the samples directory of your 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.

You can use either of the following methods to create a monitoring profile:

Extract a monitoring profile from an existing message flow that is configured to use monitoring events. If you have a deployed message flow that was configured through the IBM App Connect Enterprise Toolkit Message Flow editor to use monitoring events, 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 other monitoring profiles, and edit them as required.
For example, to extract a monitoring profile from a flow in an application that is running on an independent integration server, you can run a command similar to the following example:
```
mqsireportflowmonitoring-i localhost -p 7600 -k <Application_name> -f <Flow_name>  -x <Path to your Toolkit Policy Project Folder>/<filename>.monprofile.xml
```
After you successfully run the mqsireportflowmonitoring command, you must right-click on the Toolkit Policy Project in the IBM App Connect Enterprise Toolkit, and select refresh. The file appears in the Navigator view, in the Other Resource section. Alternatively, run the mqsireportflowmonitoring with the -x parameter set to the full path name of a file in a temporary location. Then use the Eclipse menu options File, and then Import to add <filename>.monprofile.xml into the Policy Project.
Manually create a monitoring profile XML file (.monprofile.xml) from scratch, by completing the following steps.

Procedure

The following steps describe how to manually create a monitoring profile XML. Follow these steps for each p:eventSource element:

Use a text editor to create the monitoring profile XML file.

For example, in the Toolkit right-click your policy project and then select New > Other > XML / XML File. Give the XML file a name with an extension of .monprofile.xml (for example, monitoringProfileName.monprofile.xml). You can then use the Source view of the XML file to edit the 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/monitoring/11/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.

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 App Connect Enterprise runtime components. The label also indicates whether 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 attribute.
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.
1. 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.
2. 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.
3. 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 output 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	messageFlow none
transaction.Rollback	independent none
terminal	messageFlow independent none

If you do not include the eventUOW element for an event source, transactionality for all events that are output from that source (except transaction.rollback events) defaults to messageFlow. Transactionality for transaction.rollback events defaults to independent.

If you use XPath to select the value of a field, and if the XPath query contains a component that has an XML namespace, the XPath will contain a namespace prefix for the namespace. The namespace prefix in all prefixMapping elements in a monitoring profile must be unique.
Ensure that the monitoring profile XML conforms to the 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).
Save the XML file with an extension of .monprofile.xml (for example, monitoringProfileName.monprofile.xml) to your policy project.

What to do next

Deploy the monitoring profile, as described in Deploying and redeploying a monitoring profile.