Attachment 64509 Details for Bug 159817 – Updates based on Guru's and Paul's comments

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

Updates based on Guru's and Paul's comments

getting_started.html (text/html), 28.52 KB, created by jkubasta

on 2007-04-21 11:26:31 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: jkubasta

Created: 2007-04-21 11:26:31 EDT

Size: 28.52 KB

patch

obsolete

><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
><html>
><head>
>
> <style type="text/css"></style>
> <meta http-equiv="Content-Type"
> content="text/html; charset=iso-8859-1">
> <style type="text/css"></style>
><title>Getting Started with Agent Controller - Linux</title>
></head>
><body>
><h1>Getting Started with Agent Controller - Linux</h1>
><h3>Contents</h3>
>
><a href="#Overview">Overview</a>
>
><a href="#Prerequisites">Prerequisites</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Notation">Notation</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Installation">Installing Agent Controller</a>
>
><a href="#Setting_Up_Agent_Controller">Setting Up Agent Controller</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Configure_Agent_Controller">Configuring Agent Controller</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Start_Agent_Controller">Starting Agent Controller</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Stop_Agent_Controller">Stopping Agent Controller</a>
>
><a href="#queryversion">Querying Agent Controller version information</a>
>
><a href="#Checking_Agent_Controller_Installation">Checking Agent Controller Installation</a>
>
><a href="#serverlog">Server Logging</a>
>
><a href="#javaprof">Profiling a Java Application</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Invocation_from_the_Eclipse_Workbench">Invocation of the Java Profiler from the Eclipse 
>Workbench</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Invocation_of_the_Java_Profiler_from_the_Command_Line">Invocation of 
>the Java Profiler from the Command Line</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Java_14">Using the Java Profiler with Java 1.4 (or lower) Virtual Machines</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Java_15">Using the Java Profiler with Java 1.5 (or higher) Virtual Machines</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Format_of_the_Class_Filter_file">Format of the Class Filter File</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Java_Profiling_Agent_Control">Controlling the Java Profiling Agent</a>
>&nbsp;&nbsp;&nbsp;
><a href="#Notes_about_the_Java_Profiler">Notes about the Java Profiler</a>
>
><a href="#uninstall">Uninstalling Agent Controller</a>
><h2><a name="Overview">Overview</a></h2>
>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. For more information, 
>see <a href="../../../../org.eclipse.tptp.platform.agentcontroller.doc.user/concepts/ac/ciacintro.html">Integrated Agent Controller</a>
>
><h2><a name="Prerequisites">Prerequisites</a></h2>
><ul>
> <li>Install the Java runtime (JRE) or Java development kit (JDK) 1.5 or 1.4.x 
> </li>
> <li>Remove or <a href="#uninstall">uninstall</a> all prior versions of Agent 
>	Controller.</li>
> <li>The Agent Controller is compiled using <tt>libstdc++-libc6.2-2.so.3</tt>
>shared library.
>Ensure that this shared library exists under the <tt>/usr/lib</tt>
>directory. If it does not exist, you have to install the
>RPM package <tt>compat-libstdc++</tt> that comes with the operating
>system installation media.</li>
></ul>
><h3><a name="Notation">Notation</a></h3>
>&lt;<tt>install-dir</tt>&gt; = The absolute directory path where the Agent 
>Controller has been unzipped.&nbsp; For example: <tt>/opt/tptpAC</tt>
><h3><a name="Installation">Installing Agent Controller</a></h3>
>Download one of the Linux Agent Controller Runtime packages from the TPTP 
>Download page. Install it by simply creating a directory and unzipping the 
>package contents into that directory.
><h2><a name="Setting_Up_Agent_Controller">Setting Up Agent Controller</a></h2>
>After a normal installation, you still need to configure the Agent Controller 
>before you can start it.&nbsp;
><h3><a name="Configure_Agent_Controller">Configuring Agent Controller</a></h3>
><ol>
> <li>Ensure that the files in the <tt>&lt;install-dir&gt;/bin</tt> and <tt>&lt;install-dir&gt;/lib</tt>
>directory are executable.</li>
> <li>Run <tt>SetConfig.sh</tt> script from a command shell in the <tt>
>	&lt;install-dir&gt;/bin</tt>
>	directory to generate the configuration file for the Agent Controller.&nbsp; 
>	The script requires that a Java Virtual Machine (JVM) be present in the PATH 
>	environment variable.&nbsp; Follow the prompts and enter the required 
>	parameters as appropriate.&nbsp; The configuration file <tt>
>	&lt;install-dir&gt;/config/serviceconfig.xml</tt>
> will be generated based on your inputs. 
> </li>
> <li>Add <tt>&lt;install-dir&gt;/bin</tt> directory to the PATH environment variable.</li>
>	<li>Add <tt>&lt;install-dir&gt;/lib</tt> directory to the LD_LIBRARY_PATH 
>	environment variable.</li>
></ol>
>If you want to make changes to the configuration file that was generated in 
>step 1, you may run the <tt>SetConfig.sh</tt> script again or you may manually 
>edit the file according to the rules outlined in the document 
><a href="http://help.eclipse.org/help32/topic/org.eclipse.tptp.platform.agentcontroller.doc.user/ref/ac/r_config_ovw.html">
>Agent Controller configuration files</a>. The Agent Controller must be restarted 
>for the changes to take effect.
><h3><a name="Start_Agent_Controller">Starting Agent Controller</a></h3>
>Start the Agent Controller by changing your working directory to&nbsp; <tt>
>&lt;install-dir&gt;/bin</tt> and running <tt>ACStart.sh</tt>.
>Note: The Agent Controller may also be started using <tt>RAStart.sh</tt>, in support of backward compatibility. 
><h3><a name="Stop_Agent_Controller">Stopping Agent Controller</a></h3>
>Stop the Agent Controller by changing your working directory to&nbsp; <tt>
>&lt;install-dir&gt;/bin</tt> and running <tt>ACStop.sh</tt>.
>Note: The Agent Controller may also be stopped using <tt>RAStop.sh</tt>, in support of backward compatibility.
> <h2><a name="queryversion"></a>Querying Agent Controller Version Information</h2>
>To display the version of Agent Controller, change your working directory to &lt;install-dir&gt;/bin in a command shell and run the following command:
><blockquote>
>	<tt>ACServer -v</tt> &nbsp;&nbsp;&nbsp; or <tt>ACServer -version</tt>
></blockquote>
>The Agent Controller will display its version and terminate.
>Note: The Agent Controller version may also be queried using <tt>RAServer</tt>, in support of backward compatibility.
><h2><a name="Checking_Agent_Controller_Installation"></a>Checking Agent Controller Installation</h2>
>
>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:
><ol>
>	<li><a href="#Start_Agent_Controller">Start the Agent Controller</a>.</li>
>	<li>Open a command prompt 
>	window</li>
>	<li>Go to the 
>	<tt>&lt;install-dir&gt;/bin</tt> 
>	directory</li>
>	<li>Enter the following at the 
>	command prompt: &nbsp;&nbsp;&nbsp; <tt>SampleClient</tt> &nbsp;</li>
>	<li>Observe the console output 
>	for SampleClient.&nbsp; It should be similar to the following example:</li>
></ol>
><blockquote>
>	<tt>------------------- SampleClient Console Output 
>-------------------------------- Connected to the Agent Controller on &quot;localhost&quot; 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...</tt>
></blockquote>
>Note:&nbsp; 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 <tt>
>readme.txt</tt> file for detailed information on the SampleClient 
>functionality.&nbsp; 
><h2><a name="serverlog"></a>Server Logging</h2>
>All server log entries will be placed in
><tt>&lt;install-dir&gt;/config/servicelog.log</tt>
>.
>
><h2><a name="javaprof"></a>Profiling a Java Application</h2>
>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 &quot;<a
> href="http://www.eclipse.org/tptp/platform/documents/resources/profilingspec/XML4Profiling.htm">Event 
>Specification for the Java Profiler</a>&quot;. 
>
>You can invoke the Java Profiling Agent from the Eclipse workbench or in standalone mode from the command 
>line. 
>
><h3><a name="Invocation_from_the_Eclipse_Workbench">Invocation of the Java Profiler from the Eclipse Workbench</a></h3>
>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 &gt; Open Profile Dialog... menu or the Profile toolbar button.&nbsp; The Profile 
>wizard will open.&nbsp; Simply follow the wizard to profile an application.&nbsp; 
>
><h3><a name="Invocation_of_the_Java_Profiler_from_the_Command_Line">Invocation 
>of the Java Profiler from the Command Line</a></h3>
>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.
><h3><a name="Java_14">Using the Java Profiler with Java 1.4 (or lower) Virtual Machines</h3>
>Use the <tt>-Xrun</tt> Java option to invoke the Java Profiling Agent, as follows:
><pre> -XrunpiAgent[:agent_parm[,agent_parm]*] </pre>
>For example, to profile PerformanceExample.java, using filters that are defined in the file myFilters.txt, 
>and direct the data from the profiling session to a file called PEProfilingData, type the following on a command line:
><pre> java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml PerformanceExample</pre>
>Note that it is also possible to start WebSphere Application Server (WAS) Version 6 in profiling mode from the command line. To do 
>so, perform the following steps:
><ol>
><li>Go to <tt>&lt;profile root&gt;/config/cells/&lt;nodename&gt;Cell/nodes/&lt;nodename&gt;/servers/server1</tt></li>
><li>Edit the jvmEntries element in the server.xml file. Specifically, append <tt>-XrunpiAgent:server=enabled</tt>
>to the genericJvmArguments attribute value.</li>
><li>Restart WAS.</li>
></ol>
>By augmenting the <tt>-XrunpiAgent</tt> parameter, you can specify several different modes in which to run the 
>profiling agent. The parameter <tt>agent_parm</tt> can take one of the following values: 
>
><ul>
> <li>server=[standalone | enabled | controlled | applicationControlled]
> <dl>
> <dt>standalone</dt>
> <dd>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.</dd>
> <dt>enabled</dt>
> <dd>The Java Profiler is loaded, allows the application to run normally, 
>		but produces no trace until a Eclipse 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.</dd>
> <dt>controlled</dt>
> <dd>The Java Profiler is loaded, and the application is blocked 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.</dd>
> <dt>applicationControlled</dt>
> <dd>Profiling operations are controlled by the TPTP &quot;Profiler&quot; java class. 
>		The pluginconfig.xml file must be modified to use this mode. The 
>		pluginconfig.xml is located in the following directory:
> <pre>&lt;install-dir&gt;/plugins/org.eclipse.tptp.platform.collection.framework_&lt;version&gt;/config/pluginconfig.xml</pre>
>		The following modification is required:
> <pre>&lt;Agent client=&quot;DYNAMIC&quot; configuration=&quot;default&quot; dataChannelSize=&quot;64M&quot; name=&quot;Java Profiling Agent&quot; type=&quot;Profiler&quot;/&gt;</pre>
>		should be modified to
> <pre>&lt;Agent client=&quot;HEADLESS&quot; configuration=&quot;default&quot; dataChannelSize=&quot;64M&quot; name=&quot;Java Profiling Agent&quot; type=&quot;Profiler&quot; logFile=&quot;&lt;some_dir&gt;/profile.trcxml&quot;/&gt;</pre>
>		Note that the Agent client attribute has been changed to &quot;HEADLESS&quot; and 
>		that the &quot;logFile&quot; attribute has been added. 
>		The hcframe.jar file should also be included in the user's class path 
>		when profiling an application under this mode. For example:
> <pre> java -XrunpiAgent:server=applicationControlled -classpath .:&lt;install-dir&gt;/plugins/org.eclipse.tptp.platform.collection.framework_&lt;version&gt;/hcframe.jar TestClass</pre>
> </dd>
> </dl>
> </li>
> <li>filters=filename</li>
></ul>
><blockquote>
><blockquote>
> Note: This parameter is only used when server=standalone is 
>	specified.
></blockquote>
> 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: 
></blockquote>
><pre> &lt;classpattern&gt; &lt;methodpattern&gt; &lt;mode&gt; where: </pre>
><blockquote>
>	<dl>
>		<dt>classpattern</dt>
>		<dd>is a string with no embedded blanks. The string may contain a single 
>		&quot;*&quot; either at the beginning of the string or at the end of the string. 
>		The &quot;*&quot; will match zero or more characters, thus making the pattern a 
>		generic prefix or suffix pattern. A single &quot;*&quot; can also be specified to 
>		represent all strings.</dd>
>		<dt>methodpattern</dt>
>		<dd>is a string with no embedded blanks. The string may contain a single 
>		&quot;*&quot; either at the beginning of the string or at the end of the string. 
>		The &quot;*&quot; will match zero or more characters, thus making the pattern a 
>		generic prefix or suffix pattern. A single &quot;*&quot; can also be specified to 
>		represent all strings.</dd>
>		<dt>mode</dt>
>		<dd>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.</dd>
>	</dl>
></blockquote>
><ul>
> <li>file=filename 
><blockquote>
>	Note: This parameter is only used when server=standalone is 
>	specified.
></blockquote>
>	Specifies the name of a file where the trace will be written. The default is <tt>
>	trace.trcxml</tt> in the current directory.</li>
></ul>
><ul>
> <li>help 
>	Displays a list of available agent options to standard out.</li>
></ul>
><h3><a name="Java_15">Using the Java Profiler with Java 1.5 (or higher) Virtual Machines</a></h3>
>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 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> 
>%JAVA_PROFILER_HOME%:%TPTP_AC_HOME%/lib&nbsp;</li>
>	<li>Execute the Java application with the <samp>-agentlib</samp> parameter as described above. </li>
></ol>
>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.
><h4>Examples</h4>
><ol>
><li>To profile the &quot;HelloWorld&quot; Java application with the CPU Profiler in 
>standalone mode and write the results into log.trcxml: 
><pre><tt>java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld</tt></pre>
></li>
><li>To profile the &quot;HelloWorld&quot; 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: 
><pre><tt>java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld</tt></pre>
></li>
></ol>
><h3><a name="Format_of_the_Class_Filter_file">Format of the Class Filter file</a></h3>
>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.
><h3><a name="Java_Profiling_Agent_Control">Controlling the Java Profiling Agent</a></h3>
>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.
> 
><h3><a name="Notes_about_the_Java_Profiler">Notes about the Java Profiler</a></h3>
><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>
><h2><a name="uninstall">Uninstalling Agent Controller</a></h2>
>To uninstall the agent controller:
><ol>
> <li><a href="#Stop_Agent_Controller">Stop</a> the agent controller: 
> </li>
> <li>Remove the <samp>&lt;install-dir&gt;</samp>.</li>
> <li>Remove the <tt>&lt;install-dir&gt;/bin</tt> directory from the PATH environment 
>	variable, if necessary.</li>
>	<li>Remove the <tt>&lt;install-dir&gt;/lib</tt> directory from the LD_LIBRARY_PATH 
>	environment variable, if necessary. </li>
></ol>
> 
>&nbsp;
> <div class="runningfooter">Copyright (C) 2007 
>	Intel Corporation. 
>	
></div>
></body>
></html>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- 
/**********************************************************************
 * Copyright (c) 2005 - 2007 Intel 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$
 *
 * Contributors:
 * Intel - Initial contribution
 **********************************************************************/  
 -->
  <style type="text/css"></style>
  <meta http-equiv="Content-Type"
 content="text/html; charset=iso-8859-1">
  <style type="text/css"></style>
