Querying Agent Controller version information
Checking Agent Controller Installation
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
Only using the -agentpath Java option to invoke the Java Profiling Agent
Format of the Class Filter File
Controlling the Java Profiling Agent
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.
<install-dir> = The absolute directory path where the Agent Controller has been unzipped. For example: /opt/tptpAC
See the <install-dir>/plugins directory for a list of plug-ins the Agent Controller depends on.
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.
After a normal installation, you still need to configure the Agent Controller before you can start it.
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.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.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/*
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.
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.
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.
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:
------------------- 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.
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.
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.
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.
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
-agentlib:JPIBootLoader=JPIAgent[:[help]|[<option>=<value>,...]];<profiler>[:<option>=<value>,...]
The command line is structured as follows:
execdetails=[true | false] : whether to collect execution flow/call-graph information (true) or not (false). Default is false.
allocsites=[true | false] : whether to collect object allocation site information (true) or not (false). Default is false.
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.
java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld
java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true' HelloWorld
LD_LIBRARY_PATH
environmental variables. The answer is to use -agentpath
instead of LD_LIBRARY_PATH
setting + -agentlib Java option. It is suggested -agentpath
is only used when you can not set LD_LIBRARY_PATH
environmental variables for some reason. Compared with -agentlib
command line, there are two differences. Other profiling
options are the same with agentlib part.
The first difference is JPIBootLoader part changes in command. You should give the profilers' absolute path before JPIBootLoader. And please note on Linux, when using absolute path and file name to load a library, the entire library file name must be used. So libJPIBootLoader.so should be used instead of JPIBootLoader or libJPIBootLoader.
The second difference is related with profiling -server option. We have known there are three possible values
for -server option: standalone, enabled and controlled. For standalone mode,
it is enough to provide with profilers' absolute path after -agentpath as mentioned above.
However, Agent Controller will be needed for enabled and controlled. Since Agent
Controller path information is not set in environmental variables, it must be provided in command line as need: when you are using -agentpath
, if
profilers are Eclipse default plugins or Agent Controller self-contained Java profilers, additional Agent Controller path information is
unnecessary, otherwise you should provide it with profiling option ac_home in -agentpath command line.
Please refer to examples below about details.
**Note:
<<Eclipse Home>>/plugins/org.eclipse.tptp.platform.jvmti.runtime_<version>/agent_files/<os_platform>
<<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler
java '-agentpath:<Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld
java '-agentpath:<AC self-contained Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:server=enabled,file=log.trcxml;CGProf' HelloWorld
java '-agentpath:<Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:ac_home=<Agent Controller Home>,server=enabled,file=log.trcxml;CGProf' HelloWorld
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.
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.
To uninstall the agent controller: