Attachment 27760 Details for Bug 79114 – Document for this feature to be posted on the web site

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Document for this feature to be posted on the web site

GLA_pkg.html (text/html), 25.13 KB, created by Dave Smith

on 2005-10-03 09:33:54 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: Dave Smith

Created: 2005-10-03 09:33:54 EDT

Size: 25.13 KB

patch

obsolete

><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
><html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
><title>Transforming log and trace data in your application</title>
><link rel="stylesheet" type="text/css" href="http://www.eclipse.org/tptp/eclipse_style.css" >
></head>
>
><body>
>    <div id="page_header">Eclipse Test and Performance Tools Platform Project</div>
><div id="section_header">Transforming log and trace data in your application with Generic Log Adapter</div>
><div class="content">
>
><p>
><p>October 3, 2005</p>
><p>Author:  Dave Smith  (smith@ca.ibm.com)
><p>
><div id="section_hlight">Table of Contents:</div>
><div id="main_content">
><A href="#1.0">1.0 Introduction</A><br>
><A href="#2.0">2.0 Programming with the GLA API</A><br>
><A href="#3.0">3.0 Coding a simple example</A><br>
><A href="#4.0">4.0 Packaging GLA with your application</A><br>
><A href="#4.1">4.1 Packaging the run-time JAR files</A><br>
><A href="#4.2">4.2 Packaging the schema files</A><br>
><A href="#4.3">4.3 Packaging the adapter configuration files</A><br>
><A href="#5.0">5.0 Downloading the GLA files</A><br>
></div>
><br>
><br>
><br>
>
><div id="section_hlight"><A name="1.0">1.0 Introduction</div>
><div id="main_content">
><P>Generic Log Adapter (GLA) transforms proprietary log and trace data to the
>Common Base Event format. It is a feature of the Eclipse Test and
>Performance Tools Platform (TPTP) project.
></P>
><P>GLA parses log files based on regular expression rules or java
>parsing classes specified in adapter configuration files. The
>configuration files define how to transform log file records into a
>standard form that can be used by other tools. Currently, GLA
>transforms log file records into standard Common Base Event objects.
>However, GLA is extendable to generate any kind of structured
>event representation.</P>
><p>GLA is written in the Java programming language and can
>easily be embedded in any Java application. The application may be a tool for
>examining or processing log files.
>For example, in TPTP, Log and Trace Analyzer uses GLA to import log files
>so that they can be displayed and correlated in the views of Log and Trace Analyzer.</p>
><p>Another example use of GLA is for an application that generates a log file in a
>proprietary format.  The application can make its log file available for an administrator
>to monitor with TPTP Log and Trace Analyzer.  Using the Adapter Configuration Editor in the Generic
>Log Adapter perspective of TPTP, an adapter configuration file can be created that continuously parses the
>proprietary log data into CommonBaseEvent objects and sends them to a logging agent.
>The application can create an instance of GLA to run the adapter configuration file in a
>separate thread.  An administrator can then attach to the logging agent for the application
>using Log and Trace Analyzer and continuously monitor the log of the application in the Log View
>of Log and Trace Analyzer.</p>
>
><p>This document is intended for application developers who want to exploit the GLA technology in their
>programs to transform log and trace data to a standard format like Common Base Event.
>The programming interface and packaging details required to use GLA in another application are described.
>The discussion is based on TPTP 4.0 version of GLA.</p>
>
><p>This document assumes the reader is familiar with the concepts
>of GLA and how to create an adapter configuration file using Adapter Configuration Editor.  For more information on
>GLA and how to use the Adapter Configuration Editor, see the video <a href="http://www.eclipse.org/tptp/home/documents/tutorials/gla/GLA_Intro/GLA_Intro.viewlet/GLA_Intro_viewlet_swf.html" TARGET="_blank">
>An Introduction to the Generic Log Adapter</a></p>
></div>
><br>
><br>
><br>
><div id="section_hlight"><A name="2.0">2.0 Programming with the GLA API</div>
><div id="main_content">
><p>GLA is implemented in the <i>org.eclipse.hyades.logging.adapter</i> plugin.
>To use GLA in an application, the main class <i>org.eclipse.hyades.logging.adapter.Adapter</i>
>must be instantiated.  You can use the following Adapter instance methods to configure and run
>GLA.</p>
>
>
><A NAME="setContextConfigPath(java.lang.String)"></A><H3>

>setContextConfigPath</H3>

><PRE>

>public void <B>setContextConfigPath</B>(java.lang.String&nbsp;configFilePath)</PRE>

><DL>

><DD>Sets the file path of the context configuration portion of the
> adapter configuration. This method must be called before the validate and start
> methods in order for the configuration to be used.  If this method is
> not called, the default file name SimpleContextConfiguration.xml will be used.
> Use the Adapter Configuration Editor to generate the configuration file.
> <p>Typically, the context configuration and component configuration are created in the same file using
> Adapter Configuration Editor.  In this case, call setContextConfigPath and setComponentConfigPath with
> the same file path.

><P>

><DD><DL>

><DT><B>Parameters:</B><DD><CODE>configFilePath</CODE> - The file path of the context configuration</DL>

></DD>

></DL>

><HR>

><A NAME="setComponentConfigPath(java.lang.String)"></A><H3>

>setComponentConfigPath</H3>

><PRE>

>public void <B>setComponentConfigPath</B>(java.lang.String&nbsp;configFilePath)</PRE>

><DL>

><DD>Sets the file path of the component configuration portion of the
> adapter configuration. This method must be called before the validate and start
> methods in order for the configuration to be used.  If this method is
> not called, the default file name SimpleComponentConfigurations.xml will be used.
> Use the Adapter Configuration Editor to generate the configuration file.
> <p>Typically, the context configuration and component configuration are created in the same file using
> Adapter Configuration Editor.  In this case, call setContextConfigPath and setComponentConfigPath with
> the same file path.