<title>Getting Started with Agent Controller - Linux</title>
</head>
<body>
<h1><strong>Getting Started with Agent Controller - Linux</strong></h1>
<h3>Contents</h3>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#Overview">Overview</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#Prerequisites">Prerequisites</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Notation">Notation</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Installation">Installing Agent Controller</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#Setting_Up_Agent_Controller">Setting Up Agent Controller</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Configure_Agent_Controller">Configuring Agent Controller</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Start_Agent_Controller">Starting Agent Controller</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Stop_Agent_Controller">Stopping Agent Controller</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#queryversion">Querying Agent Controller version information</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#Checking_Agent_Controller_Installation">Checking Agent Controller Installation</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#serverlog">Server Logging</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#javaprof">Profiling a Java Application</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Invocation_from_the_Eclipse_Workbench">Invocation of the Java Profiler from the Eclipse 
Workbench</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Invocation_of_the_Java_Profiler_from_the_Command_Line">Invocation of 
the Java Profiler from the Command Line</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Java_14">Using the Java Profiler with Java 1.4 (or lower) Virtual Machines</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Java_15">Using the Java Profiler with Java 1.5 (or higher) Virtual Machines</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Format_of_the_Class_Filter_file">Format of the Class Filter File</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Java_Profiling_Agent_Control">Controlling the Java Profiling Agent</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">&nbsp;&nbsp;&nbsp;
<a href="#Notes_about_the_Java_Profiler">Notes about the Java Profiler</a></p>
<p align="left" style="margin-left: 20px; margin-top: 0px; margin-bottom: 0px">
<a href="#uninstall">Uninstalling Agent Controller</a></p>
<h2><a name="Overview">Overview</a></h2>
<p>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. For more information, 
see <a href="../../../../org.eclipse.tptp.platform.agentcontroller.doc.user/concepts/ac/ciacintro.html">Integrated Agent Controller</a>
</p>
<h2><a name="Prerequisites">Prerequisites</a></h2>
<ul>
  <li>Install the Java runtime (JRE) or Java development kit (JDK) 1.5 or 1.4.x<br>
  </li>
  <li>Remove or <a href="#uninstall">uninstall</a> all prior versions of Agent 
	Controller.</li>
  <li>The Agent Controller is compiled using <tt>libstdc++-libc6.2-2.so.3</tt>
