Getting started with the Hyades Data Collection Engine - Linux on IA32

This guide contains the following information:

• Prerequisites
• Configuring and starting the Hyades Data Collection Engine
• Server logging
• Invoking the Java Profilier

Prerequisites

• RAServer requires the directories of the JRE that contain executable libraries such as libjvm.so to be added to the LD_LIBRARY_PATH environment variable. For example, if you are using the IBM JRE 1.4.1, the LD_LIBRARY_PATH variable would be set as follows:

  export LD_LIBRARY_PATH=/opt/IBMJava2-141/jre/bin/classic:/opt/IBMJava2-141/jre/bin:$LD_LIBRARY_PATH

• The Hyades Data Collection Engine is compiled using libstdc++-libc6.2-2.so.3 shared library. Ensure that this shared library exists under the /usr/lib directory. If it does not exist, you have to install the RPM package compat-libstdc++ that comes with the operating system installation media.
• Install the Hyades Data Collection Engine

Configuring and starting the Hyades Data Collection Engine

1. Add the <unzip directory>/lib directory to the system's LD_LIBRARY_PATH environment variable.
2. Add the <unzip directory>/bin directory to the system's PATH environment variable.
3. Set the RASERVER_HOME environment variable to point to <unzip directory>. The server will use this environment variable to locate the configuration file.
4. Ensure that the files in the <unzip directory>/bin and <unzip directory>/lib directory are executable.
5. Generate the configuration file that provides the rules for which applications that can be executed with the server. This can be accomplished by running the <unzip directory>/bin/SetConfig.sh script. Run this script from a command shell in the <unzip directory>/bin directory. This step will require that a Java Virtual Machine (JVM) be present in the system's PATH. Follow the prompts and the output will be the <unzip directory>/config/serviceconfig.xml file. This is a sample of the configuration file that will be used by the server when it is started. You may edit this file manually using the rules as outlined in the document Hyades Data Collection Engine configuration files. To load any changes, restart the server.
6. Ensure that the <unzip directory>/bin/RAServer file is executable.
7. Start the server by running <unzip directory>/bin/RAServer.
8. Stop the server by terminating the RAServer process. For example:

      kill -s INT <RAServer PID>
      

   NOTE: This step may require root authority. NOTE: On some Linux installations, each thread within a process has a unique PID. Terminate the lowest PID to terminate all PID(s).

Server Logging

The Java Profiler

The Java Profiler is a library that attaches to a JVM to capture and record the Java application's behavior. The output from the profiling agent is in the form of XML fragments.

Documentation on the composition of these XML fragments is located at:
http://dev.eclipse.org/viewcvs/indextools.cgi/~checkout~/hyades-home/docs/components/data_collection/docs/XML4Profiling.htm

Invocation of the Java Profiler from the Hyades Workbench

The Java Profiler can be launched from the Hyades workbench. Open the Profiling Perspective and you can launch applications using the 'Profile' menu contribution or the toolbar button. Applications can be run either using code within the current Hyades workbench's workspace or binaries that are on the file system.

Invocation of the Java Profiler from the Command Line

The Java Profiler is invoked using the -Xrun JVM option as follows:

    -XrunpiAgent[:agent_parm[,agent_parm]*

• server=[standalone | enabled | controlled]

  standalone

  The Java Profiler is manually attached to a JVM instance and generates a stand-alone trace to a specified file based on the options and filters given on the command line. When this option is selected, the Java Profiler produces the enclosing traceRoot element to form a complete and valid XML document.

  enabled

  The Java Profiler is loaded, allows the application to run normally, but produces no trace until a Hyades workbench attaches to the agent to give it instructions. When this option is selected, the Java Profiler only produces XML fragments instead of a complete XML document.

  controlled

  The Java Profiler is loaded, blocks the application from running until a client gives it instructions to continue. When this option is selected, the Java Profiler only produces XML fragments instead of a complete XML document.

• filters=filename
  NOTE: This parameter is only used when server=standalone is specified.
  Specifies the name of the file that contains the initial class filter definitions to be used during the trace. The default is filters.txt in the current directory. The format of the file is as follows:

          classpattern methodpattern mode , where:
  

  classpattern

  is a string with no imbedded blanks. The string may contain a single "*" either at the beginning of the string or at the end of the string. The "*" will match zero or more characters, thus making the pattern a generic prefix or suffix pattern. A single "*" can also be specified to represent all strings.

  methodpattern

  is a string with no imbedded blanks. The string may contain a single "*" either at the beginning of the string or at the end of the string. The "*" will match zero or more characters, thus making the pattern a generic prefix or suffix pattern. A single "*" can also be specified to represent all strings.

  mode

  is one of INCLUDE or EXCLUDE.

  Filter patterns are processed in the order that they are specified until the first pattern match succeeds. If the class name does not match any of the specified filter patterns, the default is to INCLUDE the class.

• file=filename
  NOTE: This parameter is only used when server=standalone is specified.
  Specifies the name of a file where the trace will be written. The default is trace.xml in the current directory.
• help
  Displays a list of available agent options to standard out.