7.11 Using Sensors for Monitoring

Sensors monitor BPEL activities, variables, and faults during runtime. You can define the following types of sensors, either through JDeveloper BPEL Designer or manually by providing sensor configuration files.

Activity sensors: Used to monitor the execution of activities within a BPEL process. For example, activity sensors can be used to monitor the execution time of an invoke activity or how long it takes to complete a scope. Along with the activity sensor, you can monitor variables of the activity also.
Variable sensors: Used to monitor variables (or parts of a variable) of a BPEL process. For example, variable sensors can be used to monitor the input and output data of a BPEL process.
Fault sensors: Used to monitor BPEL faults.

You typically add or edit sensors as part of the BPEL modeling of activities, faults, and variables.

When you model sensors in Oracle JDeveloper BPEL Designer, two new files are created as part of the BPEL process suitcase:

sensor.xml: Contains the sensor definitions of a BPEL process
sensorAction.xml: Contains the sensor action definitions of a BPEL process

After you define sensors for a BPEL process, you must configure sensor actions to publish the data of the sensors to an endpoint. You can publish sensor data to the BPEL reports schema, which is located in the BPEL dehydration store, to a JMS queue or topic, or to a custom Java class.

The following information is required for a sensor action:

Name
Publish type

The publish type specifies the destination where the sensor data must be presented. You can configure the following publish types:
- Database: Publishes the sensor data to the reports schema in the database. The sensor data can then be queried using SQL.
- JMSQueue: Publishes the sensor data to a JMS queue
- JMSTopic: Publishes the sensor data to a JMS topic
- Custom: Publishes the data to a custom Java class
- JMS Adapter: Publishes to remote queues or topics and a variety of different JMS providers. The JMS Queue and JMS Topic publish types only publish to local JMS destinations.
List of sensors: The sensors for a sensor action

See Chapter 18, "Sensors," in Oracle BPEL Process Manager Developer's Guide for more information.

7.11.1 How to Use Sensors for Monitoring

Add a sensor to a receive activity. The sensor monitors the input data received from the client.

To add a sensor to a receive activity:

Double-click the receive activity.
Click the Sensors tab.
Click the Create icon.
Use the Create Activity Sensor dialog to create the sensor.
1. Enter a name for the sensor.
2. Enter an evaluation time.
  
  The evaluation time controls the point at which the sensor fires. You can select from the following:
  
  Activation: The sensor fires just before the activity is executed.
  
  Completion: The sensor fires just after the activity is executed.
  
  Fault: The sensor fires if a fault occurs during the execution of the activity. Select this value only for sensors that monitor simple activities.
  
  Compensation: The sensor fires when the associated scope activity is compensated. Select this value only for sensors that monitor scopes.
  
  Retry: The sensor fires when the associated invoke activity is retried.
  
  All: Monitoring occurs during all of the preceding phases.
3. Click the Create icon to create the activity variable sensor.
4. Use the Create Activity Variable Sensor dialog to specify the variable XPath, output namespace, and output datatype, as shown in Figure 7-27.
  
  Figure 7-27 Creating the Activity Variable Sensor
  
  Description of "Figure 7-27 Creating the Activity Variable Sensor"
5. Click the Add icon to add sensor actions.
6. In the Sensor Action Chooser, select a sensor action to publish the values of the sensor (to a database, JMS queue, and so on).
7. Use the Edit Sensor Action dialog to edit the sensor action you selected in the previous step, as shown in Figure 7-28.
  
  Figure 7-28 Editing the Sensor Action
  
  Description of "Figure 7-28 Editing the Sensor Action"

7.11.2 What Happens When You Use Sensors

Sensor definitions are written to the sensor.xml file and sensor action definitions are written to the sensorAction.xml file, which are available from the Application Navigator, in the Sensor directory of your BPEL project.

Example 7-12 shows the source code for the sensor.xml file in the SOA Order Booking application.

Example 7-12 Source Code for sensor.xml

<?xml version = '1.0' encoding = 'UTF-8'?>
<sensors targetNamespace="http://www.globalcompany.com/ns/OrderBooking"
  xmlns="http://xmlns.oracle.com/bpel/sensor"
  xmlns:tns="http://www.globalcompany.com/ns/OrderBooking"
  xmlns:pc="http://xmlns.oracle.com/bpel/sensor">
    <sensor sensorName="InstanceFaulted"
      classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent" kind="activity"
      target="SetFaultedOrderStatus">
        <activityConfig evalTime="completion">
         <variable outputDataType="SOAOrderBookingFaultMessage"
           outputNamespace="http://www.globalcompany.com/ns/OrderBooking"
           target="$OrderBookingFault"/>
        </activityConfig>
    </sensor>
    <sensor sensorName="InstanceStart"
      classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent" kind="activity"
      target="receiveInput">
        <activityConfig evalTime="completion">
          <variable outputDataType="SOAOrderBookingRequestMessage"
            outputNamespace="http://www.globalcompany.com/ns/OrderBooking"
              target="$inputVariable"/>
        </activityConfig>
    </sensor>
    <sensor sensorName="InstanceCompleted"
      classname="oracle.tip.pc.services.reports.dca.agents.BpelActivitySensorAgent" kind="activity"
      target="callbackClient">
        <activityConfig evalTime="completion">
          <variable outputDataType="SOAOrderBookingRequestMessage"
           outputNamespace="http://www.globalcompany.com/ns/OrderBooking" target="$inputVariable"/>
        </activityConfig>
    </sensor>
</sensors>

Example 7-13 shows the source code for the sensorAction.xml file in the SOA OrderBooking application.

Example 7-13 Source Code for sensorAction.xml

<?xml version = '1.0' encoding = 'UTF-8'?>
<actions targetNamespace="http://www.globalcompany.com/ns/OrderBooking"
  xmlns="http://xmlns.oracle.com/bpel/sensor"
  xmlns:tns="http://www.globalcompany.com/ns/OrderBooking"
  xmlns:pc="http://xmlns.oracle.com/bpel/sensor">
    <action name="InstanceStart" publishName="" publishType="JMSTopic" enabled="true"
      publishTarget="jms/demoTopic">
        <property name="JMSConnectionFactory">jms/TopicConnectionFactory</property>
        <sensorName>InstanceStart</sensorName>
    </action>
    <action name="InstanceCompleted" publishName="" publishType="JMSTopic" enabled="true"
      publishTarget="jms/demoTopic">
        <property name="JMSConnectionFactory">jms/TopicConnectionFactory</property>
        <sensorName>InstanceCompleted</sensorName>
    </action>
    <action name="InstanceFaulted" publishName="" publishType="JMSTopic" enabled="true"
      publishTarget="jms/demoTopic">
        <property name="JMSConnectionFactory">jms/TopicConnectionFactory</property>
        <sensorName>InstanceFaulted</sensorName>
    </action>
</actions>