shared library.
Ensure that this shared library exists under the <tt>/usr/lib</tt>
directory. If it does not exist, you have to install the
RPM package <tt>compat-libstdc++</tt> that comes with the operating
system installation media.</li>
</ul>
<h3><a name="Notation">Notation</a></h3>
<p>&lt;<tt>install-dir</tt>&gt; = The absolute directory path where the Agent 
Controller has been unzipped.&nbsp; For example: <tt>/opt/tptpAC</tt></p>
<h3><a name="Installation">Installing Agent Controller</a></h3>
<p>Download one of the Linux Agent Controller Runtime packages from the TPTP 
Download page. Install it by simply creating a directory and unzipping the 
package contents into that directory.</p>
<h2><a name="Setting_Up_Agent_Controller">Setting Up Agent Controller</a></h2>
<p>After a normal installation, you still need to configure the Agent Controller 
before you can start it.&nbsp;</p>
<h3><a name="Configure_Agent_Controller">Configuring Agent Controller</a></h3>
<ol>
  <li>Ensure that the files in the <tt>&lt;install-dir&gt;/bin</tt> and <tt>&lt;install-dir&gt;/lib</tt>
directory are executable.</li>
  <li>Run <tt>SetConfig.sh</tt> script from a command shell in the <tt>
	&lt;install-dir&gt;/bin</tt>
	directory to generate the configuration file for the Agent Controller.&nbsp; 
	The script requires that a Java Virtual Machine (JVM) be present in the PATH 
	environment variable.&nbsp; Follow the prompts and enter the required 
	parameters as appropriate.&nbsp; The configuration file <tt>
	&lt;install-dir&gt;/config/serviceconfig.xml</tt>
    will be generated based on your inputs.<br>
  </li>
  <li>Add <tt>&lt;install-dir&gt;/bin</tt> directory to the PATH environment variable.</li>
	<li>Add <tt>&lt;install-dir&gt;/lib</tt> directory to the LD_LIBRARY_PATH 
	environment variable.</li>
