Attachment 63391 Details for Bug 159817 – Java Profiler command line support for TPTP 4.4.

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Java Profiler command line support for TPTP 4.4.

teprofsa.htm (text/html), 18.50 KB, created by Guru Nagarajan

on 2007-04-10 13:18:19 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: Guru Nagarajan

Created: 2007-04-10 13:18:19 EDT

Size: 18.50 KB

patch

obsolete

><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
>
><html>
>
><head>
><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
><title>Profiling an application in stand-alone mode</title>
><link rel="stylesheet" type="text/css" href="../css/book.css" >
></head>
>
><body>
>
><h1>Profiling an application in stand-alone mode</h1>
>
><img src="../images/ngwin.gif" alt="The following information applies to Windows." border="0">&nbsp;
><img src="../images/nglinux.gif" alt="The following information applies to Linux." border="0">
>You can profile an application in stand-alone mode (that is, from the command
> line), without having&nbsp;the the Test and Performance Tools Platform installed.&nbsp;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.
>
><a href="#Stand-alone_profiling_for_Java_1.4_and_lower_java_virtual_machines_">
>Using the profiler with Java 1.4 (or lower) virtual machines</a> 
>
><a href="#Stand-alone_profiling_for_Java_1.5_and_higher_java_virtual_machines">
>Using the profiler with Java 5.0 (or higher) virtual machines</a> 
><a href="#Format_of_the_Class_Filter_file">Format of the Class Filter file</a> 
><a href="#Java_Profiling_Agent_Control">Controlling the Java Profiling Agent</a> 
><a href="#Java_Profiling_Notes">Notes</a>
>
><h2>
><a name="Stand-alone_profiling_for_Java_1.4_and_lower_java_virtual_machines_">
>Using the profiler with Java 1.4 (or lower) virtual machines</a></h2>
>Use the -<samp>Xrun</samp> Java option to invoke the Java Profiling Agent:
><samp>&nbsp;&nbsp;&nbsp; -XrunpiAgent:agent_parm[,agent_parm]*</samp>
>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: 
>&nbsp;&nbsp;&nbsp; <samp>java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml
> PerformanceExample</samp>
><dl>
> <dt>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:</dt>
></dl>
><ol>
>	<li>Go to &lt;profile root&gt;/config/cells/&lt;nodename&gt;Cell/nodes/&lt;nodename&gt;/servers/server1</li>
>	<li>Edit the jvmEntries element in the server.xml file. In that element, there is an attribute called genericJvmArguments. Append 
>	<tt>-XrunpiAgent:server=enabled</tt> to the attribute value.</li>
>	<li>Restart WAS. 
>&nbsp;</li>
></ol>
><dl>
> <dt>&nbsp;</dt>
>	<dt>By augmenting the -XrunpiAgent parameter you can specify several 
> different modes to run the profiling agent in. The parameter
> <samp>agent_parm</samp> can take one of the following values:</dt>
></dl>
><ul>
><li>server=[standalone | enabled | controlled | application] 
> <dl>
> <dt>standalone</dt>
> <dd>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. 
> </dd>
> <dd>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. 
> </dd>
> <dt>enabled (This is the default.)</dt>
> <dd>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. 
> </dd>
> <dt>controlled </dt>
> <dd>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. 
> </dd>
> <dt>application </dt>
> <dd>The Java Profiling Agent is loaded, runs in the background, and allows
> the application to run normally as in enabled mode. </dd>
> <dd>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. </dd>
> <dd>Note: All profiling is controlled by the application, using the
> org.eclipse.hyades.collection.profiler.Profiler class. 
> 
> </dd>
> 
> </dl>
> </li>
><li>profile=profile file 
>This option is only applicable when <tt>server=standalone</tt>. 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. <ul>
><li> Specify the
><tt>profile=filename</tt> option, for example <pre>-XrunpiAgent:server=standalone,profile=&lt;profile_filename&gt;</pre>
></li>
><li>Name the profile options file <tt>jvmpi.pro</tt> and put in
>the directory where the Java process is launched. The profiler will recognize
>the existence of this file and will launch the process as if the user had specified
><tt>-XrunpiAgent:server=standalone,profile=./jvmpi.pro</tt> as a VM argument. 
></li>
></ul>
>See <a href="../ref/rsaproffilt.htm">Stand-alone profile filter options</a> for a list of valid options for the profile file.
><li>filters=filename 
> Used only when <samp>server=standalone</samp> is specified. 
> Specifies the name of the file that contains the initial class filter
> definitions to be used during the&nbsp;profiling session. The default file
> name is filters.txt in the current directory. See below for information about
> the file format.
></li>
><li>file=filename 
> Used only when <samp>server=standalone</samp> 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.
></li>
><li>help 
> Displays a list of available agent options to STDOUT.</li>
> </ul>
> 
> <h2>
><a name="Stand-alone_profiling_for_Java_1.5_and_higher_java_virtual_machines">
>Using the profiler with Java 5.0 (or higher) virtual machines</a></h2>
><div id="main_content">
>Use the -<samp>agentlib</samp> Java option to invoke the Java Profiling Agent:
>-agentlib:JPIBootLoader=JPIAgent[:[help]|[&lt;option&gt;=&lt;value&gt;,...]];&lt;profiler&gt;[:&lt;option&gt;=&lt;value&gt;,...]
>	The command line is structured as follows:
>	<dl>
>	<dt>JPIBootLoader is the library that loads the profiling agent.</dt>
>	<dt>&nbsp;</dt>
>	<dt>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:</dt>
></dl>
><ul>
><li>server=[standalone | enabled | controlled] 
> <dl>
> <dt>standalone</dt>
> <dd>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. 
> </dd>
> <dd>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. 
> </dd>
> <dt>enabled (This is the default.)</dt>
> <dd>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. 
> </dd>
> <dt>controlled </dt>
> <dd>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. 
> </dd>
> 
> 
> </dl>
> </li>
><li>filters=filename 
> Used only when <samp>server=standalone</samp> is specified. 
> Specifies the name of the file that contains the initial class filter
> definitions to be used during the&nbsp;profiling session. The default file
> name is filters.txt in the current directory. See below for information about
> the file format.
></li>
><li>file=filename 
> Used only when <samp>server=standalone</samp> 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.
></li>
><li>help 
> Displays a list of available agent options to STDOUT.</li>
> </ul>
> <dl>
> 	<dt>&lt;Profiler&gt; is the name of the Profiler Library to load. Some of the 
>	available profilers support additional profiler-specific options, as 
>	described below:</dt>
>	<ul type="disc">
>	<li>CGProf 
>	Execution time analysis. Supports the following options:execdetails=[true 
>	| false] : whether to collect execution flow/call-graph information 
>	(<samp>true</samp>) or not (<samp>false</samp>). Default is <samp>false</samp>.</li>
>	<li>HeapProf 
>	Object allocation/heap analysis. Supports the following options:
>	allocsites=[true 
>	| false] : whether to collect object allocation site information 
>	(<samp>true</samp>) or not (<samp>false</samp>). Default is <samp>false</samp>.</li>
>		<li>ThreadProf 
>		Thread analysis.</li>
>	</ul>
> </dl>
>	To run the Java Profiling Agent in standalone mode on Windows, perform the 
>	following steps:
>	<ol>
>		<li>Set <code>TPTP_AC_HOME=&lt;&lt;Agent Controller Home&gt;&gt;</code></li>
>		<li>Set <code>JAVA_PROFILER_HOME=%TPTP_AC_HOME%\plugins\org.eclipse.tptp.javaprofiler</code></li>
>		<li>Set <code>PATH=%JAVA_PROFILER_HOME%;%PATH%;%TPTP_AC_HOME%\bin</code></li>
>		<li>Set <code>PATH=%PATH%;%JAVA_HOME%\bin</code></li>
>		<li>Execute the Java application with the <samp>-agentlib</samp> parameter as described above</li>
>	</ol>
></div>
>&nbsp;
>To run the Java Profiling Agent in standalone mode on Linux, perform the 
>following steps:
><ol>
>	<li>Set <code>TPTP_AC_HOME=&lt;&lt;Agent Controller Home&gt;&gt;</code> 
>	</li>
>	<li>Set <code>JAVA_PROFILER_HOME=%TPTP_AC_HOME%/plugins/org.eclipse.tptp.javaprofiler</code> 
>
>	</li>
>	<li>Add the following directories to <code>LD_LIBRARY_PATH:</code> 
>	</li>
></ol>
>%JAVA_PROFILER_HOME%:%TPTP_AC_HOME%/lib 
>&nbsp;
><ol start="4">
>	<li>Execute the Java application with the <samp>-agentlib</samp> parameter as described above. </li>
></ol>
><div id="main_content">
>	<blockquote>
>		Note 
>		 
>		On Linux, make sure to surround the entire &#8211;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.
>	</blockquote>
></div>
>Examples
>Profiling the &quot;HelloWorld&quot; Java application with the CPU Profiler in 
>standalone mode, writing results into log.trcxml:
>java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld
>Profiling the &quot;HelloWorld&quot; Java application with the Heap Profiler in 
>standalone mode, using filters defined in myFilter.txt, and collecting 
>information about the source locations were objects are allocated:
>java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld
>
><h2><a name="Format_of_the_Class_Filter_file">
>Format of the Class Filter file</a></h2>
>The filter file should specify three fields, package/class, method, and mode in the
>following format: 
>&nbsp;&nbsp;&nbsp;<tt>package/class method mode</tt> 
> 
> where: 
> <blockquote>
> <dl>
> <dt>package/class </dt>
> <dd>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. <tt>*.mypackage</tt> or <tt>org.mycompany.*</tt>. 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.</dd>
> <dt>method </dt>
> <dd>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.</dd>
> <dt>mode</dt>
> <dd>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.</dd>
> </dl>
> </blockquote>
>Filter patterns are processed in the order that they are specified until the
> first pattern match succeeds.&nbsp;If the class name does not match any of
> the specified filter patterns, the default is to INCLUDE the class.
><h2><a name="Java_Profiling_Agent_Control">
>Controlling the Java Profiling Agent</a></h2>
>When the Java Profiling Agent is started with the <samp>server=enabled</samp>
> or <samp>server=controlled</samp> parameter, communication with the agent is
> done using the client workbench by means of the Agent Controller on the host
> machine.
> 
><h2><a name="Java_Profiling_Notes">Notes</a></h2>
><ul>
><li>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.</li>
><li>If you do not specify an output file for the profiling data, it will be saved 
> in the file trace.trcxml</li>
><li>You do not have to specify an extension for the output file. It automatically 
> gets the extension .trcxml</li>
><li>You do not have to specify the extension for your Java application. It
> can be a .class file.</li>
></ul>
> 
>&nbsp;
> 
>Related concepts 
><a href="../concepts/ceproftl.htm">Overview of the Profiling Tool</a> 
><a href="../concepts/cemonitr.htm">Profiling resources</a> 
>
> 
>Related tasks 
> <a href="../tasks/tprofas400.htm">Profiling an application in standalone mode on AS/400</a> 
> <a href="teprlaun.htm">Launching or attaching a Java process</a> 
> <a href="../tasks/tuseprmnvw.htm">Using the Profiling monitor view</a> 
>
> 
> 
>(C) Copyright IBM Corporation 2000, 2006. All Rights Reserved.
> 
>
></body></html>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!-- 
/**********************************************************************
 * Copyright (c) 2000, 2007 IBM Corporation.
 * All rights reserved. This content
 * is made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html        
 * $Id: teprofsa.htm,v 1.13 2007/04/06 01:39:36 jkubasta Exp $
 *
 * Contributors:
 * IBM - Initial contribution
 **********************************************************************/  
 -->