><P>

><DD><DL>

><DT><B>Parameters:</B><DD><CODE>configFilePath</CODE> - The file path of the component configuration</DL>

></DD>

></DL>

><HR>

><A NAME="validate()"></A><H3>

>validate</H3>

><PRE>

>public void <B>validate</B>()
>              throws <A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></PRE>

><DL>

><DD>Validates the Generic Log Adapter configuration files specified using the setContextConfigPath and setComponentConfigPath
>methods.  If you do not specify the context or component configuration file paths, the default configuration files SimpleContextConfiguration.xml
>and SimpleComponentConfigurations.xml are validated. It initializes the Adapter instance with the
>configuration specified in the configuration files but does not run the Adapter instance.
>To run the Adapter use the start method.

><P>

><DD><DL>

>
><DT><B>Throws:</B>
><DD><CODE><A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></CODE> - if the configuration is invalid</DL>

></DD>

></DL>

><HR>

><A NAME="start(boolean, boolean)"></A><H3>

>start</H3>

><PRE>

>public void <B>start</B>(boolean&nbsp;separateThread,
>                  boolean&nbsp;daemon)
>           throws <A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></PRE>

><DL>

><DD>Starts Generic Log Adapter with the configuration files specified using the setContextConfigPath and setComponentConfigPath
>methods. If you do not specify the context or component configuration file paths, the Adapter instance uses SimpleContextConfiguration.xml
>and SimpleComponentConfigurations.xml as the default configuration files, respectively.  Note, the configuration files are
>validated before the Adapter instance uses them.
><p>Generic Log Adapter can be started in a separate thread by specifying true as the first parameter and in addition started as a daemon thread
>by specifying true for both parameters.  If true is specified as the first parameter, start will return immediately after starting
>the Generic Log Adapter thread.  Otherwise, if the first parameter is false, Generic Log Adapter will be started in the current
>thread, regardless of the value of the second parameter, and start will return when Generic Log Adapter has finished executing all
>of the contexts configured in the Adapter instance.  Generic Log Adapter runs each context configured in the Adapter instance in
>a separate thread.  Therefore, if the Adapter instance is configured with two contexts and start(true, true) is called, three threads will
>be started to execute Generic Log Adapter with two contexts.

></P>

><DD><DL>

><DT><B>Parameters:</B>
><DD><CODE>separateThread</CODE> - Run the adapter in a separate thread
><DD><CODE>daemon</CODE> - Run the adapter as a daemon thread.
><DT><B>Throws:</B>
><DD><CODE><A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></CODE> - If an error occurs during execution.</DL>

></DD>

></DL>

><HR>

><A NAME="stop()"></A><H3>

>stop</H3>

><PRE>

>public void <B>stop</B>()</PRE>

><DL>

><DD>Stops all of the adapter contexts.  Data still being processed
> by the contexts will be flushed to the last component of each context. The stop method
> waits until all contexts are stopped before stopping the internal Generic Log Adapter
> logging context in order to capture all messages from all contexts.

><P>

><DD><DL>

></DL>

></DD>

></DL>

><HR>

><A NAME="hardStop()"></A><H3>

>hardStop</H3>

><PRE>

>public void <B>hardStop</B>()</PRE>

><DL>

><DD>Stops all of the adapter contexts.  Data still being processed
> by the contexts will be flushed to the last component of each context.
> The hardStop method also disables any context listeners during flushing.
> Context listeners implement the <a href="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/IContextListener.html" title="interface in org.eclipse.hyades.logging.adapter">IContextListener</a> interface and are only
> supported when Generic Log Adapter is running in an Eclipse environment.
> The hardStop method does not wait for all contexts to stop before
> stopping the internal Generic Log Adapter logging context so some messages
> from the other contexts may not be captured.
></DD>

><P>

><DD><DL>

></DL>

></DD>

></DL>

><HR>

><A NAME="main(java.lang.String[])"></A><H3>

>main</H3>

><PRE>

>public static void <B>main</B>(java.lang.String[]&nbsp;args)</PRE>

><DL>

><DD>Adapter main method to run Generic Log Adapter as a standalone application.

><P>

><DD><DL>

><DT><B>Parameters:</B><DD><CODE>args</CODE> - -cc contextConfigurationPath -ac componentConfigurationPath</DL>

></DD>

></DL>

><HR>

><A NAME="getStatus()"></A><H3>

>getStatus</H3>

><PRE>

>public <A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/IStatus.html" title="interface in org.eclipse.hyades.logging.adapter">IStatus</A> <B>getStatus</B>()</PRE>

><DL>

><DD>Gets the status of the adapter instance.

><P>

><DD><DL>

>
><DT><B>Returns:</B><DD>the org.eclipse.hyades.logging.adapter.IStatus object representing the status.</DL>

></DD>

></DL>

><HR>

><A NAME="setLogOutputter(org.eclipse.hyades.logging.adapter.IOutputter)"></A><H3>

>setLogOutputter</H3>

><PRE>