</ol>
<p>If you want to make changes to the configuration file that was generated in 
step 1, you may run the <tt>SetConfig.sh</tt> script again or you may manually 
edit the file according to the rules outlined in the document 
<a href="http://help.eclipse.org/help32/topic/org.eclipse.tptp.platform.agentcontroller.doc.user/ref/ac/r_config_ovw.html">
Agent Controller configuration files</a>. The Agent Controller must be restarted 
for the changes to take effect.</p>
<h3><a name="Start_Agent_Controller">Starting Agent Controller</a></h3>
<p>Start the Agent Controller by changing your working directory to&nbsp; <tt>
&lt;install-dir&gt;/bin</tt> and running <tt>ACStart.sh</tt>.</p>
<p><b>Note:</b> The Agent Controller may also be started using <tt>RAStart.sh</tt>, in support of backward compatibility.</p> 
<h3><a name="Stop_Agent_Controller">Stopping Agent Controller</a></h3>
<p>Stop the Agent Controller by changing your working directory to&nbsp; <tt>
&lt;install-dir&gt;/bin</tt> and running <tt>ACStop.sh</tt>.</p>
<p><b>Note:</b> The Agent Controller may also be stopped using <tt>RAStop.sh</tt>, in support of backward compatibility.</p>
  <h2><a name="queryversion"></a>Querying Agent Controller Version Information</h2>
