Deploying the log parser plug-in project

Deploying the log parser plug-in project
Prerequisites

After you create a plug-in project to contain the artifacts for a log parser, you need to configure the plug-in so that it can be used by the Log and Trace Analyzer. Follow these steps:

Add plug-in dependencies to the plug-in's manifest file
Add an extension point for the log parser to the plug-in's manifest file
Create a static wrapper parser class
Verify the log parser plug-in settings
Packaging your log parser plug-in for deployment
Deploying your log parser

Add plug-in dependencies

The following plug-in dependencies must be included in the plug-in manifest file. Open the plugin.xml file in a text editor and add the following lines after the runtime element:
   
<requires>
 <import plugin="org.eclipse.ui"/>
 <import plugin="org.eclipse.core.runtime.compatibility"/>
 <import plugin="org.eclipse.hyades.logging.adapter"/>
 <import plugin="org.eclipse.hyades.logging.parsers"/>
 <import plugin="org.eclipse.hyades.logging.adapter.config"/>
</requires>
Add a log parser extension point

You need to define an extension point for each type of application log file that you want to parse and import into the Log and Trace Analyer. Below is a sample extension point for the MyApp application with both a rules adapter and static adapter defined:
 <extension
         point="org.eclipse.hyades.logging.parsers.logParser">
          <parser
            name="Sample Rules Adapter for MyApp"
            icon=""
            description="%STR_MYAPP_PARSER_DESCRIPTION"
            class="RulesParser.StaticParserExtension"
            ui_name="MyApp myapp.log file"
            id="org.eclipse.hyades.logging.parsers.MyAppLogParser">  
         <field
               useBrowse="true"
               defaultValue="d:\temp\sample.log"
               name="Directory"
               helpContextId=""
               tooltip="%STR_MYAPP_TOOLTIP1"
               id="file_path"
               browseType="*.log">
         </field>         
         <field
               useBrowse="false"
               defaultValue="MyApp 1.0(rules), MyApp 1.0(static)"
               name="Supported versions"
               helpContextId=""
               tooltip="%STR_MYAPP_TOOLTIP2"
               ui_type="combobox"
               id="version">
         </field>
         <parserParameter
               name="MyApp 1.0(rules)"
               value="./MyAdapter/myadapter.adapter">
    </parserParameter>
    <parserParameter
               name="MyApp 1.0(static)"
               value="./MyAdapter/mystaticadapter.adapter">
         </parserParameter>

      </parser>
   </extension>
To customize the extension point for your log parser, the updates need to be made:

Replace RulesParser in this extension point with the name of the plugin you created for the log parser plugin project.
Replace MyAdapter in this extension point with the folder name in your plugin that contains your adapter files.
The <parser> tag specifies high-level information for the parser and it is a required element. Replace the following attributes:

name- the name of this parser (can be the same as ui_name)
description - a description of this parser that will be shown in the Import Log File wizard when this parser is selected
icon - the icon that will be shown in the Import Log File wizard for this parser
class - the full class name of the parser wrapper class
ui_name - the name of this parser that will be included in the Selected log file list in the Import Log File wizard
id - a unique identifier for this parser extension point

The first <field> tag defines the UI field for selecting the location of the log file. It is a required element. Replace the following attributes:

useBrowse - whether a browse button is displayed for this field
defaultValue - default value shown in this field
name - name of this field that is shown in the Import Log File wizard
tooltip - help text that will be shown in the Import Log File wizard when the cursor hovers over the field
id - name of this field that will be passed to the parser wrapper class - do not change this name
browseType - the type of files shown in the browse dialog

The second <field> tag defines the UI Combo box for selecting the version of the log file to be imported. It is a required element. Replace the following attributes:

defaultValue - list all of the versions that you want displayed in the combobox list
name - name of this field that is shown in the Import Log File wizard
tooltip - help text that will be shown in the Import Log File wizard when the cursor hovers over the field
id - name of this field that will be passed to the parser wrapper class - do not change this name
ui_type - indicates this is a combobox field

The <parserParameter> tag defines which Adapter Configuration file to use for each log file version supported. Replace the following attributes:

name - Adapter Configuration file name needs to match the version string exactly as listed in the UI Combo box defaultValue attribute.
value - directory and name of the Adapter Configuration file

Hint: A Default should be defined in case a match for a version cannot be found. If you only have one adapter configuration file then you only need to have the following Default parserParameter:
<parserParameter
   name="Default"
   value="./MyAdapter/myadapter.adapter">
</parserParameter>
The fields specified above will create an option for MyApp myapp.log in the Import Log wizard as shown below:

You can use a plugin.properties file to define certain properties in the plugin.xml file that may need to have different versions. For example, if there are text strings that will be included on the Import Log File wizard that need to be translated to different languages, they can be defined in the plugin.properties file and you can include different properties files for the languages you want to support. In the plugin.properties file you define substitution variables that can be used in the plugin.xml file. The plugin.properties file for the above plugin.xml would look like this:
# Properties for RulesParser Plugin