>public void <B>setLogOutputter</B>(<A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/IOutputter.html" title="interface in org.eclipse.hyades.logging.adapter">IOutputter</A>&nbsp;outputter)</PRE>

><DL>

><DD>Set the Adapter log outputter for Generic Log Adapter messages.  Generic Log Adapter uses an internal context
> to log trace and error messages during the execution of the Adapter instance.  The outputter specified with
> setLogOutputter is used in the internal logging context.  This method should be
> called before calling validate() and start(), which may log validation and run-time execution messages.
> If this method is not called, GLA will log its messages to the file <i>hgla.log</i> in
> the current directory.

><P>

><DD><DL>

><DT><B>Parameters:</B><DD><CODE>outputter</CODE> - component where GLA will log its messages.</DL>

></DD>

></DL>

><HR>
>
><p>The methods are typically called in the following order: </p>
>
><ol>
><li>   <code>setContextConfigPath(adapterConfigFileName)</code>
><li>   <code>setComponentConfigPath(adapterConfigFileName)</code>
><li>   <code>setLogOutputter(glaLogOutputter)</code> - optional
><li>   <code>validate()</code> - optional
><li>   <code>start(separateThread, daemonThread)</code>
></ol>
><p>The following methods are typically called from a different thread than the one that called
>start if start is called with <i>separateThread</i>=false.
>If start is called with <i>separateThread</i>=true
>then these methods can be called from the same thread that called start. </p>
>
><ul>
><li><code>getStatus()</code> - to get the status of the adapter execution
><li><code>stop()     </code> - to stop the adapter execution
><li><code>hardstop() </code> - to stop the adapter execution
></ul>
>
><p><b>Note:</b> Missing from this programming interface is
>the ability to create or modify adapter configuration files programmatically.
>This capability is under consideration for a future release. Please see the TPTP
>feature enhancement request <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=96433">96433</a></p>
>
></div>
><br>
><br>
><br>
>
><div id="section_hlight"><A name="3.0">3.0 Coding a simple example</div>
><div id="main_content">
><p>The following example shows a simple main program to run the
>adapter configuration file <i>c:\test.adapter</i>.</p>
>
><pre>
>import org.eclipse.hyades.logging.adapter.Adapter;
>import org.eclipse.hyades.logging.adapter.AdapterException;
>import org.eclipse.hyades.logging.adapter.IStatus;
>import org.eclipse.hyades.logging.adapter.impl.Status;
>import org.eclipse.hyades.logging.adapter.outputters.CBEFileOutputter;
>
>public class RunAdapter {
>
>    /**
>     * This is a simple program to run the Generic Log Adapter
>     * with a hardcoded adapter configuration file.
>     */
>    public static void main(String[] args) {
>
>        String adapterConfigFile = "c:\\test.adapter";
>
>        /* Create an Adapter instance */
>        Adapter adapter = new Adapter();
>
>        /* Set the adapter configuration file */
>        adapter.setContextConfigPath(adapterConfigFile);
>        adapter.setComponentConfigPath(adapterConfigFile);
>
>        /* Create a file outputter to capture GLA
>         * log messages.
>         * WARNING:  The following code does not work
>         * in TPTP 4.0 due to bugzilla 108187 in
>         * CBEFileOutputter.  Please comment the
>         * following three lines of code if using
>         * TPTP 4.0.
>         */
>        CBEFileOutputter fo = new CBEFileOutputter();
>        fo.setDirectory("c:\\logs");
>        fo.setFileName("testgla.log");
>
>        /* Set the outputter to capture the GLA log messages */
>        adapter.setLogOutputter(fo);
>
>        /* Validate the adapter configuration file */
>        try {
>            adapter.validate();
>        }
>        catch (AdapterException e) {
>            System.err.println("Adapter configuration file is invalid.");
>            System.err.println(e.getMessage());
>            return;
>        }
>
>        System.out.println("Adapter configuration was validated.");
>
>        /* Start the adapter as a separate thread */
>        try {
>            adapter.start(true, true);
>        }
>        catch (AdapterException e) {
>            /* If we get an exception at this point we likely do
>             * not have a valid configuration and hence the log file
>             * is likely not flushed.  We need to write this to stderr.
>             */
>            System.err.println("GLA Exception occurred");
>            System.err.println(e.getMessage());
>            adapter.stop();
>            return;
>        }
>
>        System.out.println("Adapter was started.");
>
>        /* Wait 30 seconds */
>        try {
>            Thread.sleep(30000);
>        }
>        catch (InterruptedException e) {
>        	
>        }
>
>        /* Get the adapter status */
>        IStatus status = adapter.getStatus();
>
>        if (status != null) {
>            /* print the current adapter status out */
>            printAdapterStatus(status);
>        }
>
>        /* If the adapter is still running then stop it */
>        if (status != null && status.isActive()) {
>            adapter.stop();
>            System.out.println("Adapter was stopped.");
>        }
>    }
>
>    /**
>     * Print the adapter status.
>     *
>     * @param status Adapter IStatus object
>     */
>    private static void printAdapterStatus(IStatus status) {
>        /* print the current adapter status out */
>        if (status.isActive()) {
>            System.out.println("Adapter is active!  It has processed "
>                + status.getItemsProcessedCount() + " items in "
>                + ((Status)status).getElpasedTimeInSeconds()
>                + " seconds.");
>        }
>        else {
>            System.out.println("Adapter is not active!  It processed "
>                + status.getItemsProcessedCount() + " items in "
>                + ((Status)status).getElpasedTimeInSeconds()
>                + " seconds.");
>        }
>    	
>        /* Get the status of the contexts */
>        IStatus [] contexts = status.getChildrenStatus();
>
>        if (contexts != null && contexts.length > 0) {
>            for (int i=0; i < contexts.length; i++) {
>                /* For each context, print its status */
>                if (contexts[i] != null) {
>                    IStatus cstatus = contexts[i];
>                    if (cstatus.isActive()) {
>                        System.out.println("Context " + cstatus.getName()
>                            + " is active!  It has processed "
>                            + cstatus.getItemsProcessedCount()
>                            + " items in "
>                            + ((Status)cstatus).getElpasedTimeInSeconds()
>                            + " seconds.");
>                    }
>                    else {
>                        System.out.println("Context " + cstatus.getName()
>                            + " is not active!  It processed "
>                            + cstatus.getItemsProcessedCount()
>                            + " items in "
>                            + ((Status)cstatus).getElpasedTimeInSeconds()
>                            + " seconds.");
>                    }
>
>                    /* Get the status of the components */
>                    IStatus [] components = cstatus.getChildrenStatus();
>                    if (components != null && components.length > 0) {
>                        for (int j=0; j < components.length; j++) {
>                            /* For each component, print its status */
>                            IStatus cpstatus = components[j];
>                            if (cpstatus.isActive()) {
>                                System.out.println("  Component "
>                                    + cpstatus.getName()
>                                    + " is active and has processed "
>                                    + cpstatus.getItemsProcessedCount()
>                                    + " items in "
>                                    + ((Status)cpstatus).getElpasedTimeInSeconds()
>                                    + " seconds.");
>                            }
>                            else {
>                                System.out.println("  Component "
>                                    + cpstatus.getName()
>                                    + " is not active and processed "
>                                    + cpstatus.getItemsProcessedCount()
>                                    + " items in "
>                                    + ((Status)cpstatus).getElpasedTimeInSeconds()
>                                    + " seconds.");
>                            }
>                        }
>                    }
>                }
>            }
>        }
>    }
>}
></pre>
>
>
><p>This sample program performs the following operations:</p>
>
><ol>
> <li>Creates an Adapter instance.</li>
> <li>Gives the Adapter instance the adapter configuration file path to execute.</li>
> <li>Gives the Adapter instance a <i>CBEFileOutputter</i> instance to use to
>     capture the GLA log messages.  <b>Note:</b> There is bug in CBEFileOutputter in
>     TPTP 4.0 that causes this program to fail. Comment this portion of the program
>     if you are using TPTP 4.0.  This problem has been fixed in TPTP 4.1.
>     See bugzilla <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=108187">108187</a> for more details.</li>
> <li>Validates the adapter configuration against the schema and validates the content of the
>     configuration.</li>
> <li>Starts the execution of the Adapter instance with the specified adapter configuration on a
>     separate daemon thread.</li>
> <li>Waits 30 seconds and then retrieves the status of the Adapter instance.</li>
> <li>Prints the status of the Adapter instance to <i>System.out PrintStream</i>.</li>
> <li>Stops the execution of the Adapter instance if it is still active.</li>
></ol>
></div>
><br>
><br>
><br>
>
><div id="section_hlight"><A name="4.0">4.0 Packaging GLA with your application</div>
><div id="main_content">
><p>To use GLA in your application you must package the required
>GLA run-time files with your application and make them
>available at the time of execution.  The following GLA files are required:</p>
>
><div id="section_hlight"><A name="4.1">4.1 Packaging the run-time JAR files</div>
><div id="main_content">
>
><p>The following jar files are required to be on the java classpath:</p>
>
><TABLE BORDER="1" WIDTH="75%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>hgla.jar
></TD>
><TD>GLA run-time classes</TD>
></TR>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>hparse.jar
></TD>
><TD>GLA static parser support and example classes</TD>
></TR>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>hlcore.jar
></TD>
><TD>TPTP logging core classes</TD>
></TR>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>hlcbe101.jar
></TD>
><TD>TPTP <i>CommonBaseEvent</i> implementation classes</TD>
></TR>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>hexr.jar
></TD>
><TD>TPTP remote agent execution classes</TD>
></TR>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>emf.common_2.1.0.jar
></TD>
><TD>Eclipse standalone EMF common classes</TD>
></TR>
><TR>
><TD ALIGN="left" VALIGN="top" WIDTH="5%">
>emf.ecore_2.1.0.jar
></TD>
><TD>Eclipse standalone EMF core classes</TD>
></TR>
></TABLE>
>
><p>In addition, any custom GLA component or static parser classes that you have
>created must be on the java classpath in order for
>them to be found by GLA run-time.</p>
>
><div id="section_hlight"><A name="4.2">4.2 Packaging the schema files</div>
><div id="main_content">
>
><p>To perform schema validation on the adapter configuration file, the following GLA
>schema files must be accessible to the GLA run-time. To make them accessible the <b>GLA_HOME</b>
>environment variable must be set to the location of the schema files.</p>
>
><pre>
>   Adapter.xsd
>   ComponentConfiguration.xsd
>   Context.xsd
>   Extractor.xsd
>   Formatter.xsd
>   Outputter.xsd
>   Parser.xsd
>   ProcessUnit.xsd
>   Sensor.xsd
></pre>
>
><div id="section_hlight"><A name="4.3">4.3 Packaging the adapter configuration files</div>
><div id="main_content">
>
><p>The adapter configuration files to be executed by GLA must be accessible.
>These can be packaged with your application as well.</p>
></div>
><br>
><br>
><br>
><div id="section_hlight"><A name="5.0">5.0 Downloading the GLA files</div>
><div id="main_content">
><p>The GLA run-time jar files and schema files can be
>acquired by downloading the
><a href="http://www.eclipse.org/downloads/download.php?file=/tptp/4.0.0/TPTP-4.0.0-200507181519/tptp.gla.runtime-TPTP-4.0.0-200507181519.zip">
>Generic Log Adapter package</a> from the
><a href="http://www.eclipse.org/tptp/home/downloads/downloads.html">TPTP Download page</a></p>
></div>
></div>
><div id="section_divider"></div>
>    <div id="copyright">
>		
>		Copyright &copy; 2005 IBM Corporation and others.
>		All rights reserved.   This document and the accompanying materials
>		are made available under the terms of the Eclipse Public License v1.0
>		which accompanies this distribution, and is available at
>		<a href="http://www.eclipse.org/legal/epl-v10.html">
>		http://www.eclipse.org/legal/epl-v10.html
>		</a> <br/>
>	</div>
></body>
>
></html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
<title>Transforming log and trace data in your application</title>
<link rel="stylesheet" type="text/css" href="http://www.eclipse.org/tptp/eclipse_style.css" >
</head>

<body>
    <div id="page_header">Eclipse Test and Performance Tools Platform Project</div>
<div id="section_header">Transforming log and trace data in your application with Generic Log Adapter</div>
<div class="content">

<p>
<p>October 3, 2005</p>
<p>Author:  Dave Smith  (smith@ca.ibm.com)
<p>
<div id="section_hlight">Table of Contents:</div>
<div id="main_content">
<A href="#1.0">1.0 Introduction</A><br>
<A href="#2.0">2.0 Programming with the GLA API</A><br>
<A href="#3.0">3.0 Coding a simple example</A><br>
<A href="#4.0">4.0 Packaging GLA with your application</A><br>
<A href="#4.1">4.1 Packaging the run-time JAR files</A><br>
<A href="#4.2">4.2 Packaging the schema files</A><br>
<A href="#4.3">4.3 Packaging the adapter configuration files</A><br>
<A href="#5.0">5.0 Downloading the GLA files</A><br>
</div>
<br>
<br>
<br>

<div id="section_hlight"><A name="1.0">1.0 Introduction</div>
<div id="main_content">
<P>Generic Log Adapter (GLA) transforms proprietary log and trace data to the
Common Base Event format. It is a feature of the Eclipse Test and
Performance Tools Platform (TPTP) project.
</P>
<P>GLA parses log files based on regular expression rules or java
parsing classes specified in adapter configuration files. The
configuration files define how to transform log file records into a
standard form that can be used by other tools. Currently, GLA
transforms log file records into standard Common Base Event objects.
However, GLA is extendable to generate any kind of structured
event representation.</P>
<p>GLA is written in the Java programming language and can
easily be embedded in any Java application. The application may be a tool for
examining or processing log files.
For example, in TPTP, Log and Trace Analyzer uses GLA to import log files
so that they can be displayed and correlated in the views of Log and Trace Analyzer.</p>
<p>Another example use of GLA is for an application that generates a log file in a
proprietary format.  The application can make its log file available for an administrator
to monitor with TPTP Log and Trace Analyzer.  Using the Adapter Configuration Editor in the Generic
Log Adapter perspective of TPTP, an adapter configuration file can be created that continuously parses the
proprietary log data into CommonBaseEvent objects and sends them to a logging agent.
The application can create an instance of GLA to run the adapter configuration file in a
separate thread.  An administrator can then attach to the logging agent for the application
using Log and Trace Analyzer and continuously monitor the log of the application in the Log View
of Log and Trace Analyzer.</p>

<p>This document is intended for application developers who want to exploit the GLA technology in their
programs to transform log and trace data to a standard format like Common Base Event.
The programming interface and packaging details required to use GLA in another application are described.
The discussion is based on TPTP 4.0 version of GLA.</p>

<p>This document assumes the reader is familiar with the concepts
of GLA and how to create an adapter configuration file using Adapter Configuration Editor.  For more information on
GLA and how to use the Adapter Configuration Editor, see the video <a href="http://www.eclipse.org/tptp/home/documents/tutorials/gla/GLA_Intro/GLA_Intro.viewlet/GLA_Intro_viewlet_swf.html" TARGET="_blank">
An Introduction to the Generic Log Adapter</a></p>
</div>
<br>
<br>
<br>
<div id="section_hlight"><A name="2.0">2.0 Programming with the GLA API</div>
<div id="main_content">
<p>GLA is implemented in the <i>org.eclipse.hyades.logging.adapter</i> plugin.
To use GLA in an application, the main class <i>org.eclipse.hyades.logging.adapter.Adapter</i>
must be instantiated.  You can use the following Adapter instance methods to configure and run
GLA.</p>


<A NAME="setContextConfigPath(java.lang.String)"><!-- --></A><H3>

setContextConfigPath</H3>

<PRE>

public void <B>setContextConfigPath</B>(java.lang.String&nbsp;configFilePath)</PRE>

<DL>

<DD>Sets the file path of the context configuration portion of the
 adapter configuration. This method must be called before the validate and start
 methods in order for the configuration to be used.  If this method is
 not called, the default file name SimpleContextConfiguration.xml will be used.
 Use the Adapter Configuration Editor to generate the configuration file.
 <p>Typically, the context configuration and component configuration are created in the same file using
 Adapter Configuration Editor.  In this case, call setContextConfigPath and setComponentConfigPath with
 the same file path.

<P>

<DD><DL>

<DT><B>Parameters:</B><DD><CODE>configFilePath</CODE> - The file path of the context configuration</DL>

</DD>

</DL>

<HR>



<A NAME="setComponentConfigPath(java.lang.String)"><!-- --></A><H3>

setComponentConfigPath</H3>

<PRE>

public void <B>setComponentConfigPath</B>(java.lang.String&nbsp;configFilePath)</PRE>

<DL>

<DD>Sets the file path of the component configuration portion of the
 adapter configuration. This method must be called before the validate and start
 methods in order for the configuration to be used.  If this method is
 not called, the default file name SimpleComponentConfigurations.xml will be used.
 Use the Adapter Configuration Editor to generate the configuration file.
 <p>Typically, the context configuration and component configuration are created in the same file using
 Adapter Configuration Editor.  In this case, call setContextConfigPath and setComponentConfigPath with
 the same file path.

<P>

<DD><DL>

<DT><B>Parameters:</B><DD><CODE>configFilePath</CODE> - The file path of the component configuration</DL>

</DD>

</DL>

<HR>



<A NAME="validate()"><!-- --></A><H3>

validate</H3>

<PRE>

public void <B>validate</B>()
              throws <A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></PRE>

<DL>

<DD>Validates the Generic Log Adapter configuration files specified using the setContextConfigPath and setComponentConfigPath
methods.  If you do not specify the context or component configuration file paths, the default configuration files SimpleContextConfiguration.xml
and SimpleComponentConfigurations.xml are validated. It initializes the Adapter instance with the
configuration specified in the configuration files but does not run the Adapter instance.
To run the Adapter use the start method. 

<P>

<DD><DL>


<DT><B>Throws:</B>
<DD><CODE><A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></CODE> - if the configuration is invalid</DL>

</DD>

</DL>

<HR>



<A NAME="start(boolean, boolean)"><!-- --></A><H3>

start</H3>

<PRE>

public void <B>start</B>(boolean&nbsp;separateThread,
                  boolean&nbsp;daemon)
           throws <A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></PRE>

<DL>

<DD>Starts Generic Log Adapter with the configuration files specified using the setContextConfigPath and setComponentConfigPath
methods. If you do not specify the context or component configuration file paths, the Adapter instance uses SimpleContextConfiguration.xml
and SimpleComponentConfigurations.xml as the default configuration files, respectively.  Note, the configuration files are
validated before the Adapter instance uses them.
<p>Generic Log Adapter can be started in a separate thread by specifying true as the first parameter and in addition started as a daemon thread
by specifying true for both parameters.  If true is specified as the first parameter, start will return immediately after starting
the Generic Log Adapter thread.  Otherwise, if the first parameter is false, Generic Log Adapter will be started in the current
thread, regardless of the value of the second parameter, and start will return when Generic Log Adapter has finished executing all
of the contexts configured in the Adapter instance.  Generic Log Adapter runs each context configured in the Adapter instance in
a separate thread.  Therefore, if the Adapter instance is configured with two contexts and start(true, true) is called, three threads will
be started to execute Generic Log Adapter with two contexts.

</P>

<DD><DL>

<DT><B>Parameters:</B>
<DD><CODE>separateThread</CODE> - Run the adapter in a separate thread
<DD><CODE>daemon</CODE> - Run the adapter as a daemon thread.
<DT><B>Throws:</B>
<DD><CODE><A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/AdapterException.html" title="class in org.eclipse.hyades.logging.adapter">AdapterException</A></CODE> - If an error occurs during execution.</DL>

</DD>

</DL>

<HR>



<A NAME="stop()"><!-- --></A><H3>

stop</H3>

<PRE>

public void <B>stop</B>()</PRE>

<DL>

<DD>Stops all of the adapter contexts.  Data still being processed
 by the contexts will be flushed to the last component of each context. The stop method
 waits until all contexts are stopped before stopping the internal Generic Log Adapter
 logging context in order to capture all messages from all contexts.

<P>

<DD><DL>

</DL>

</DD>

</DL>

<HR>



<A NAME="hardStop()"><!-- --></A><H3>

hardStop</H3>

<PRE>

public void <B>hardStop</B>()</PRE>

<DL>

<DD>Stops all of the adapter contexts.  Data still being processed
 by the contexts will be flushed to the last component of each context.
 The hardStop method also disables any context listeners during flushing.
 Context listeners implement the <a href="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/IContextListener.html" title="interface in org.eclipse.hyades.logging.adapter">IContextListener</a> interface and are only
 supported when Generic Log Adapter is running in an Eclipse environment.
 The hardStop method does not wait for all contexts to stop before
 stopping the internal Generic Log Adapter logging context so some messages
 from the other contexts may not be captured.
</DD>

<P>

<DD><DL>

</DL>

</DD>

</DL>

<HR>



<A NAME="main(java.lang.String[])"><!-- --></A><H3>

main</H3>

<PRE>

public static void <B>main</B>(java.lang.String[]&nbsp;args)</PRE>

<DL>

<DD>Adapter main method to run Generic Log Adapter as a standalone application.

<P>

<DD><DL>

<DT><B>Parameters:</B><DD><CODE>args</CODE> - -cc contextConfigurationPath -ac componentConfigurationPath</DL>

</DD>

</DL>

<HR>



<A NAME="getStatus()"><!-- --></A><H3>

getStatus</H3>

<PRE>

public <A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/IStatus.html" title="interface in org.eclipse.hyades.logging.adapter">IStatus</A> <B>getStatus</B>()</PRE>

<DL>

<DD>Gets the status of the adapter instance.

<P>

<DD><DL>


<DT><B>Returns:</B><DD>the org.eclipse.hyades.logging.adapter.IStatus object representing the status.</DL>

</DD>

</DL>

<HR>



<A NAME="setLogOutputter(org.eclipse.hyades.logging.adapter.IOutputter)"><!-- --></A><H3>

setLogOutputter</H3>

<PRE>

public void <B>setLogOutputter</B>(<A HREF="http://download.eclipse.org/tptp/4.0.0/javadoc/Monitoring_Tools/public/org/eclipse/hyades/logging/adapter/IOutputter.html" title="interface in org.eclipse.hyades.logging.adapter">IOutputter</A>&nbsp;outputter)</PRE>

<DL>

<DD>Set the Adapter log outputter for Generic Log Adapter messages.  Generic Log Adapter uses an internal context
 to log trace and error messages during the execution of the Adapter instance.  The outputter specified with
 setLogOutputter is used in the internal logging context.  This method should be
 called before calling validate() and start(), which may log validation and run-time execution messages.
 If this method is not called, GLA will log its messages to the file <i>hgla.log</i> in
 the current directory.

<P>

<DD><DL>

<DT><B>Parameters:</B><DD><CODE>outputter</CODE> - component where GLA will log its messages.</DL>

</DD>

</DL>

<HR>

<p>The methods are typically called in the following order: </p>

<ol>
<li>   <code>setContextConfigPath(adapterConfigFileName)</code>
<li>   <code>setComponentConfigPath(adapterConfigFileName)</code>
<li>   <code>setLogOutputter(glaLogOutputter)</code> - optional
<li>   <code>validate()</code> - optional
<li>   <code>start(separateThread, daemonThread)</code>
</ol>
<p>The following methods are typically called from a different thread than the one that called
start if start is called with <i>separateThread</i>=false.
If start is called with <i>separateThread</i>=true
then these methods can be called from the same thread that called start. </p>

<ul>
<li><code>getStatus()</code> - to get the status of the adapter execution
<li><code>stop()     </code> - to stop the adapter execution
<li><code>hardstop() </code> - to stop the adapter execution
</ul>

<p><b>Note:</b> Missing from this programming interface is
the ability to create or modify adapter configuration files programmatically.
This capability is under consideration for a future release. Please see the TPTP
feature enhancement request <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=96433">96433</a></p>

</div>
<br>
<br>
<br>

<div id="section_hlight"><A name="3.0">3.0 Coding a simple example</div>
<div id="main_content">
<p>The following example shows a simple main program to run the
adapter configuration file <i>c:\test.adapter</i>.</p>

<pre>
import org.eclipse.hyades.logging.adapter.Adapter;
import org.eclipse.hyades.logging.adapter.AdapterException;
import org.eclipse.hyades.logging.adapter.IStatus;
import org.eclipse.hyades.logging.adapter.impl.Status;
import org.eclipse.hyades.logging.adapter.outputters.CBEFileOutputter;

public class RunAdapter {

    /**
     * This is a simple program to run the Generic Log Adapter
     * with a hardcoded adapter configuration file.
     */
    public static void main(String[] args) {

        String adapterConfigFile = "c:\\test.adapter";

        /* Create an Adapter instance */
        Adapter adapter = new Adapter();

        /* Set the adapter configuration file */
        adapter.setContextConfigPath(adapterConfigFile);
        adapter.setComponentConfigPath(adapterConfigFile);

        /* Create a file outputter to capture GLA
         * log messages.
         * WARNING:  The following code does not work
         * in TPTP 4.0 due to bugzilla 108187 in
         * CBEFileOutputter.  Please comment the
         * following three lines of code if using
         * TPTP 4.0.
         */
        CBEFileOutputter fo = new CBEFileOutputter();
        fo.setDirectory("c:\\logs");
        fo.setFileName("testgla.log");

        /* Set the outputter to capture the GLA log messages */
        adapter.setLogOutputter(fo);

        /* Validate the adapter configuration file */
        try {
            adapter.validate();
        }
        catch (AdapterException e) {
            System.err.println("Adapter configuration file is invalid.");
            System.err.println(e.getMessage());
            return;
        }

        System.out.println("Adapter configuration was validated.");

        /* Start the adapter as a separate thread */
        try {
            adapter.start(true, true);
        }
        catch (AdapterException e) {
            /* If we get an exception at this point we likely do
             * not have a valid configuration and hence the log file
             * is likely not flushed.  We need to write this to stderr.
             */
            System.err.println("GLA Exception occurred");
            System.err.println(e.getMessage());
            adapter.stop();
            return;
        }

        System.out.println("Adapter was started.");

        /* Wait 30 seconds */
        try {
            Thread.sleep(30000);
        }
        catch (InterruptedException e) {
        	
        }

        /* Get the adapter status */
        IStatus status = adapter.getStatus();

        if (status != null) {
            /* print the current adapter status out */
            printAdapterStatus(status);
        }

        /* If the adapter is still running then stop it */
        if (status != null && status.isActive()) {
            adapter.stop();
            System.out.println("Adapter was stopped.");
        }
    }

    /**
     * Print the adapter status.
     *
     * @param status Adapter IStatus object
     */
    private static void printAdapterStatus(IStatus status) {
        /* print the current adapter status out */
        if (status.isActive()) {
            System.out.println("Adapter is active!  It has processed "
                + status.getItemsProcessedCount() + " items in "
                + ((Status)status).getElpasedTimeInSeconds()
                + " seconds.");
        }
        else {
            System.out.println("Adapter is not active!  It processed "
                + status.getItemsProcessedCount() + " items in "
                + ((Status)status).getElpasedTimeInSeconds()
                + " seconds.");
        }
    	
        /* Get the status of the contexts */
        IStatus [] contexts = status.getChildrenStatus();

        if (contexts != null && contexts.length > 0) {
            for (int i=0; i < contexts.length; i++) {
                /* For each context, print its status */
                if (contexts[i] != null) {
                    IStatus cstatus = contexts[i];
                    if (cstatus.isActive()) {
                        System.out.println("Context " + cstatus.getName()
                            + " is active!  It has processed "
                            + cstatus.getItemsProcessedCount()
                            + " items in "
                            + ((Status)cstatus).getElpasedTimeInSeconds()
                            + " seconds.");
                    }
                    else {
                        System.out.println("Context " + cstatus.getName()
                            + " is not active!  It processed "
                            + cstatus.getItemsProcessedCount()
                            + " items in "
                            + ((Status)cstatus).getElpasedTimeInSeconds()
                            + " seconds.");
                    }

                    /* Get the status of the components */
                    IStatus [] components = cstatus.getChildrenStatus();
                    if (components != null && components.length > 0) {
                        for (int j=0; j < components.length; j++) {
                            /* For each component, print its status */
                            IStatus cpstatus = components[j];
                            if (cpstatus.isActive()) {
                                System.out.println("  Component "
                                    + cpstatus.getName()
                                    + " is active and has processed "
                                    + cpstatus.getItemsProcessedCount()
                                    + " items in "
                                    + ((Status)cpstatus).getElpasedTimeInSeconds()
                                    + " seconds.");
                            }
                            else {
                                System.out.println("  Component "
                                    + cpstatus.getName()
                                    + " is not active and processed "
                                    + cpstatus.getItemsProcessedCount()
                                    + " items in "
                                    + ((Status)cpstatus).getElpasedTimeInSeconds()
                                    + " seconds.");
                            }
                        }
                    }
                }
            }
        }
    }
}
</pre>


<p>This sample program performs the following operations:</p>

<ol>
 <li>Creates an Adapter instance.</li>
 <li>Gives the Adapter instance the adapter configuration file path to execute.</li>
 <li>Gives the Adapter instance a <i>CBEFileOutputter</i> instance to use to
     capture the GLA log messages.  <b>Note:</b> There is bug in CBEFileOutputter in
     TPTP 4.0 that causes this program to fail. Comment this portion of the program
     if you are using TPTP 4.0.  This problem has been fixed in TPTP 4.1.
     See bugzilla <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=108187">108187</a> for more details.</li>
 <li>Validates the adapter configuration against the schema and validates the content of the
     configuration.</li>
 <li>Starts the execution of the Adapter instance with the specified adapter configuration on a
     separate daemon thread.</li>
 <li>Waits 30 seconds and then retrieves the status of the Adapter instance.</li>
 <li>Prints the status of the Adapter instance to <i>System.out PrintStream</i>.</li>
 <li>Stops the execution of the Adapter instance if it is still active.</li>
</ol>
</div>
<br>
<br>
<br>

<div id="section_hlight"><A name="4.0">4.0 Packaging GLA with your application</div>
<div id="main_content">
<p>To use GLA in your application you must package the required
GLA run-time files with your application and make them
available at the time of execution.  The following GLA files are required:</p>

<div id="section_hlight"><A name="4.1">4.1 Packaging the run-time JAR files</div>
<div id="main_content">

<p>The following jar files are required to be on the java classpath:</p>

<TABLE BORDER="1" WIDTH="75%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">

<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
hgla.jar
</TD>
<TD>GLA run-time classes</TD>
</TR>
<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
hparse.jar
</TD>
<TD>GLA static parser support and example classes</TD>
</TR>
<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
hlcore.jar
</TD>
<TD>TPTP logging core classes</TD>
</TR>
<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
hlcbe101.jar
</TD>
<TD>TPTP <i>CommonBaseEvent</i> implementation classes</TD>
</TR>
<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
hexr.jar
</TD>
<TD>TPTP remote agent execution classes</TD>
</TR>
<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
emf.common_2.1.0.jar
</TD>
<TD>Eclipse standalone EMF common classes</TD>
</TR>
<TR>
<TD ALIGN="left" VALIGN="top" WIDTH="5%">
emf.ecore_2.1.0.jar
</TD>
<TD>Eclipse standalone EMF core classes</TD>
</TR>
</TABLE>

<p>In addition, any custom GLA component or static parser classes that you have
created must be on the java classpath in order for
them to be found by GLA run-time.</p>

<div id="section_hlight"><A name="4.2">4.2 Packaging the schema files</div>
<div id="main_content">

<p>To perform schema validation on the adapter configuration file, the following GLA
schema files must be accessible to the GLA run-time. To make them accessible the <b>GLA_HOME</b>
environment variable must be set to the location of the schema files.</p>

<pre>
   Adapter.xsd
   ComponentConfiguration.xsd
   Context.xsd
   Extractor.xsd
   Formatter.xsd
   Outputter.xsd
   Parser.xsd
   ProcessUnit.xsd
   Sensor.xsd
</pre>

<div id="section_hlight"><A name="4.3">4.3 Packaging the adapter configuration files</div>
<div id="main_content">

<p>The adapter configuration files to be executed by GLA must be accessible.
These can be packaged with your application as well.</p>
</div>
<br>
<br>
<br>
<div id="section_hlight"><A name="5.0">5.0 Downloading the GLA files</div>
<div id="main_content">
<p>The GLA run-time jar files and schema files can be
acquired by downloading the
<a href="http://www.eclipse.org/downloads/download.php?file=/tptp/4.0.0/TPTP-4.0.0-200507181519/tptp.gla.runtime-TPTP-4.0.0-200507181519.zip">
Generic Log Adapter package</a> from the
<a href="http://www.eclipse.org/tptp/home/downloads/downloads.html">TPTP Download page</a></p>
</div>
</div>
<div id="section_divider"></div>
    <div id="copyright">
		<!--
			Change "IBM Corporation" to the name of the company who was the
			primary author as appropriate. If more than one company contributed
			to the documentation, list all of the company names.
		-->
		Copyright &copy; 2005 IBM Corporation and others.
		All rights reserved.   This document and the accompanying materials
		are made available under the terms of the Eclipse Public License v1.0
		which accompanies this distribution, and is available at
		<a href="http://www.eclipse.org/legal/epl-v10.html">
		http://www.eclipse.org/legal/epl-v10.html
		</a> <br/>
	</div>
</body>

</html>

Actions: View

Attachments on bug 79114: 27760