Creating an Analysis Engine

Table of Contents

1.0 Introduction
2.0 Creating an Analysis Engine
2.1 Implementing a log analyzer
2.2 Implementing an analysis engine
2.3 Testing the log analyzer
3.0 References

1.0 Introduction

This document provides a guideline for creating an analysis engine that can be used with the Eclipse workbench. The classes and the extension point required to create an analysis engine are described breifly in this document.

An analysis engine is an algorithm that takes data from a log file,compares it to rules or a set of rules in a symptom database, and returns an array of objects representing the solutions and directives for the matched symptoms. There are two components to an analysis engine:

Log analyzer: The component which is the plugged into the workbench and exposes the analysis engine to the user interface.

Analysis engine: The component that performs the data analysis.

The Log and Trace Analyzer provides a set of tools that can be used to implement an Analysis Engine and to plug it into the workbench.

2.0 Creating an Analysis Engine

2.1 Implementing a log analyzer

In order to plug an analysis engine into the workbench, the extension point org.eclipse.hyades.analysis.engine.LogAnalyzer must be used. The extension point associates the log analyzer to the analysis engine. The LogAnalyzer extension is recoginized by the Log View of the Log and Trace Analyzer, and is added as a menu selection for the Analyze and Analyze All menu actions.

The log analyzer class should be an implementation of the org.eclipse.hyades.analysis.engine.ILogAnalyzer interface.

To create a log analyzer, follow these steps:
Create a new plug-in project by selecting File > New > Other > Plug-in project.

Create a name for your plug-in project. Click Finish. Your plug-in project is created in the workspace.

Add the org.eclipse.hyades.analysis.engine plug-in to the project build path.
Create a new class that implements the interface org.eclipse.hyades.analysis.engine.ILogAnalyzer. This is required to plug the analysis engine into the workbench. The interface contains four methods that need to be implemented:
public void loadDatabase()
Used by the log viewer to load any neccessary symptom databases. The current Log and Trace Analyzer framework supports only EMF-based symptom databases. The method public void loadDatabase() can be used to load a symptom database. If you choose to use one of the databases imported into the workbench, the method public void loadDatabase() should check the org.eclipse.hyades.sdb.internal.util.SdUIConstants.SYMPTOM_DB_PATH_KEY preferences string. For example, String symptomdbPath = SDbPlugin.getDefault().getPreferenceStore().getString(SdUIConstants.SYMPTOM_DB_PATH_KEY);
The preference string is structured as follows:
symptom_db_path=project_path/symptomdb1_name.trcdbxmi,N;/project_path/symptomdb1_name.trcdbxmi,N
where symptom_db_path is the symptom database key
project_path is the project folder where the database has been imported into
symptomdb1_name.trcdbxmi, symptomdb2_name.trcdbxmi are the names of different symptom database files
and N is a flag that indicates whether or not a database should be used for analysis. A value of 1 indicates that the database should be used for the log analysis. The symtpom database entries are separated by semi-colons.
public void unloadDatabase()

Unload any symptom databases used for analysis purposes.

public String errorMsg()

If an error occurs during the analysis process, this method returns the corresponding error message. If there is no error, this method returns null.

public String analyze(Object aObject, IAnalysisMonitor monitor)
Analyzes an object or a collection of objects. The IAnalysisMonitor can be specified if a progress monitor is being used. The method public String analyze(Object aObject) is called by the Log Viewer when the menu item corresponding to the contributed log analyzer is selected. The implementation of this method should identify the incident(s) corresponding to the analyzed object(s), taking into account that the viewer is passing an IStructuredSelection to this method. The actual analysis processing should be delegated to the method public Object[] analyze(Incident incident) of the IAnalysisEngine implementation. This method should return an array of matched symptoms. The framework ignores the returned String of the public String analyze(Object aObject) method, only the analyzed object's symptoms list is used to display the analysis result. Every CBEDefaultEvent, in particular, the CBECommonBaseEvent object can keep a list of corresponding symptoms. The implementation should add the list of matched symptoms to this which is used by the framework to display the analysis results for every analyzed CBEDefaultEvent object. To obtain the list of symptoms:
EList symptoms = ((CBEDefaultEvent)object).getSymptoms();
Contribute the newly created class to the extension point org.eclipse.hyades.analysis.engine.logAnalyzer. Open the plugin.xml file and add the following lines:
<extension point="org.eclipse.hyades.analysis.engine.logAnalyzer">
 <logAnalyzer
   id="sampleLogAnalyzer.LogAnalyzerImpl"
   name="My Log Analyzer"
   type="org.eclipse.hyades.models.cbe.CBEDefaultEvent"
   class="sampleLogAnalyzer.LogAnalyzerImpl"/>
 </extension>
