Configuring an adapter for live application monitoring

The Generic Log Adapter provides an Outputter class that allows the Common Base Event objects generated by your adapter to be sent to a Logging Agent. The Log and Trace Analyzer can be used to attach to the Logging Agent, to monitor and to analyze the application log in real time.

Prerequisites:

Please follow these steps to configure your adapter for monitoring.

Configure the Outputter component

Note: When a new adapter configuration file is created, it is configured to use the CBELogOutputter class by default. If you have not changed this setting, you can skip this procedure.

The Outputter component in the adapter configuration file needs to be updated to use the CBELogOutputter class which writes the Common Base Event objects to a Logging Agent. You can either update the existing Outputter component or add a new Outputter component.

To add a new Outputter component:

  1. To edit the adapter configuration file, select the adapter configuration file in the Navigator pane. Right-click and select Open with > Adapter Configuration Editor. The file is opened in the editor.
  2. In the Adapter Configuration Editor window, expand the Adapter > Configuration > Context Instance node.
  3. Right-click on the Context Instance and select Add > Outputter. A new Outputter is created in the Context Instance.
  4. In the Outputter Type field, select LoggingAgentOutputter.
  5. Click on the agentName property. The property details are shown in the right pane.
  6. Update the property value with the desired Logging Agent name. This is the name that you will see in the Log and Trace Analyzer as the Logging Agent to monitor.
  7. If you want the Outputter to wait before writing the Common Base Events to the Logging Agent, add a property called waitUntilLoggingTime and set the value of the property to the time in milliseconds. To add the property, right-click on the newly created Outputter and select Add > Property. A new property is created under the new Outputter node.
  8. To enable the CBELogOutputter class, you need to create the associated Outputter component in the Contexts Basic Context Implementation. Open Contexts > Context Basic Implementation Context.
  9. Right-click on Context Basic Implementation Context and select Add > Component. A new component is added to the context.
  10. Configure the new component with the following values:
    Name: The name of the Outputter in the context. For example, Logging Agent Outputter
    Description: Description of what this Outputter does
    Executable class: org.eclipse.hyades.logging.adapter.outputters.CBELogOutputter
    Logging level:The level of internal logging the Outputter component should use. This level is based on CommonBaseEvent severity values. The higher the number, the higher the severity of the message. For the Logging level, the number specified will cause only internal Outputter messages of that severity and above to be logged by the Outputter component. A value of 71 or above means the Outputter will not log any internal Outputter messages. A value of 0 means the Outputter will log internal Outputter messages of all severities. The recommended value is 50 which means that only Critical or Fatal internal Outputter errors messages are logged.
    Role: Outputter
    UniqueID: Must point to the Outputter defined in the Context Instance in step 3. Use the Browse button to select the correct ID.
  11. Save the adapter configuration file changes.

Configure the context instance

If you want the log parser to monitor the log file continuously, you need to update the context instance properties of the adapter configuration file for continuous operation.

  1. To edit the adapter configuration file, select the adapter configuration file in the Navigator perspective. Right-click and select Open with > Adapter Configuration Editor. The file is opened in the editor.
  2. In the editor window, select Adapter > Configuration > Context Instance . The Context Instance details are displayed in the right pane.
  3. Select the Continuous Operation check box.
  4. Configure the Maximum Idle Time and Pause Interval fields as required.
  5. Save the adapter configuration file changes.

Launch a Java process to run the adapter

The log adapter you created can be run externally from a batch file in the Windows environment or a shell script in non-Windows environments. Below are sample files that can be used to launch the Java process that will run your log adapter.
Note: To attach and monitor the logging agent created by the Generic Log Adapter, the Agent Controller must be installed on the system where the Generic Log Adapter is to run and it must be started before the Generic Log Adapter is started.

Windows batch file:

@rem USAGE:  runregex
@rem PURPOSE:  Illustrates the functional capabilities of the Generic Log Adapter (GLA) run-time using an example adapter file and sample log file.
@rem INSTRUCTIONS:  When executing in a GLA run-time environment, change the value of the %GLA_HOME% environment variable to the absolute path of the unzipped GLA run-time.
@rem NOTE:  When executing in a plug-in (e.g. Eclipse) run-time environment, create a temporary working directory and change the value of the %GLA_HOME% environment variable to the 
@rem        absolute path of the new temporary working directory.  Furthermore, create a %GLA_HOME%\config directory and copy the contents of the org.eclipse.hyades.logging.adapter.config 
@rem        plug-in to the new %GLA_HOME%\config directory.  Finally, create a %GLA_HOME%\lib directory and copy the following JAR files to the new %GLA_HOME%\lib directory:
@rem                    Plug-in                 |     JAR
@rem        ---------------------------------------------------
@rem        org.eclipse.hyades.logging.adapter  |  hgla.jar
@rem        org.eclipse.hyades.logging.core     |  hlcbe101.jar
@rem        org.eclipse.hyades.logging.core     |  hlcore.jar
@rem        org.eclipse.hyades.execution.remote |  hexr.jar
@rem        org.eclipse.emf.ecore               |  ecore.jar
@rem        org.eclipse.emf.common              |  common.jar

