# Getting Started with Agent Controller - AIX

### Contents

Overview

Prerequisites

Notation

Installing Agent Controller

Setting Up Agent Controller

Configuring Agent Controller

Starting Agent Controller

Stopping Agent Controller

Querying Agent Controller version information

Checking Agent Controller Installation

Server Logging

Profiling a Java Application

Invocation of the Java Profiler from the Eclipse Workbench

Invocation of the Java Profiler from the Command Line

Using the Java Profiler with Java 1.5 (or higher) Virtual Machines

Using LIBPATH setting and the -`agentlib` Java option to invoke the Java Profiling Agent

Format of the Class Filter File

Controlling the Java Profiling Agent

Notes about the Java Profiler

Uninstalling Agent Controller

## Overview

This document explains the installation and configuration steps required to use the standalone Agent Controller. To profile a Java application on a remote machine or run a TPTP test on a remote machine, you must first install a standalone Agent Controller on that remote machine. To profile a Java application locally or run a TPTP test locally, you have the option of installing a standalone Agent Controller on the local machine or using the Integrated Agent Controller. If using the Integrated Agent Controller, there is no need to install and configure the standalone Agent Controller when using the Profiling and Logging perspective and Test perspective locally.

## Prerequisites

- Install the Java runtime (JRE) or Java development kit (JDK) 1.5 or higher.
- Remove or uninstall all prior versions of Agent Controller.
- Bash (/bin/bash) is required for the launch and configuration shells scripts.

### Notation

<`install-dir`> = The absolute directory path where the Agent Controller has been unzipped. For example: `/opt/tptpAC`

### Installing Agent Controller

Download one of the AIX Agent Controller Runtime packages from the TPTP Download page. Install it by simply creating a directory and unzipping the package contents into that directory.

## Setting Up Agent Controller

After a normal installation, you still need to configure the Agent Controller before you can start it.

### Configuring Agent Controller

1. Ensure that the files in the `<install-dir>/bin` and `<install-dir>/lib` directory are executable.
2. Run `SetConfig.sh` script from a command shell in the `<install-dir>/bin` directory to generate the configuration file for the Agent Controller. The script requires that a Java Virtual Machine (JVM) be present in the PATH environment variable. Follow the prompts and enter the required parameters as appropriate. The configuration file `<install-dir>/config/serviceconfig.xml` will be generated based on your inputs.
3. Add `<install-dir>/bin` directory to the LIBPATH environment variable.
4. Add `<install-dir>/lib` directory to the LIBPATH environment variable.

If you want to make changes to the configuration file that was generated in step 1, you may run the `SetConfig.sh` script again or you may manually edit the file according to the rules outlined in the document Agent and Agent Controller Configuration Overview. The Agent Controller must be restarted for the changes to take effect.

If Agent Controller is installed by a root user, then non-root user would not be able to run the SetConfig.sh unless file permissions are set correctly. Here is a sample script to do this:

#!/bin/sh
chmod a+rwx org.eclipse.hyades.execution*/config
chmod a+rw org.eclipse.hyades.execution*/config/*
chmod a+rwx org.eclipse.hyades.logging.core*/config
chmod a+rw org.eclipse.hyades.logging.core*/config/*
chmod a+rwx org.eclipse.hyades.test.core*/config
chmod a+rw org.eclipse.hyades.test.core*/config/*
chmod a+rwx org.eclipse.hyades.test.tools.core*/config
chmod a+rw org.eclipse.hyades.test.tools.core*/config/*
chmod a+rwx org.eclipse.tptp.monitoring.instrumentation*/config
chmod a+rw org.eclipse.tptp.monitoring.instrumentation*/config/*
chmod a+rwx org.eclipse.tptp.platform.collection.framework*/config
chmod a+rw org.eclipse.tptp.platform.collection.framework*/config/*
chmod a+rwx org.eclipse.tptp.platform.logging.events*/config
chmod a+rw org.eclipse.tptp.platform.logging.events*/config/*
chmod a+rwx org.eclipse.tptp.test.tools.junit.plugin*/config
chmod a+rw org.eclipse.tptp.test.tools.junit.plugin*/config/*
chmod a+rwx org.eclipse.tptp.trace.arm*/config
chmod a+rw org.eclipse.tptp.trace.arm*/config/*
chmod a+rwx org.mx4j.jmx*/config
chmod a+rw org.mx4j.jmx*/config/*
chmod a+rwx org.opengroup.arm*/config
chmod a+rw org.opengroup.arm*/config/*
chmod a+rwx org.eclipse.hyades.probekit*/config/
chmod a+rw org.eclipse.hyades.probekit*/config/*
chmod a+rwx org.eclipse.tptp.platform.jvmti.runtime*/config
chmod a+rw org.eclipse.tptp.platform.jvmti.runtime*/config/*

### Starting Agent Controller

Start the Agent Controller by changing your working directory to `<install-dir>/bin` and running `ACStart.sh`.

Note: The Agent Controller may also be started using `RAStart.sh`, in support of backward compatibility.

### Stopping Agent Controller

Stop the Agent Controller by changing your working directory to `<install-dir>/bin` and running `ACStop.sh`.

Note: The Agent Controller may also be stopped using `RAStop.sh`, in support of backward compatibility.

## Querying Agent Controller Version Information

To display the version of Agent Controller, change your working directory to <install-dir>/bin in a command shell and run the following command:

> `ACServer -v`
> or
> `ACServer -version`

The Agent Controller will display its version and terminate.

Note: The Agent Controller version may also be queried using `RAServer`, in support of backward compatibility.

## Checking Agent Controller Installation

If desired, you can verify proper operation of your Agent Controller installation by executing the SampleClient application provided with the runtime package.

Perform the following steps:

1. Start the Agent Controller.
2. Open a command prompt window
3. Go to the `<install-dir>/bin` directory
4. Enter the following at the command prompt:
   `SampleClient`
5. Observe the console output for SampleClient. It should be similar to the following example:

> `------------------- SampleClient Console Output --------------------------------
> Connected to the Agent Controller on "localhost" at port number #####
> The Time Collector Agent ID: ###
> Established a data channel with the agent.
> Sending 5 Hello messages over data channel to TimeCollector ...
> Start the TimeCollector ...
> Incoming data: Hello from Time Collector Agent - Count 0
> Incoming data: Hello from Time Collector Agent - Count 1
> Incoming data: Hello from Time Collector Agent - Count 2
> Incoming data: Hello from Time Collector Agent - Count 3
> Incoming data: Hello from Time Collector Agent - Count 4
> Stop the TimeCollector ...
> Incoming data: Hello from Time Collector Agent - Count 5
> Incoming data: Hello from Time Collector Agent - Count 6
> Incoming data: Hello from Time Collector Agent - Count 7
> Incoming data: Hello from Time Collector Agent - Count 8
> Incoming data: Hello from Time Collector Agent - Count 9
> Incoming data: Hello from Time Collector Agent - Count 10
> All finished
> Press any key to exit...`

Note: The above port number and Agent ID values will typically be 10006 and 103 respectively, depending on Agent Controller configuration settings and the number of times that the SampleClient application runs.

Refer to the Agent Controller build `readme.txt` file for detailed information on the SampleClient functionality.

## Server Logging

All server log entries will be placed in `<install-dir>/config/servicelog.log` .

## Profiling a Java Application

You can profile an application by invoking the Java Profiling Agent, which is a library that attaches to a Java Virtual Machine (JVM) to capture and record the behavior of your Java application. The output from the agent is in the form of XML fragments. The format of this fragment is described in the document titled "Event Specification for the Java Profiler".

You can invoke the Java Profiling Agent from the Eclipse workbench or in standalone mode from the command line.

### Invocation of the Java Profiler from the Eclipse Workbench

From the Eclipse workbench, you can launch and profile applications in the current Eclipse workbench's workspace or external Java applications located in the file system. To invoke the Java Profiler from the Eclipse workbench, you must have the Test and Performance Tools Platform installed. To profile a Java application locally, you can use the Integrated Agent Controller or a local installation of the Agent Controller. To profile a remote Java application, you must also have the Agent Controller installed on the machine where the application to be profiled resides.

To launch the Java Profile, from the Profiling and Logging Perspective of the Eclipse workbench use the Run > Open Profile Dialog... menu or the Profile toolbar button. The Profile wizard will open. Simply follow the wizard to profile an application. When using the profiling functionality, both IPv4 and IPv6 agent controller connections are supported.

### Invocation of the Java Profiler from the Command Line

To launch the Java profiler from the command line, you do not need to have the Test and Performance Tools Platform installed but you do need to have the Agent Controller installed on the machine where the application to be profiled resides.

** Note: Before starting the command line invocation, make sure that the profiling agent libraries are setup in the system LIBPATH variable. Read thru the following section for instruction on environment variable setup.

### How do I setup the environment variables?

Before starting the Java process, please make sure `$JAVA_HOME/bin` has been added into `PATH` and then setup the following variables in the same session:

- `export TPTP_AC_HOME=<<Agent Controller Home>>`
- `export JAVA_PROFILER_HOME=$TPTP_AC_HOME/plugins/org.eclipse.tptp.javaprofiler`
- `export LIBPATH=$JAVA_PROFILER_HOME:$TPTP_AC_HOME/lib:$LIBPATH`

  ### Using the Java Profiler with Java 1.5 (or higher) Virtual Machines

  #### Using LIBPATH setting and the -`agentlib` Java option to invoke the Java Profiling Agent

  -agentlib:JPIBootLoader=JPIAgent[:[help]|[<option>=<value>,...]];<profiler>[:<option>=<value>,...]

  The command line is structured as follows:

  JPIBootLoader is the library that loads the profiling agent.
  JPIAgent is the Java 5.0+ profiling agent. By augmenting the JPIAgent part of the command line with additional options, you can control the behavior of the profiling agent. The following options are supported:
  - server=[standalone | enabled | controlled]
    standalone
      The profiling agent runs in a headless mode, which means it is not possible to interact with it from the workbench. Configuration information is provided as part of the command lineand profiling data is stored in a file directly by the profiling agent. The profiling file can then be imported into the workbench at a later date.
      The Java Profiling Agent is manually attached to a JVM instance and generates profiling data to an output file. The default output file is called trace.trcxml, but you can specify a different file name using the file= filename parameter. When this option is selected, the Java Profiling Agent produces an enclosing traceRoot element to form a complete and valid XML document.
    enabled (This is the default.)
      The profiling agent runs in the background of the JVM without consuming resources until it is connected to by the workbench and asked to start monitoring. Data is then streamed over the agent's data channel and consumed by the workbench. This mode allows the application to run normally, but produces no profiling data until a client attaches to the agent to give it instructions. When this option is selected, the Java Profiling Agent produces only XML fragments instead of a complete XML document.
    controlled
      The profiling agent preempts the JVM from initialization (the agent is loaded but it blocks the application from running) until it is attached to from the workbench and given instructions to start monitoring by a client. That is, when the profiling agent is launched in controlled mode, it will appear to hang the JVM until asked to start monitoring and it will produce only XML fragments instead of a complete XML document.
  - filters=filename
    Used only when `server=standalone` is specified.
    Specifies the name of the file that contains the initial class filter definitions to be used during the profiling session. The default file name is filters.txt in the current directory. See below for information about the file format.
  - file=filename
    Used only when `server=standalone` is specified.
    Specifies the name of a file that the profiling data will be written to. The default is trace.trcxml in the current directory.
  - help
    Displays a list of available agent options to STDOUT.
  <Profiler> is the name of the Profiler Library to load. Some of the available profilers support additional profiler-specific options, as described below:
  - CGProf
    Execution time analysis. Supports the following options:

    execdetails=[true | false] : whether to collect execution flow/call-graph information (`true`) or not (`false`). Default is `false`.

  - HeapProf
    Object allocation/heap analysis. Supports the following options:

    allocsites=[true | false] : whether to collect object allocation site information (`true`) or not (`false`). Default is `false`.

  - ThreadProf
    Thread analysis. Supports the following options:

    contanalysis=[true | false] : whether to collect lock usage information for thread contention analysis (`true`) or not (`false`). Default is `false`.

    maxstackdepth=number of frames : Limit the size of the stack trace reported by the profiler.

  To run the Java Profiling Agent on AIX with -agentlib option, perform the LIBPATH setting steps mentioned before, then execute the Java application with the `-agentlib` parameter as described above.

  Note: Ensure you surround the entire -agentlib argument with single quotes. Otherwise, the Linux shell may interpret the semicolon (;) preceding the profiler name as a command terminator and the Java application will not be executed.

  ##### Examples

  1. To profile the "HelloWorld" Java application with the CPU Profiler in standalone mode and write the results into log.trcxml:

         java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld

  2. To profile the "HelloWorld" Java application with the Heap Profiler in standalone mode, use the filters defined in myFilter.txt, and collect information about the source locations where objects are allocated:

         java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true' HelloWorld

  ### Format of the Class Filter file

  The filter file should specify three fields, package/class, method, and mode in the following format:
  `package/class method mode`
  where:

  > package/class
  >   This field is used to specify a pattern for a package or a class name. The pattern should be specified as a string with no embedded blanks. The string may contain a single asterisk (*) either at the beginning of the string or trailing the string, e.g. `*.mypackage` or `org.mycompany.*`. The * matches zero or more characters, thus making the pattern a generic prefix or suffix pattern. A sole * can also be specified to represent all strings.
  > method
  >   This field is used to specify a pattern for the method name. The pattern should be specified as a string with no embedded blanks and with the same specification rules as the class field.
  > mode
  >   This field specifies whether the package or class that matches the pattern is to be included or excluded from profiling. The value for mode is either 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.

  ### Controlling the Java Profiling Agent

  When the Java Profiling Agent is started with the `server=enabled` or `server=controlled` parameter, communication with the agent is done using the client workbench by means of the Agent Controller on the host machine.

  ### Notes about the Java Profiler

  - If you do not specify a filter definition file name on the command line, the Java Profiling Agent tries to read the filters from the file named filters.txt in the current directory. If the file filters.txt does not exist, no filters will be used during the profiling session. If you name your filters file filters.txt and place it in the current directory, you do not need to specify the filters parameter on the command line for your filters to be used by the profiling agent.
  - If you do not specify an output file for the profiling data, it will be saved in the file trace.trcxml
  - You do not have to specify an extension for the output file. It automatically gets the extension .trcxml
  - You do not have to specify the extension for your Java application. It can be a .class file.

  ## Uninstalling Agent Controller

  To uninstall the agent controller:

  1. Stop the Agent Controller. See Stopping Agent Controller.
  2. Remove the `<install-dir>`.
  3. Remove the `<install-dir>/lib` directory from the LIBPATH environment variable, if necessary.

  Copyright (C) 2005, 2009 Intel Corporation and others.