The name attribute will be the name of analyzer that shows up in the Analyze and Analyze All menu items.
The type attribute is used to specify the type of objects which are analyzed by the contributed log analyzer. Any object instantiated from a class implementing one of the following two interfaces is analyzable with the contributed log analyzer:

org.eclipse.hyades.models.cbe.CBEDefaultEvent

org.eclipse.hyades.models.cbe.CBECommonBaseEvent

The class attribute is used to specify the implementation of the interface ILogAnalyzer, i.e. the contributed log analyzer.
The id attribute is used to uniquely identify the extension point contribution.
Save the changes to the plugin.xml file.

2.2 Implementing an analysis engine

The analysis engine should be an implementation of the org.eclipse.hyades.analysis.engine.IAnalysisEngine interface. To create the analysis engine component, follow these steps:

In the plug-in project created in the previous section, add a Java class that implements the interface org.eclipse.hyades.analysis.engine.IAnalysisEngine. The following methods need to be implemented:

public boolean reloadSymptomDatabase()

Reloads the base symptom database from the base XML file.

public boolean mergeSymptomDatabase(String symptomDbPath)

Loads a new symptom database XML file denoted by the parameter path and merges any unique records with the base symptom database.

public boolean removeSymptomDatabase()

Removes the base symptom database.

public boolean removeSymptomDatabase()

A new symptom database is created denoted by the parameter XML file path. If the new symptom database XML file was successfully loaded, it replaces the base symptom database.

public String getSymptomDatabasePath()

Returns the XML file path of the base symptom database. If no base symptom database XML file is loaded, null is returned.

public Object[] analyze(Incident incident)

The current symptom database is searched for Incident matches. All Directive(s) from successful Incident matches are returned in an array structure. The implementation of public Object[] analyze(Incident incident) should look into the corresponding symptom database for the passed incident and return an array of matched symptoms back to the caller, i.e. the method public String analyze(Object aObject, IAnalysisMonitor aMonitor) from ILogAnalyzer or any helper method.

public Solution[] analyzeForSolutions(Incident incident)

Return an array of matched solutions, i.e. org.eclipse.hyades.analysis.engine.Solution, but as stated above the current design supports only EMF based symptom databases so it will work exclusively with org.eclipse.hyades.models.internal.sdb.SDBSolution objects, as a consequence the above mentioned method is ignored.

Save the Java class in your project.

2.3 Testing the analysis engine

Once you have created both the analysis engine and the log analyzer, you can test your analysis engine in the Log and Trace Analyzer.

From the Plug-in Development perspective, select the Run icon from the menu and select Run from the list.
In the Run configuration dialog, double-click on Run-time workbench. A new workbench configuration is created with details displayed in the right pane.
Under the Plug-in tab, verify that your plug-in is selected. Click Run. A new workbench is launched with your plug-in enabled.
In the new workbench, switch to the Profiling and Logging perspective.
Optional: If your analysis engine uses a database that needs to be imported into the workspace, ensure that it is properly imported using the File > Import > Symptom database option from the menu.
From the menu select File > Import.
In the Import wizard, select Log File and click Next.
On the Log Files page, click Add to add a log file.
In the Add Log File window, select the log file that you want to analyzer from the Selected log file list.
Specify a value for the log file location.
Click OK.
Click Finish to import the log file. The log file will be loaded in the Log Navigator view.
Right-click on the log file, and from the menu, select Open with > Log view. The log records of the log file are loaded in to the log view.
In the Log view, select one of the log records, right-click and select Analyzer > your log analyzer. Verify that the correct results are displayed in the Log view under the Analysis Result pane.

3.0 References

The Log and Trace Analyzer tool provides a default analysis engine and log analyzer implementation in org.eclipse.hyades.log.ui.internal.views.LogAnalyzerImpl and org.eclipse.hyades.log.ui.internal.views.AnalysisEngine.

A sample log analysis engine is provided in Hyades. To access the sample:

From the workbench, select File > New > Example.
Expand the node Hyades Logging and select Analysis Engine Sample.