<p>To display the version of Agent Controller, change your working directory to &lt;install-dir&gt;/bin in a command shell and run the following command:</p>
<blockquote>
	<p><tt>ACServer -v</tt><br>&nbsp;&nbsp;&nbsp; or<br><tt>ACServer -version</tt></p>
</blockquote>
<p>The Agent Controller will display its version and terminate.</p>
<p><b>Note:</b> The Agent Controller version may also be queried using <tt>RAServer</tt>, in support of backward compatibility.</p>
<h2><a name="Checking_Agent_Controller_Installation"></a>Checking Agent Controller Installation</h2>

<p>If desired, you can verify proper operation of your Agent Controller 
installation by executing the SampleClient application provided with the runtime 
package.</p>
<p>Perform the following steps:</p>
<ol>
	<li><a href="#Start_Agent_Controller">Start the Agent Controller</a>.</li>
	<li>Open a command prompt 
	window</li>
	<li>Go to the 
	<tt>&lt;install-dir&gt;/bin</tt> 
	directory</li>
	<li>Enter the following at the 
	command prompt:<br><br>&nbsp;&nbsp;&nbsp; <tt>SampleClient</tt><br>&nbsp;</li>
	<li>Observe the console output 
	for SampleClient.&nbsp; It should be similar to the following example:</li>
