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
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
. 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.
- 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 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 |
|
transaction.Rollback |
|
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.