Probes

Probes are using during the execution life cycle of a flow. A probe provides a simple mechanism to monitor events during the execution life cycle of a flow. The events being monitored by a probe are:

Flow started executing
Flow finished executing
Flow aborted execution
The executable component requested execution abortion
The executable component has been initialized
The executable component has been initialized
The executable component has push a piece of data
The executable component has pull a piece of data
The executable component got a property value
The executable component is being fired
The executable component is cooling down

Where the executable component events are track for all the instances that form the flow.

The Probe Interface

All the probes implement the following basic API.

Probe interface

package org.meandre.core.engine;

import java.util.Date;

/** This interface define the API for the probing facility.
 * 
 * @author Xavier Llor&agrave;
 *
 */
public interface Probe {

	/** The probe commands */
	public static enum ProbeCommands { 
		FLOW_STARTED,				// Flow started executing
		FLOW_FINISHED,				// Flow finished executing
		FLOW_ABORTED,				// Flow aborted execution
		
		EXECUTABLE_COMPONENT_ABORTED,		// The executable component requested execution abortion
		EXECUTABLE_COMPONENT_INITIALIZED,	// The executable component has been initialized
		EXECUTABLE_COMPONENT_DISPOSED,		// The executable component has been initialized

		EXECUTABLE_COMPONENT_PUSH_DATA, 	// The executable component has push a piece of data
		EXECUTABLE_COMPONENT_PULL_DATA,	 	// The executable component has pull a piece of data

		EXECUTABLE_COMPONENT_GET_PROPERTY,	// The executable component got a property value
		
		EXECUTABLE_COMPONENT_FIRED,			// The executable component is being fired
		EXECUTABLE_COMPONENT_COOLING_DOWN	// The executable component is cooling down
	}
	
	/** Invoked when the probe object get instantiated.
	 * 
	 */
	public void initialize ();
	
	/** Invoked when the probe object has finished its live cycle.
	 * 
	 */
	public void dispose();
	
	/** Returns the serialized probe information.
	 * 
	 */
	public String serializeProbeInformation();
	
	/** The flow started executing.
	 * 
	 * @param sFlowUniqueID The unique execution flow ID
	 * @param ts The time stamp
	 */
	public void probeFlowStart(String sFlowUniqueID, Date ts, String weburl);
	
	/** The flow stopped executing.
	 * 
	 * @param sFlowUniqueID The unique execution flow ID
	 * @param ts The time stamp
	 */
	public void probeFlowFinish(String sFlowUniqueID, Date ts);
	
	/** The flow aborted the execution.
	 * 
	 * @param sFlowUniqueID The unique execution flow ID
	 * @param ts The time stamp
	 */
	public void probeFlowAbort(String sFlowUniqueID, Date ts,String message);

	/** The executable component finished initialization.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the initialization
	 * @param ts The time stamp
	 * @param bSerializeState The wrapped component is serialized
	 */
	public void probeExecutableComponentInitialized(String sECID, Object owc, Date ts, boolean bSerializeState);

	/** The executable component requested execution abortion.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the initialization
	 * @param ts The time stamp
	 * @param bSerializeState The wrapped component is serialized
	 */
	public void probeExecutableComponentAbort(String sECID, Object owc, Date ts, boolean bSerializeState);

	/** The executable component finished disposing itself.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the disposing call
	 * @param ts The time stamp
	 * @param bSerializeState The wrapped component is serialized
	 */
	public void probeExecutableComponentDisposed(String sECID, Object owc, Date ts, boolean bSerializeState);

	/** The executable component pushed a piece of data.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the disposing call
	 * @param odata The data being pushed
	 * @param ts The time stamp
	 * @param portName 
	 * @param bSerializeState The wrapped component is serialized
	 * @param bSerializedData The data provided has been serialized
	 */
	public void probeExecutableComponentPushData(String sECID, Object owc, Object odata, Date ts, String portName, boolean bSerializeState, boolean bSerializedData);

	/** The executable component pulled a piece of data.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the disposing call
	 * @param odata The data being pulled
	 * @param ts The time stamp
	 */
	public void probeExecutableComponentPullData(String sECID, Object owc, Object odata, Date ts,String portName, boolean bSerializeState, boolean bSerializedData);
	
	/** The executable component was fired.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the disposing call
	 * @param ts The time stamp
	 * @param bSerializeState The wrapped component is serialized
	 */
	public void probeExecutableComponentFired(String sECID, Object owc, Date ts, boolean bSerializeState);

	/** The executable component was fired.
	 * 
	 * @param sECID The unique executable component ID
	 * @param owc The wrapped component done with the disposing call
	 * @param ts The time stamp
	 * @param bSerializeState The wrapped component is serialized
	 */
	public void probeExecutableComponentCoolingDown(String sECID, Object owc, Date ts, boolean bSerializeState);

	/** The executable component requested a property value.
	 * 
	 * @param sECID The unique executable component ID
	 * @param sPropertyName The requested property
	 * @param sPropertyValue The property value
	 * @param ts The time stamp
	 */
	public void probeExecutableComponentGetProperty(String sECID, String sPropertyName, String sPropertyValue, Date ts);

}

Creating and Using Your Own Probes

When a specific probe is not provided by the infrastructure and a developer wants to provide one to monitor the flow on his/her own terms, the following steps must be followed:

Implement a Java class that implements the interface presented above.
Remember that a probe object will be created per flow execution, and that initialize and dispose will be call before and after the flow execution.
Compile the probe.
Add a entry to the probe configuration file for the new probe where the key is the logic name of the probe (see Meandre server configuration files for more details about the configuration file).
Add the compiled probe to the class path of Meandre Server (restart the server if appropriate).

Now the probe is available and can be used by the Meandre Server. To use the provided probe during the execution of a flow invoke the proper service adding logic name=true on the parameter list. For instance if we created a probe that has been assign the logic name foo on the probe configuration file, a flow using that probe could be executed using the call

http://some.meandre.sever:1714/services/execute/flow.txt?foo=true&rdf=true&statistics=true&uri=meandre://test.org/flow/test

The call shown above would execute the flow meandre://test.org/flow/test using three probes:

statistics (provided by the infrastructure which gathers various statistics about the flow execution)
rdf (provided by the infrastructure which generates a RDF model with the execution provenance of the flow, including all the data pass and component states)
foo (the external probe provided)

Extending flow execution probes

Table of contents

Probes

The Probe Interface

Creating and Using Your Own Probes

Labels