<html>

<head>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<title>Profiling an application in stand-alone mode</title>
<link rel="stylesheet" type="text/css" href="../css/book.css" >
</head>

<body>

<h1>Profiling an application in stand-alone mode</h1>
<p>
<img src="../images/ngwin.gif" alt="The following information applies to Windows." border="0">&nbsp;
<img src="../images/nglinux.gif" alt="The following information applies to Linux." border="0">
You can profile an application in stand-alone mode (that is, from the command
 line), without having&nbsp;the the Test and Performance Tools Platform installed.&nbsp;However, you do 
 need to have the  Agent Controller installed on the machine where the 
 application to be profiled resides.<br>
</p>
<p>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.</p>
<p><b>
<a href="#Stand-alone_profiling_for_Java_1.4_and_lower_java_virtual_machines_">
Using the profiler with Java 1.4 (or lower) virtual machines</a></b><br>
<b>
<a href="#Stand-alone_profiling_for_Java_1.5_and_higher_java_virtual_machines">
Using the profiler with Java 5.0 (or higher) virtual machines</a></b><br>
<b><a href="#Format_of_the_Class_Filter_file">Format of the Class Filter file</a></b><br>
<b><a href="#Java_Profiling_Agent_Control">Controlling the Java Profiling Agent</a></b><br>
<b><a href="#Java_Profiling_Notes">Notes</a></b>
</p>
<h2><b>
<a name="Stand-alone_profiling_for_Java_1.4_and_lower_java_virtual_machines_">
Using the profiler with Java 1.4 (or lower) virtual machines</a></b></h2>
<p>Use the -<samp>Xrun</samp> Java option to invoke the Java Profiling Agent:</p>
<p><samp>&nbsp;&nbsp;&nbsp; -XrunpiAgent:agent_parm[,agent_parm]*</samp></p>
<p>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:<br>
&nbsp;&nbsp;&nbsp; <samp>java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml
 PerformanceExample</samp></p>
<dl>
   <dt>Note:<span style="font-weight: 400"> 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:</span></dt>
</dl>
<ol>
	<li>Go to &lt;profile root&gt;/config/cells/&lt;nodename&gt;Cell/nodes/&lt;nodename&gt;/servers/server1</li>
	<li>Edit the jvmEntries element in the server.xml file. In that element, there is an attribute called genericJvmArguments. Append 
	<tt>-XrunpiAgent:server=enabled</tt> to the attribute value.</li>
	<li>Restart WAS.<br>
&nbsp;</li>
</ol>
<dl>
   <dt>&nbsp;</dt>
	<dt>By augmenting the <em>-XrunpiAgent</em> parameter you can specify several 
   different modes to run the profiling agent in. The parameter
   <samp>agent_parm</samp> can take one of the following values:</dt>
</dl>
<ul>
<li><strong>server=[standalone | enabled | controlled | application]</strong><br>
   <dl>
     <dt><strong>standalone</strong></dt>
     <dd>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.<br>
     </dd>
     <dd>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= <em>filename </em>parameter. When this option is selected, the Java
     Profiling Agent produces an enclosing traceRoot element to form a complete
     and valid XML document.<br>
     </dd>
     <dt><strong>enabled</strong> (This is the default.)</dt>
     <dd>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.<br>
     </dd>
     <dt><strong>controlled</strong> </dt>
     <dd>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.<br>
     </dd>
     <dt><strong>application</strong> </dt>
     <dd>The Java Profiling Agent is loaded, runs in the background, and allows
     the application to run normally as in enabled mode. </dd>
     <dd>It only produces profiling data when two conditions are satisfied.
     First, the application must have requested that the profiling agent start
     profiling using <em>org.eclipse.hyades.collection.profiler.Profiler</em> and
     second, the test client of the workbench must have attached to the Java
     Profiling Agent and started monitoring.<br></dd>
     <dd><strong>Note:</strong> All profiling is controlled by the application, using the
     <em>org.eclipse.hyades.collection.profiler.Profiler</em> class.<br>
     <br>
     </dd>
  
   </dl>
   </li>
<li><strong>profile=<em>profile file</em></strong><br>
This option is only applicable when <tt>server=standalone</tt>. 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.<br> 
The file can be loaded in one of two ways. <ul>
<li> Specify the
<tt>profile=<em>filename</em></tt> option, for example <pre>-XrunpiAgent:server=standalone,profile=&lt;profile_filename&gt;</pre>
</li>
<li>Name the profile options file <tt>jvmpi.pro</tt> and put in
the directory where the Java process is launched. The profiler will recognize
the existence of this file and will launch the process as if the user had specified
<tt>-XrunpiAgent:server=standalone,profile=./jvmpi.pro</tt> as a VM argument. 
</li>
</ul>
See <a href="../ref/rsaproffilt.htm">Stand-alone profile filter options</a> for a list of valid options for the profile file.
<li><strong>filters=<em>filename</em></strong><br>
   Used only when <samp>server=standalone</samp> is specified.<br>
   Specifies the name of the file that contains the initial class filter
   definitions to be used during the&nbsp;profiling session. The default file
   name is filters.txt in the current directory. See below for information about
   the file format.
</li>
<li><strong>file=</strong><em><strong>filename</strong></em><br>
   Used only when <samp>server=standalone</samp> is specified.<br>
   Specifies the name of a file that the profiling data will be written to. The
   default is trace.trcxml in the current directory.
</li>
<li><strong>help</strong><br>
   Displays a list of available agent options to STDOUT.</li>
 </ul>
 
 <h2><b>
<a name="Stand-alone_profiling_for_Java_1.5_and_higher_java_virtual_machines">
Using the profiler with Java 5.0 (or higher) virtual machines</a></b></h2>
<div id="main_content">
<p>Use the -<samp>agentlib</samp> Java option to invoke the Java Profiling Agent:</p>
<p class="Code">-agentlib:JPIBootLoader=JPIAgent[:[help]|[&lt;option&gt;=&lt;value&gt;,...]];&lt;profiler&gt;[:&lt;option&gt;=&lt;value&gt;,...]</p>
	<p>The command line is structured as follows:</p>
	<dl>
	<dt><i>JPIBootLoader</i> is the library that loads the profiling agent.</dt>
	<dt>&nbsp;</dt>
	<dt><i>JPIAgent</i> is the Java 5.0+ profiling agent. By augmenting the <em>JPIAgent</em> part of the command line with 
	additional options, you can control the behavior of the profiling agent. The 
	following options are supported:</dt>
</dl>
<ul>
<li><strong>server=[standalone | enabled | controlled]</strong><br>
   <dl>
     <dt><strong>standalone</strong></dt>
     <dd>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.<br>
     </dd>
     <dd>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= <em>filename </em>parameter. When this option is selected, the Java
     Profiling Agent produces an enclosing traceRoot element to form a complete
     and valid XML document.<br>
     </dd>
     <dt><strong>enabled</strong> (This is the default.)</dt>
     <dd>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.<br>
     </dd>
     <dt><strong>controlled</strong> </dt>
     <dd>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.<br>
     </dd>
     
  
   </dl>
   </li>
<li><strong>filters=<em>filename</em></strong><br>
   Used only when <samp>server=standalone</samp> is specified.<br>
   Specifies the name of the file that contains the initial class filter
   definitions to be used during the&nbsp;profiling session. The default file
   name is filters.txt in the current directory. See below for information about
   the file format.
</li>
<li><strong>file=</strong><em><strong>filename</strong></em><br>
   Used only when <samp>server=standalone</samp> is specified.<br>
   Specifies the name of a file that the profiling data will be written to. The
   default is trace.trcxml in the current directory.
</li>
<li><strong>help</strong><br>
   Displays a list of available agent options to STDOUT.</li>
 </ul>
 <dl>
 	<dt>&lt;Profiler&gt; is the name of the Profiler Library to load. Some of the 
	available profilers support additional profiler-specific options, as 
	described below:</dt>
	<ul type="disc">
	<li><strong>CGProf</strong><br>
	Execution time analysis. Supports the following options:<p><i><b>execdetails=[true 
	| false]</b></i> : whether to collect execution flow/call-graph information 
	(<samp>true</samp>) or not (<samp>false</samp>). Default is <samp>false</samp>.</li>
	<li><strong>HeapProf</strong><br>
	Object allocation/heap analysis. Supports the following options:<p><b><i>
	allocsites</i></b><i><b>=[true 
	| false]</b></i> : whether to collect object allocation site information 
	(<samp>true</samp>) or not (<samp>false</samp>). Default is <samp>false</samp>.</li>
		<li><strong>ThreadProf</strong><br>
		Thread analysis.</li>
	</ul>
 </dl>
	<p>To run the Java Profiling Agent in standalone mode on Windows, perform the 
	following steps:</p>
	<ol>
		<li>Set <code>TPTP_AC_HOME=&lt;&lt;Agent Controller Home&gt;&gt;</code></li>
		<li>Set <code>JAVA_PROFILER_HOME=%TPTP_AC_HOME%\plugins\org.eclipse.tptp.javaprofiler</code></li>
		<li>Set <code>PATH=%JAVA_PROFILER_HOME%;%PATH%;%TPTP_AC_HOME%\bin</code></li>
		<li>Set <code>PATH=%PATH%;%JAVA_HOME%\bin</code></li>
		<li>Execute the Java application with the <samp>-agentlib</samp> parameter as described above</li>
	</ol>
</div>
<p>&nbsp;</p>
<p>To run the Java Profiling Agent in standalone mode on Linux, perform the 
following steps:</p>
<ol>
	<li>Set <code>TPTP_AC_HOME=&lt;&lt;Agent Controller Home&gt;&gt;</code> 
	</li>
	<li>Set <code>JAVA_PROFILER_HOME=%TPTP_AC_HOME%/plugins/org.eclipse.tptp.javaprofiler</code> 

	</li>
	<li>Add the following directories to <code>LD_LIBRARY_PATH:</code> 
	</li>
</ol>
<p class="Code">%JAVA_PROFILER_HOME%:%TPTP_AC_HOME%/lib<br>
&nbsp;</p>
<ol start="4">
	<li>Execute the Java application with the <samp>-agentlib</samp> parameter as described above. </li>
</ol>
<div id="main_content">
	<blockquote>
		<p><b>Note<br>
		<br>
		</b>On Linux, make sure to surround the entire &#8211;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.</p>
	</blockquote>
</div>
<p>Examples</p>
<p><b>Profiling the &quot;HelloWorld&quot; Java application with the CPU Profiler in 
standalone mode, writing results into log.trcxml:</b></p>
<p class="Code">java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld</p>
<p><b>Profiling the &quot;HelloWorld&quot; Java application with the Heap Profiler in 
standalone mode, using filters defined in myFilter.txt, and collecting 
information about the source locations were objects are allocated:</b></p>
<p class="Code">java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld</p>

<h2><a name="Format_of_the_Class_Filter_file">
Format of the Class Filter file</a></h2>
<p>The filter file should specify three fields, <em>package/class</em>, <em>method</em>, and <em>mode</em> in the
following format:<br>
&nbsp;&nbsp;&nbsp;<tt>package/class method mode</tt><br>
<br>
 where: </p>
 <blockquote>
   <dl>
     <dt><strong>package/class</strong> </dt>
     <dd>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. <tt>*.mypackage</tt> or <tt>org.mycompany.*</tt>. 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.</dd>
     <dt><strong>method</strong> </dt>
     <dd>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 <em>class</em> field.</dd>
     <dt><strong>mode</strong></dt>
     <dd>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.</dd>
   </dl>
 </blockquote>
<p>Filter patterns are processed in the order that they are specified until the
 <em>first</em> pattern match succeeds.&nbsp;If the class name does not match any of
 the specified filter patterns, the default is to INCLUDE the class.</p>
<h2><a name="Java_Profiling_Agent_Control">
Controlling the Java Profiling Agent</a></h2>
<p>When the Java Profiling Agent is started with the <samp>server=enabled</samp>
 or <samp>server=controlled</samp> parameter, communication with the agent is
 done using the client workbench by means of the Agent Controller on the host
 machine.</p>
 
<h2><a name="Java_Profiling_Notes">Notes</a></h2>
<ul>
<li>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.</li>
<li>If you do not specify an output file for the profiling data, it will be saved 
   in the file trace.trcxml</li>
<li>You do not have to specify an extension for the output file. It automatically 
   gets the extension .trcxml</li>
<li>You do not have to specify the extension for your Java application. It
   can be a .class file.</li>
</ul>
 
<p>&nbsp;</p>
 
<p><strong>Related concepts</strong><br>
<a href="../concepts/ceproftl.htm">Overview of the Profiling Tool</a><br>
<a href="../concepts/cemonitr.htm">Profiling resources</a><br>
</p>
 
<p><strong>Related tasks</strong><br>
   <a href="../tasks/tprofas400.htm">Profiling an application in standalone mode on AS/400</a><br>
   <a href="teprlaun.htm">Launching or attaching a Java process</a><br>
   <a href="../tasks/tuseprmnvw.htm">Using the Profiling monitor view</a><br>
</p>
 
<br>
<p class="copyright">(C) Copyright IBM Corporation 2000, 2006. All Rights Reserved.</p>
<br>

</body></html>

Actions: View

Attachments on bug 159817: 63228 | 63229 | 63264 | 63355 | 63391 | 64509