</ol>
<blockquote>
	<p><tt>------------------- SampleClient Console Output 
--------------------------------<br><br>Connected to the Agent Controller on &quot;localhost&quot; at port number #####<br>
	<br>The Time Collector Agent ID: ###<br><br>Established a data channel with the agent.<br>
	<br>Sending 5 Hello messages over data channel to TimeCollector ...<br><br>Start the TimeCollector ...<br>
	<br>Incoming data: Hello from Time Collector Agent - Count 0<br><br>Incoming data: Hello from Time Collector Agent - Count 1<br>
	<br>Incoming data: Hello from Time Collector Agent - Count 2<br><br>Incoming data: Hello from Time Collector Agent - Count 3<br>
	<br>Incoming data: Hello from Time Collector Agent - Count 4<br><br><br>Stop the TimeCollector ...<br>
	<br>Incoming data: Hello from Time Collector Agent - Count 5<br><br>Incoming data: Hello from Time Collector Agent - Count 6<br>
	<br>Incoming data: Hello from Time Collector Agent - Count 7<br><br>Incoming data: Hello from Time Collector Agent - Count 8<br>
	<br>Incoming data: Hello from Time Collector Agent - Count 9<br><br>Incoming data: Hello from Time Collector Agent - Count 10<br>
	<br>All finished<br>Press any key to exit...</tt></p>
</blockquote>
<p><b>Note:</b>&nbsp; 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.</p>
<p>Refer to the Agent Controller build <tt>
readme.txt</tt> file for detailed information on the SampleClient 
functionality.&nbsp; </p>
<h2><a name="serverlog"></a>Server Logging</h2>
All server log entries will be placed in
<tt>&lt;install-dir&gt;/config/servicelog.log</tt>
.

