Profiling an application in stand-alone mode
You can profile an application in stand-alone mode (that is, from the command
line), without having the the Test and Performance Tools Platform installed. However, you do
need to have the Agent Controller installed on the machine where the
application to be profiled resides.
You can profile an application in stand-alone mode 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.
** Note: Before starting the command line invocation, make sure that the profiling agent libraries are setup in the system LD_LIBRARY_PATH variable for
TPTP 4.5.2 (or lower). For TPTP 4.6.0 (or higher) which do not support Java 1.4 (or lower), PATH(Windows)/LD_LIBRARY_PATH(Linux) setting is optional and the details will be described later.
Read thru the following section for instruction on environment variable setup.
If need PATH(Windows)/LD_LIBRARY_PATH(Linux) setting, how to setup 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 Command Prompt session:
For Windows:
Set TPTP_AC_HOME=<<Agent Controller Home>>
Set JAVA_PROFILER_HOME=%TPTP_AC_HOME%\plugins\org.eclipse.tptp.javaprofiler
Set PATH=%JAVA_PROFILER_HOME%;%TPTP_AC_HOME%\bin;%PATH%
For Linux:
export TPTP_AC_HOME=<<Agent Controller Home>>
export JAVA_PROFILER_HOME=$TPTP_AC_HOME/plugins/org.eclipse.tptp.javaprofiler
export LD_LIBRARY_PATH=$JAVA_PROFILER_HOME:$TPTP_AC_HOME/lib:$LD_LIBRARY_PATH
**Note: Actually, it is possible not to use environment variables JAVA_PROFILER_HOME
and TPTP_AC_HOME
for TPTP 4.6.0 (or higher).
The dependency on JAVA_PROFILER_HOME
and TPTP_AC_HOME
have been removed. So you can add the necessary
path directly into:
PATH
for Windows:
<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler:<<Agent Controller Home>>\bin
LD_LIBRARY_PATH
for Linux:
<<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler:<<Agent Controller Home>>/lib
Using the profiler with Java 1.4 (or lower) virtual machines
Using the profiler with Java 5.0 (or higher) virtual machines
Using environmental variables 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
Notes
Use the -Xrun Java option to invoke the Java Profiling Agent:
-XrunpiAgent:agent_parm[,agent_parm]*
For example, to profile PerformanceExample.java, using filters that are defined in the file myFilters.txt, and
directing the data from the profiling session to a file called PEProfilingData,
you would type the following on a command line:
java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml
PerformanceExample
Note: If you want to start WebSphere
Application Server Version 6 (WAS) in profiling mode from the command line,
you have to perform the following steps:
- Go to <profile root>/config/cells/<nodename>Cell/nodes/<nodename>/servers/server1
- Edit the jvmEntries element in the server.xml file. In that element, there is an attribute called genericJvmArguments. Append
-XrunpiAgent:server=enabled to the attribute value.
- Restart WAS.
By augmenting the -XrunpiAgent parameter you can specify several
different modes to run the profiling agent in. The parameter
agent_parm can take one of the following values:
- server=[standalone | enabled | controlled | application]
- 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
using configuration files and 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.
That is, the Java Profiling Agent is loaded, 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.
- application
- The Java Profiling Agent is loaded, runs in the background, and allows
the application to run normally as in enabled mode.
- It only produces profiling data when two conditions are satisfied.
First, the application must have requested that the profiling agent start
profiling using org.eclipse.hyades.collection.profiler.Profiler and
second, the test client of the workbench must have attached to the Java
Profiling Agent and started monitoring.
- Note: All profiling is controlled by the application, using the
org.eclipse.hyades.collection.profiler.Profiler class.
- profile=profile file
This option is only applicable when server=standalone. This file specifies the options
with which you want the profiler to run when in standalone mode. The options specified in this file
are usually set in the profiling configurations window when the user launches a Java
process from the workbench; the use of this file is an equivalent way of
specifying options when running in standalone mode.
The file can be loaded in one of two ways.
See Stand-alone profile filter options for a list of valid options for the profile file.
- 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.
To run the Java Profiling Agent on Linux with -agentlib option, perform the
LD_LIBRARY_PATH setting steps mentioned before, then execute the Java application with the -agentlib
parameter as described above.
Use 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 line interface and 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 in standalone mode, perform the following steps:
- Setup environmental variables as mentioned before
- Execute the Java application with the -agentlib parameter as described above
Note:
On Linux, make sure to 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
- To profile the "HelloWorld" Java application with the CPU Profiler in
standalone mode and write the results into log.trcxml:
For Windows:
java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld
For Linux:
java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld
- 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:
For Windows:
java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld
For Linux:
java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true' HelloWorld
For TPTP 4.6.0 (or higher), it is possible to not set additional environmental variables. The answer is to use -agentpath
instead of PATH
(Windows) / LD_LIBRARY_PATH
(Linux) setting + -agentlib Java option. It is suggested
-agentpath
is only used when you can not set 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 for Linux.
The second difference is related with profiling -server option. We have known there are three possible values
for -server option: standalone, enabled and controlled mode. 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 about Eclipse default plugins or Agent Controller self-contained Java profilers:
For Windows:
Eclipse default plugins Java profilers should be in:
<<Eclipse Home>>\plugins\org.eclipse.tptp.platform.jvmti.runtime_<version>\agent_files\<os_platform>
Agent Controller self-contained Java profilers should be in:
<<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler
For Linux:
Eclipse default plugins Java profilers should be in:
<<Eclipse Home>>/plugins/org.eclipse.tptp.platform.jvmti.runtime_<version>/agent_files/<os_platform>
Agent Controller self-contained Java profilers should be in:
<<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler
Examples
- To profile the "HelloWorld" Java application with the CPU Profiler in
standalone mode and write the results into log.trcxml:
For Windows:
java -agentpath:<Java profilers absolute path>\JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld
For Linux:
java '-agentpath:<Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld
- To profile the "HelloWorld" Java application with the CPU Profiler in
enabled mode and write the results into log.trcxml using Agent Controller self-contained Java profilers:
For Windows:
java -agentpath:<AC self-contained Java profilers absolute path>\JPIBootLoader=JPIAgent:server=enabled,file=log.trcxml;CGProf HelloWorld
For Linux:
java '-agentpath:<AC self-contained Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:server=enabled,file=log.trcxml;CGProf' HelloWorld
- To profile the "HelloWorld" Java application with the CPU Profiler in
enabled mode and write the results into log.trcxml when Agent Controller path info is needed:
For Windows:
java -agentpath:<Java profilers absolute path>\JPIBootLoader=JPIAgent:ac_home=<Agent Controller Home>,server=enabled,file=log.trcxml;CGProf HelloWorld
For Linux:
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.
- 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.
Related concepts
Overview of the Profiling Tool
Profiling resources
Related tasks
Launching or attaching a Java process
Using the Profiling monitor view
(C) Copyright IBM Corporation 2000, 2010. All Rights Reserved.