Deploying the log parser plug-in project

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:

1. Add plug-in dependencies to the plug-in's manifest file
2. Add an extension point for the log parser to the plug-in's manifest file
3. Create a static wrapper parser class
4. Verify the log parser plug-in settings
5. Packaging your log parser plug-in for deployment

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:

1. Replace RulesParser in this extension point with the name of the plugin you created for the log parser plugin project.
2. Replace MyAdapter in this extension point with the folder name in your plugin that contains your adapter files.
3. 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
4. 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
5. 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
6. 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

<parserParameter
   name="Default"
   value="./MyAdapter/myadapter.adapter">

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:

1. Switch to the Plug-in perspective by selecting Window > Open perspective > Other > Plug-in Development.
2. From the Plug-in Development perspective, select your plug-in project.
3. From the toolbar, select Run > Run As > Run-time Workbench.
4. In the new workbench, from the menu, select File > Import.
5. In the Import wizard, select Log File and click Next.
6. 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.
7. Select your log file type. Verify that all of the fields and text on the Details tab is correct.
8. Specify the value for the log file location.
9. Click OK.
10. 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:

1. Open the plugin.xml file in a text editor.
2. 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>
   	

3. To deploy your log parser to a remote host so that you can import log files from that remote host, you must create an Agent Controller plug-in configuration file for your log parser. Follow these steps:
   1. Create a folder in your log parser plug-in called config.
   2. 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>
      

   3. Replace RulesParser with the name of your log parser plug-in project.
4. Open the build.properties file in a text editor.
5. 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/
   

6. Export the plug-in files by selecting File > Export.
7. In the Export wizard, select > Deployable plugins and fragments.
8. Click Next.
9. On the Export Plugins and Fragments page, select your plug-in in the Available Plugins and Fragments list.
10. Select deploy as a single deployable ZIP file in the Export Options field.
11. Specify the destination File name for the zip file.
12. Click Finish.

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.

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

(C) Copyright IBM Corporation 2000, 2004. All Rights Reserved.