<h2><a name="javaprof"></a>Profiling a Java Application</h2>
<p>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. <b>The format of this fragment is described in the document titled</b> &quot;<a
 href="http://www.eclipse.org/tptp/platform/documents/resources/profilingspec/XML4Profiling.htm">Event 
Specification for the Java Profiler</a>&quot;.<br>
</p>
<p>You can invoke the Java Profiling Agent from the Eclipse workbench or in standalone mode from the command 
line.<br>
</p>
<h3><a name="Invocation_from_the_Eclipse_Workbench">Invocation of the Java Profiler from the Eclipse Workbench</a></h3>
<p>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.</p>
<p>To launch the Java Profile, from the Profiling and Logging Perspective of the Eclipse workbench use the 
<b>Run &gt; Open Profile Dialog...</b> menu or the <b>Profile</b> toolbar button.&nbsp; The Profile 
wizard will open.&nbsp; Simply follow the wizard to profile an application.&nbsp; 
</p>
<h3><a name="Invocation_of_the_Java_Profiler_from_the_Command_Line">Invocation 
of the Java Profiler from the Command Line</a></h3>
<p>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.</p>
<h3><a name="Java_14">Using the Java Profiler with Java 1.4 (or lower) Virtual Machines</h3>
<p>Use the <tt>-Xrun</tt> Java option to invoke the Java Profiling Agent, as follows:</p>
<pre>    -XrunpiAgent[:agent_parm[,agent_parm]*]<br></pre>
<p>For example, to profile PerformanceExample.java, using filters that are defined in the file myFilters.txt, 
and direct the data from the profiling session to a file called PEProfilingData, type the following on a command line:</p>
<pre>    java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml PerformanceExample</pre>
<p>Note that it is also possible to start WebSphere Application Server (WAS) Version 6 in profiling mode from the command line. To do 
so, perform the following steps:</p>
<ol>
<li>Go to <tt>&lt;profile root&gt;/config/cells/&lt;nodename&gt;Cell/nodes/&lt;nodename&gt;/servers/server1</tt></li>
<li>Edit the jvmEntries element in the server.xml file. Specifically, append <tt>-XrunpiAgent:server=enabled</tt>
to the genericJvmArguments attribute value.</li>
<li>Restart WAS.</li>
</ol>
<p>By augmenting the <tt>-XrunpiAgent</tt> parameter, you can specify several different modes in which to run the 
profiling agent. The parameter <tt>agent_parm</tt> can take one of the following values:</p> 
<p></p>
<ul>
  <li><strong>server=[standalone | enabled | controlled | applicationControlled]</strong>
    <dl>
      <dt><strong>standalone</strong></dt>
      <dd>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.</dd>
      <dt><strong>enabled</strong></dt>
      <dd>The Java Profiler is loaded, allows the application to run normally, 
		but produces no trace until a Eclipse 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.</dd>
      <dt><strong>controlled</strong></dt>
      <dd>The Java Profiler is loaded, and the application is blocked 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.</dd>
      <dt><strong>applicationControlled</strong></dt>
      <dd>Profiling operations are controlled by the TPTP &quot;Profiler&quot; java class. 
		The pluginconfig.xml file must be modified to use this mode. The 
		pluginconfig.xml is located in the following directory:
        <pre>&lt;install-dir&gt;/plugins/org.eclipse.tptp.platform.collection.framework_&lt;version&gt;/config/pluginconfig.xml</pre>
		The following modification is required:
        <pre>&lt;Agent client=&quot;DYNAMIC&quot; configuration=&quot;default&quot; dataChannelSize=&quot;64M&quot; name=&quot;Java Profiling Agent&quot; type=&quot;Profiler&quot;/&gt;</pre>
		should be modified to
        <pre>&lt;Agent client=&quot;HEADLESS&quot; configuration=&quot;default&quot; dataChannelSize=&quot;64M&quot; name=&quot;Java Profiling Agent&quot; type=&quot;Profiler&quot; logFile=&quot;&lt;some_dir&gt;/profile.trcxml&quot;/&gt;</pre>
		Note that the Agent client attribute has been changed to &quot;HEADLESS&quot; and 
		that the &quot;logFile&quot; attribute has been added.<br>
		The hcframe.jar file should also be included in the user's class path 
		when profiling an application under this mode. For example:
        <pre> java -XrunpiAgent:server=applicationControlled -classpath .:&lt;install-dir&gt;/plugins/org.eclipse.tptp.platform.collection.framework_&lt;version&gt;/hcframe.jar TestClass</pre>
      </dd>
    </dl>
  </li>
  <li><strong>filters=filename</strong></li>
