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:

  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. Add an extension point for static parsers
  4. Create a wrapper parser class
  5. Verify the log parser plug-in settings
  6. Packaging your log parser
  7. Deploying your log parser

1. 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. Locate the required element in the file and add the plug-in dependencies to it. For example:

   
<import plugin="org.eclipse.core.runtime"/>  
<requires>
<import plugin="org.eclipse.hyades.logging.adapter"/>
<import plugin="org.eclipse.hyades.logging.parsers"/>
<import plugin="org.eclipse.hyades.logging.adapter.config"/>
</requires>

Note: The required plug-ins specified above must either be located in the eclipse plugins directory or must be included in the current workspace.


2. 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:
  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:
  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:
  6. The <parserParameter> tag defines which Adapter Configuration file to use for each log file version supported. Replace the following attributes:
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 Default parserParameter. For example:
<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:

Import Log wizard showing the myapp myapp.log as an option to import

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

Hint: An application may write data to its log file in different languages, depending on the locale that it is running in. Static parser classes or regular expression rules are written to parse a log file in a single language. Therefore, to support a log file type that can be written in many languages, a separate static parser adapter file or rules adapter file must be created for each language. Then, in the logParser extension point for that log file type, a parserParameter tag should be added for each adapter file, specifying the language it applies to in the name field. Do not forget to add the parserParameter name values to the list in the version field defaultValue attribute. This will allow a user to choose the correct language of the log file when importing the log file.

For example, the following parser parameters can be added to the logParser extension point to support importing English, French and German logs:

	         <parserParameter               
	         	name="MyApp 1.0(rules) English"               
	         	value="./MyAdapter/myadapter_en.adapter"/>         
	         <parserParameter               
	         	name="MyApp 1.0(rules) French"               
	         	value="./MyAdapter/myadapter_fr.adapter"/>         
	         <parserParameter               
	         	name="MyApp 1.0(rules) German"               
	         	value="./MyAdapter/myadapter_de.adapter"/>

3. Add an extension point for static parsers

This step is required if you are creating a static parser.

For static parsers, the static parser class that you created must be specified in the plugin.xml using a staticParser extension. This extension point will allow the class can be found when it is used to parse a file in the Log Import scenario.
Add the following extension point:

<extension
  point="org.eclipse.hyades.logging.adapter.config.staticParser">
  <parserClassname
    name="myLogParser33.MyStaticParser">
  </parserClassname>
</extension>

Replace myLogParser33.MyStaticParser with your Java parser class name.

4. 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 to execute the adapter configuration file associated with the version selected by the user in the Log Import wizard, using the Generic Log Adapter run-time.

/*
 * 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"; 
	}
}

5. 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.
    Hint: If no log file records are displayed in the Log View, verify that the Outputter component in the parser adapter configuration file is configured with the execution class org.eclipse.hyades.logging.adapter.config.outputters.StaticParserOutputter.

6. Packaging and deploying your log parser plug-in

Local 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 with the Plug-in Manifest editor.
  2. Select the Runtime tab and verify that a jar file for your plugin classes is included in the Run-time libraries list. If there is no jar file listed then add one by clicking the New... button and specifying an appropriate name.
  3. Select the Build tab and check the appropriate files and folders in the Binary Build list that will be included in your exported plugin. For example, check the plugin.xml, plugin.properties and parser adapter configuration files. Save the changes to the plugin.xml file.
  4. Export the plug-in files by selecting File > Export.
  5. In the Export wizard, select > Deployable plugins and fragments.
  6. Click Next.
  7. On the Export Plugins and Fragments page, select your plug-in in the Available Plugins and Fragments list and check its check box.
  8. Select deploy as a single ZIP file in the Export Options field.
  9. Specify the destination File name for the zip file.
  10. Click Finish.

Remote deployment

To deploy your log parser to a remote host so that you can import log files from that remote host, you must create a Agent Controller plug-in configuration file for your log parser. Follow these steps:
  1. Open the plugin.xml file with the Plug-in Manifest editor.
  2. Select the Runtime tab and verify that a jar file for your plugin classes is included in the Run-time libraries list. If there is no jar file listed then add one by clicking the New... button and specifying an appropriate name.
  3. Create a folder in your log parser plug-in called config.
  4. Create a file called pluginconfig.xml in the config folder. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    <PluginConfiguration requires="org.eclipse.hyades.logging.parsers">
        <Application configuration="default" 
            executable="RemoteLogParserLoader" 
            extends="default" 
            location=="%SYS_TEMP_DIR%" 
            path="%JAVA_PATH%">
            <Variable name="CLASSPATH" 
                position="prepend" 
                value="%RASERVER_HOME%\plugins\RulesParser_1.0.0\parsers.jar"/>
            <Variable name="GLA_CONFIG_PATH" position="prepend" value="%RASERVER_HOME%\plugins\RulesParser_1.0.0"/>
            <Parameter position="append" value=""config_path=%GLA_CONFIG_PATH%""/>    
        </Application>
    <Option name="RulesParser" type="version" value="1.0.0"/>
    </PluginConfiguration>
    

  5. Replace RulesParser with the name of your log parser plug-in project.
  6. Open the plugin.xml file with the Plug-in Manifest editor.
  7. Select the Build tab and check the appropriate files and folders in the Binary Build list that will be included in your exported plugin. For example, check the plugin.xml, plugin.properties, the parser adapter configuration files and the pluginconfig.xml file that was just created. Save the changes to the plugin.xml file.
  8. Export the plug-in files by selecting File > Export.
  9. In the Export wizard, select > Deployable plugins and fragments.
  10. Click Next.
  11. On the Export Plugins and Fragments page, select your plug-in in the Available Plugins and Fragments list and check its check box.
  12. Select deploy as a single ZIP file in the Export Options field.
  13. Specify the destination File name for the zip file.
  14. Click Finish.

7. Deploying your log parser

You can deploy your log parser plug-in by unzipping the zip file you just created in the eclipse 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. Re-start the Agent Controller.

 

Related concepts
Common Base Event format specification

Related tasks
Creating a log parser
Creating a static adapter
Creating a rule-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