pluginName = RulesParser
providerName = MyCompany

# logParser extension point message(s):
STR_MYAPP_PARSER_DESCRIPTION = MyApp rules parser v1.0
STR_MYAPP_TOOLTIP1           = Enter the location of the log file
STR_MYAPP_TOOLTIP2           = Select the version of the log file to import
Create a wrapper class for the parser

Create a static wrapper class that extends the org.eclipse.hyades.logging.adapter.config.StaticParserWrapper. This class is used for both static and rules-based parsers. Create the class in the log parser plug-in project. You can use the example class below by replacing RulesParser with the name of your log parser plug-in project.
/*
 * Created on Apr 12, 2004
 * StaticParserExtension class created to be used in RulesParser Plug-in
 */
package RulesParser;

import org.eclipse.hyades.logging.adapter.config.StaticParserWrapper;

/**
 * @author developer
 * StaticParserExtension class
 */
public class StaticParserExtension extends StaticParserWrapper {
    public StaticParserExtension(){
        super();
        currentPlugin="RulesParser"; 
    }
}
Verify the log parser plug-in settings

To verify that you have correctly configured the plug-in manifest file, you can run your plug-in project in a new run-time workbench. Follow these steps:

Switch to the Plug-in perspective by selecting Window > Open perspective > Other > Plug-in Development.
From the Plug-in Development perspective, select your plug-in project.
From the toolbar, select Run > Run As > Run-time Workbench.
In the new workbench, 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, verify that your new log file type is included in the Selected log file list.
Select your log file type. Verify that all of the fields and text on the Details tab is correct.
Specify the value for the log file location.
Click OK.
Click Finish to import the log file of your new log file type. Verify that the log file records are displayed in the Log View.

Packaging your log parser plug-in for deployment

To deploy your log parser plug-in to an eclipse workbench you need to package the plug-in files by exporting them to a zip file. Follow these steps:
Open the plugin.xml file in a text editor.
Verify that it includes a runtime library jar file for your plug-in class files. For example:
    <runtime>
        <library name="parsers.jar">
            <export name="*"/>
        </library>
    </runtime>
    
To deploy your log parser to a remote host so that you can import log files from that remote host, create an Agent Controller plug-in configuration file for your log parser. Follow these steps:
Create a folder in your log parser plug-in called config.
Create a file called pluginconfig.xml in the config folder. For example:
<?xml version="1.0" encoding="UTF-8"?>
<PluginConfiguration>
<Application configuration="default" 
    executable="RemoteLogParserLoader" 
    extends="default" 
    location="%RASERVER_HOME%\plugins\RulesParser_1.0.0" 
    path="%JAVA_PATH%">
<Variable name="CLASSPATH" 
    position="prepend" 
    value="%RASERVER_HOME%\plugins\RulesParser_1.0.0\parsers.jar"/>
</Application>
<Option name="RulesParser" type="version" value="1.0.0"/>
</PluginConfiguration>
Replace RulesParser with the name of your log parser plug-in project.
Note: If you are extending an existing parser, you need an additional parameter in the pluginconfig.xml to specify the root directory of the parent adapter files. The following parameters are required:
 <Variable name="GLA_CONFIG_PATH" position="append" value="%RASERVER_HOME%\plugins\PARSER_PLUGIN\config"/>
   <Parameter position="append" value="config_path=%GLA_CONFIG_PATH%"/>
 
where PARSER_PLUGIN is the directory of the log parser you are extending. The new <Variable> element has to be added as the first child node of the <Application> element while the new <Parameter> element has to be added as the last child of the <Application> element.
Open the build.properties file in a text editor.
Add the folder where your adapter configuration files are stored and the plugin.properties file to the Binary Build list. Also add the config folder if you will be deploying on a remote host. For example here is an example build.properties file:
bin.includes = MyAdapters/,\

config/,\

plugin.xml,\

plugin.properties,\

parsers.jar
source.parsers.jar = src/
output.parsers.jar = bin/
Export the plug-in files by selecting File > Export.
In the Export wizard, select > Deployable plugins and fragments.
Click Next.
On the Export Plugins and Fragments page, select your plug-in in the Available Plugins and Fragments list.
Select deploy as a single deployable ZIP file in the Export Options field.
Specify the destination File name for the zip file.
Click Finish.
Deploying your log parser

You can deploy your log parser plug-in by unzipping the zip file you just created in the plugin directory of an eclipse installation. You are now ready to test your newly created log parser plug-in using the Log and Trace Analyzer.

To deploy your log parser plug-in on a remote system so a log file can be imported remotely, unzip the zip file you just created in the Agent Controller installation directory on the remote system.

Related Concepts
Common Base Event format specification

Related tasks
Creating a log parser
Creating a static adapter
Creating a rules-based adapter
Testing a log parser
Setting up a plug-in project for a log parser

Related references
Adapter Configuration File structure
Adapter Configuration Editor
Regular expression grammar