</ul>
<blockquote>
<blockquote>
    <p><b>Note</b>: This parameter is only used when server=standalone is 
	specified.</p>
</blockquote>
    <p>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. </p>
	<p>The format of the file is as follows: </p>
</blockquote>
<pre>        &lt;classpattern&gt; &lt;methodpattern&gt; &lt;mode&gt; where:<br></pre>
<blockquote>
	<dl>
		<dt><strong>classpattern</strong></dt>
		<dd>is a string with no embedded blanks. The string may contain a single 
		&quot;*&quot; either at the beginning of the string or at the end of the string. 
		The &quot;*&quot; will match zero or more characters, thus making the pattern a 
		generic prefix or suffix pattern. A single &quot;*&quot; can also be specified to 
		represent all strings.</dd>
		<dt><strong>methodpattern</strong></dt>
		<dd>is a string with no embedded blanks. The string may contain a single 
		&quot;*&quot; either at the beginning of the string or at the end of the string. 
		The &quot;*&quot; will match zero or more characters, thus making the pattern a 
		generic prefix or suffix pattern. A single &quot;*&quot; can also be specified to 
		represent all strings.</dd>
		<dt><strong>mode</strong></dt>
		<dd>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.</dd>
	</dl>
</blockquote>
<ul>
  <li><strong>file=filename</strong><br>
<blockquote>
	<p><b>Note</b>: This parameter is only used when server=standalone is 
	specified.</p>
</blockquote>
	Specifies the name of a file where the trace will be written. The default is <tt>
	trace.trcxml</tt> in the current directory.</li>
</ul>
<ul>
  <li><strong>help</strong><br>
	Displays a list of available agent options to standard out.</li>
</ul>
<h3><a name="Java_15">Using the Java Profiler with Java 1.5 (or higher) Virtual Machines</a></h3>
<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 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> 
<p class="Code">%JAVA_PROFILER_HOME%:%TPTP_AC_HOME%/lib&nbsp;</p></li>
	<li>Execute the Java application with the <samp>-agentlib</samp> parameter as described above. </li>
</ol>
<p><b>Note</b>: 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.</p>
<h4>Examples</h4>
<ol>
<li>To profile the &quot;HelloWorld&quot; Java application with the CPU Profiler in 
standalone mode and write the results into log.trcxml:<br>
<pre><tt>java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld</tt></pre>
</li>
<li>To profile the &quot;HelloWorld&quot; 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:<br>
<pre><tt>java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld</tt></pre>
</li>
</ol>
<h3><a name="Format_of_the_Class_Filter_file">Format of the Class Filter file</a></h3>
<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>
<h3><a name="Java_Profiling_Agent_Control">Controlling the Java Profiling Agent</a></h3>
<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>
 
<h3><a name="Notes_about_the_Java_Profiler">Notes about the Java Profiler</a></h3>
<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>
<h2><a name="uninstall">Uninstalling Agent Controller</a></h2>
<p>To uninstall the agent controller:</p>
<ol>
  <li><a href="#Stop_Agent_Controller">Stop</a> the agent controller: 
    </li>
  <li>Remove the <samp>&lt;install-dir&gt;</samp>.</li>
  <li>Remove the <tt>&lt;install-dir&gt;/bin</tt> directory from the PATH environment 
	variable, if necessary.</li>
	<li>Remove the <tt>&lt;install-dir&gt;/lib</tt> directory from the LD_LIBRARY_PATH 
	environment variable, if necessary.<br></li>
</ol>
 
<p>&nbsp;</p>
 <div class="runningfooter"><p><span style="font-size: 7pt;">Copyright (C) 2007 
	Intel Corporation. </span>
	</p>
</div>
</body>
</html>

Actions: View

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