Extending Eclipse monitoring, profiling, and testing functions
Previous Page	Home	Next Page

Extending the monitoring, profiling, and testing functions Extending the logging function Common Log Analyzer Framework

Log Correlation APIs

The log correlation service provides a set of APIs to correlate a list of trace log agents. The following workflow shows the steps to correlate two log agents.:

Create a list of log agents to correlate.
Create a correlation facade.
Select a correlation operation from a list of registered operations.
Create a context object that will contain information needed by the correlation operation.
Create a container that will hold the contents of the correlation.
Create the correlation.
Check the context status to determine if the correlation operation was successful.

The following code snippet illustrates this workflow and demonstrates how to correlate a set of trace log agents.

1	List agentsList = new ArrayList(); agentsList.add(apacheAccessAgentProxy); agentsList.add(apacheErrorAgentProxy);
2	ICorrelationFacade facade = CorrelationFacadeFactoryWrapper.instance();
3	IConfigurationElement[] operations = facade.getRegisteredCorrelationExtensions(); IConfigurationElement operation = operations[0];
4	ICorrelationOperationContext context = facade.createOperationContext(); context.setProperty(ICorrelationFacade.PROGRESSMONITOR, new MyProgressMonitor());
5	CorrelationContainerProxy container = facade.createCorrelationContainer(agentsList, operation, context, "MyContainerName");
6	facade.createCorrelation(operation, container, agentsList, context);
7	if (context.getStatus().isOK()) System.out.println("Correlation successful!");

1. Create a list of log agents to correlate

A list of log trace log agent proxy objects should be created that will contain a list of common base events that will be correlated.

2. Create a correlation facade

ICorrelationFacade provides all the necessary APIs to perform a correlation operation. The following factory method should be used to create the ICorrelationFacade instance.

CorrelationFacadeFactoryWrapper.instance()

3. Select a correlation operation from a list of registered operations

A list of correlation operations can be registered with the service. The following two extension points that can be used to register correlation operations.

org.eclipse.tptp.platform.common.ui.trace.logInteractionView - extension point used to register legacy correlation operations
org.eclipse.hyades.analysis.engine.correlationEngine - extension point used to register new correlation operations

There are two corresponding ICorrelationFacade APIs to get a list of registered correlation operations from both of the above extension points.

public ICorrelationOperation[] getRegisteredCorrelationOperations()
public IConfigurationElement[] getRegisteredCorrelationExtensions()

A particular correlation operation should be selected from the above lists. Notice that getRegisteredCorrelationExtensions will get list of registered legacy correlation operations while the getRegisteredCorrelationOperations will get the list of new correlation operations.

4. Create a context object that will contain information needed by the correlation operation

Each correlation operation may require specific configuration information to complete the operation. Specific configuration information is passed to the correlation operation via the context object. One should consult the java doc for each correlation operation to determine the configuration information needed. Some legacy correlation operations require a progress monitor operation that implements the org.eclipse.tptp.platform.provisional.correlation.common.IOperationMonitor interface.

5. Create a container that will hold the contents of the correlation

A correlation container is needed to hold the results of the correlation. The following ICorrelationFacade APIs create a correlation container.

public CorrelationContainerProxy createCorrelationContainer(List agents, ICorrelationOperation operation, IOperationContext context, String name);
public CorrelationContainerProxy createCorrelationContainer(List agents, IConfigurationElement operation, IOperationContext context, String name);

Depending on the type of correlation operation one would use a particular API The above API requires the list of agents to correlate, the correlation operation, a context object that contains configuration information and the name of the correlation container.

6. Create the correlation

The next step is to correlate the list of log agents using one of the following APIs.

public void createCorrelation(ICorrelationOperation operation, CorrelationContainerProxy container, List events, List agents, ICorrelationOperationContext context)
public void createCorrelation(IConfigurationElement operation,CorrelationContainerProxy container, List agentsList, ICorrelationOperationContext context)

7. Check the context status to determine if the analysis operation was successful

Once the correlation has completed status information should be checked to make sure the correlation operation was successful. The status information is stored in a org.eclipse.tptp.platform.provisional.correlation.common.IOperationStatus instance which can be extracted from the context object.