SET GLA_HOME=d:\GenericLogAdapter
SET MY_DIRECTORY=MyAdapter
SET CONFIG_FILE=%GLA_HOME%\config\%MY_DIRECTORY%\myadapter.adapter
PUSHD %GLA_HOME%\config\%MY_DIRECTORY%\java -DGLA_HOME="%GLA_HOME%" -classpath "%GLA_HOME%\lib\hgla.jar;%GLA_HOME%\lib\hexr.jar;%GLA_HOME%\lib\hlcbe101.jar;%GLA_HOME%\lib\ecore.jar;%GLA_HOME%\lib\common.jar;%GLA_HOME%\lib\hlcore.jar" org.eclipse.hyades.logging.adapter.Adapter -ac "%CONFIG_FILE%" -cc "%CONFIG_FILE%"
POPD

non-Windows batch file:
#!/bin/sh
# USAGE:  runregex_example.sh
# PURPOSE: Illustrates the functional capabilities of the Generic Log Adapter (GLA) run-time using an example adapter file and sample log file.
# INSTRUCTIONS: When executing in a GLA run-time environment, change the value of the $GLA_HOME environment variable to the absolute path of the unzipped GLA run-time.
# NOTE: When executing in a plug-in (e.g. Eclipse) run-time environment, create a temporary working directory and change the value of the $GLA_HOME environment variable to the 
# absolute path of the new temporary working directory. Furthermore, create a $GLA_HOME/config directory and copy the contents of the com.ibm.etools.logging.adapter.config 
# plug-in to the new $GLA_HOME/config directory. Finally, create a $GLA_HOME/lib directory and copy the following JAR files to the new $GLA_HOME/lib directory:
# Plug-in | JAR
# ---------------------------------------------------
# org.eclipse.hyades.logging.adapter | hgla.jar
# org.eclipse.hyades.logging.core | hlcbe101.jar
# org.eclipse.hyades.logging.core | hlcore.jar
# org.eclipse.hyades.execution.remote | hexr.jar
# org.eclipse.emf.ecore | ecore.jar
# org.eclipse.emf.common | common.jar

GLA_HOME=/home/eclipse/GenericLogAdapter
export GLA_HOME

YOUR_DIRECTORY=MY_DIRECTORY
export MY_DIRECTORY

CONFIG_FILE="$GLA_HOME/config/$MY_DIRECTORY/myadapter.adapter"
export CONFIG_FILE

CUR_DIR=`pwd`
export CUR_DIR

cd "$GLA_HOME/config/$MY_DIRECTORY

java -DGLA_HOME="$GLA_HOME" -classpath "$GLA_HOME/lib/hgla.jar:$GLA_HOME/lib/hexr.jar:$GLA_HOME/lib/hlcbe101.jar:$GLA_HOME/lib/ecore.jar:$GLA_HOME/lib/common.jar:$GLA_HOME/lib/hlcore.jar"org.eclipse.hyades.logging.adapter.Adapter -ac "$CONFIG_FILE" -cc "$CONFIG_FILE"

cd "$CUR_DIR"
Configure the file as required to launch the Java process that will run your adapter.

Monitoring the live application log

You are now ready to monitor the live application log.

  1. Ensure that logging is enabled in the preferences.
    1. From the main toolbar, select Window > Preferences . The Preferences wizard opens.
    2. Select Profiling and Logging from the left pane. The Profiling and Logging preferences are loaded in the right pane.
    3. Select Enable logging under Profiling and Logging options.

      Enable logging check box is selected in the preferences pane for Profiling and Logging

    4. Select OK to apply the changes.
  2. In the Profiling and Logging perspective, click Profiling Icon of profiling tool the toolbar and select Profile. The Profile wizard opens.
  3. Select Attach - Java Process and click the New button at the bottom of the list. A new Java process configuration is created.
  4. Click the Hosts tab and select the host on which the application log resides by moving it to the Selected agents pane using the arrow button.
    Note: To monitor a live application log, the Agent Controller must be running on the same system as the application.
  5. Click the Agents tab and use the arrow keys to select the Logging Agent that you configured.

    In the profiling preferences wizard, the logging agent the user created is on the left pane

  6. Click Apply.
  7. Click Profile to attach to the Logging Agent.
  8. In the Profiling Monitor view of the Profiling and Logging perspective, select the Logging Agent..
  9. Right-click on the Logging Agent and select Start monitoring.
  10. Right-click on the Logging Agent and select Open with > Log View. The log events from the application log are loaded into the Log view.

 

Related Concepts
Overview of the Hyades Generic Log Adapter
Common Base Event format specification

Related tasks
Creating a log parser

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