Getting Started with Agent Controller - Windows

Contents

Overview

Prerequisites

    Notation

    Installing Agent Controller

Setting Up Agent Controller

    Configuring Agent Controller

    Starting Agent Controller

        As an Application

        As a Service

    Stopping Agent Controller

        If an Application

        If a Service

Querying Agent Controller version information

Checking Agent Controller Installation

Server Logging

Profiling a Java Application

    Invocation of the Java Profiler from the Eclipse Workbench

    Invocation of the Java Profiler from the Command Line

    Using the Java Profiler with Java 1.4 (or lower) Virtual Machines

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

    Format of the Class Filter File

    Controlling the Java Profiling Agent

    Notes about the Java Profiler

Uninstalling Agent Controller

Overview

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

Prerequisites

Additional Windows Vista requirements:

Notation

<install-dir> = The absolute directory path where the Agent Controller has been unzipped. For example, C:\tptpAC.
<service_name> = A unique Windows service name.

Installing Agent Controller

Download one of the Windows Agent Controller Runtime packages from the TPTP Downloads area.  (Note: If you installed a 32-bit JRE, the Agent Controller and Java Profiling Agent that you install must also be 32-bit. If you installed a 64-bit JRE, the Agent Controller and Java Profiling Agent that you install must also be 64-bit.)

Complete the installation steps before setting up the Agent Controller.

Setting Up Agent Controller

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

Configuring Agent Controller

  1. Run SetConfig.bat script from a command shell in the <install-dir>\bin directory to generate the configuration file for the Agent Controller.  The script requires that a Java Virtual Machine (JVM) be present in the PATH environment variable.  Follow the prompts and enter the required parameters as appropriate.  The configuration file <install-dir>\config\serviceconfig.xml will be generated based on your inputs.
  2. Add <install-dir>\bin directory to the PATH environment variable when running applications with TPTP agents (such as Profiling or Logging agents) from the command line.

Note: Do not encase the environment variable's value in double quotes even if there are spaces in the <install-dir> path.

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

For guidance on administering the Agent Controller, refer to the Working with the Agent Controller document.

Starting Agent Controller

The Agent Controller can be started as an Application or as a Windows Service.

Note: On Windows Vista systems, you will need to be Administrator to start the ACServer if you require cross-session operation between agents and the Agent Controller. For more information, see Prerequisites

Starting as an Application

Start the Agent Controller by changing your working directory to  <install-dir>\bin and running ACServer.exe.

Note: The Agent Controller may also be started using "RAServer.exe".

Note: If you are running the Agent Controller on Windows Vista and you require cross-session operation between agents and the Agent Controller, you will need to run ACServer as Administrator. There are several ways to do this:

1)     Each time you launch ACServer, right click on the file in the explorer and choose "Run As Administrator".

2)     Each time you launch ACServer, create an administrator command prompt (by right clicking on cmd.exe and choosing "Run As Administrator") and then launch ACServer from that command prompt.

3)     Once only, right click on ACServer and select "Properties".  On the "Compatibility" tab, check the box labeled "Run As Administrator" and click Apply.  All subsequent executions of ACServer (whether launched from a command prompt or from Windows Explorer) will be automatically run as Administrator.

Note: On Windows Vista systems, there are several different options that control the behavior when an application attempts to run at an elevated privilege level.  Depending on how your Windows Vista system is configured, you may 1) be prompted for an administrator username and password, 2) simply be prompted for permission to elevate privileges, or 3) not be prompted at all.  See the Microsoft Windows Vista documentation for more information.

Starting as a Service

  1. Run the <install-dir>\bin\manageservice.exe application to create the Windows service. The syntax is:
    manageservice add "<service_name>" "<install-dir>"

For example:

    manageservice add "Agent Controller"  "C:\tptpAC"

You can now start the server using the Windows' Services panel.


Note: On Windows Vista systems, you will need to be Administrator to start the ACServer if you require cross-session operation between agents and the Agent Controller. To do this, you must run the above command from an administrator command prompt (by right clicking on cmd.exe and selecting "Run As Administrator").

Stopping Agent Controller

If Agent Controller is an Application

Stop the Agent Controller service by terminating the ACServer.exe process (e.g. closing the command shell).  Alternatively you can stop the service by entering:

ACServer -shutdown 

If Agent Controller is a Service

To uninstall the Windows service, stop the server using the Windows' Services panel (or the Windows "net" command) and then run the <install-dir>\bin\manageservice.exe application to delete the Windows' service.
For example:

    	net stop "Agent Controller"
	manageservice remove "Agent Controller"

Querying Agent Controller Version Information

To display the version of Agent Controller, simply type:

ACServer -v
    or
ACServer -version

The Agent Controller will display its version and terminate.

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

Checking Agent Controller Installation

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

Perform the following steps:

  1. Start the Agent Controller. See Starting Agent Controller.
  2. Open a command prompt window
  3. Go to the <install-dir>/bin directory
  4. Enter the following at the command prompt:

        SampleClient
     
  5. Observe the console output for SampleClient.  It should be similar to the following example:

------------------- SampleClient Console Output --------------------------------

Connected to the Agent Controller on "localhost" at port number #####

The Time Collector Agent ID: ###

Established a data channel with the agent.

Sending 5 Hello messages over data channel to TimeCollector ...

Start the TimeCollector ...

Incoming data: Hello from Time Collector Agent - Count 0

Incoming data: Hello from Time Collector Agent - Count 1

Incoming data: Hello from Time Collector Agent - Count 2

Incoming data: Hello from Time Collector Agent - Count 3

Incoming data: Hello from Time Collector Agent - Count 4


Stop the TimeCollector ...

Incoming data: Hello from Time Collector Agent - Count 5

Incoming data: Hello from Time Collector Agent - Count 6

Incoming data: Hello from Time Collector Agent - Count 7

Incoming data: Hello from Time Collector Agent - Count 8

Incoming data: Hello from Time Collector Agent - Count 9

Incoming data: Hello from Time Collector Agent - Count 10

All finished
Press any key to exit...

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

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

Server Logging

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

Profiling a Java Application

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

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

Invocation of the Java Profiler from the Eclipse Workbench

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

To launch the Java Profile, from the Profiling and Logging Perspective of the Eclipse workbench use the Run > Open Profile Dialog... menu or the Profile toolbar button.  The Profile wizard will open.  Simply follow the wizard to profile an application. 

Invocation of the Java Profiler from the Command Line

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

Using the Java Profiler with Java 1.4 (or lower) Virtual Machines

Use the -Xrun Java option to invoke the Java Profiling Agent, as follows:

    -XrunpiAgent[:agent_parm[,agent_parm]*]

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:

    java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml PerformanceExample

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:

  1. Go to <profile root>/config/cells/<nodename>Cell/nodes/<nodename>/servers/server1
  2. Edit the jvmEntries element in the server.xml file. Specifically, append -XrunpiAgent:server=enabled to the genericJvmArguments attribute value.
  3. Restart WAS.

By augmenting the -XrunpiAgent parameter, you can specify several different modes in which to run the profiling agent. The parameter agent_parm can take one of the following values:

Note: This parameter is only used when server=standalone is specified.

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:

        <classpattern> <methodpattern> <mode> where:
classpattern
is a string with no embedded blanks. The string may contain a single "*" either at the beginning of the string or at the end of the string. The "*" will match zero or more characters, thus making the pattern a generic prefix or suffix pattern. A single "*" can also be specified to represent all strings.
methodpattern
is a string with no embedded blanks. The string may contain a single "*" either at the beginning of the string or at the end of the string. The "*" will match zero or more characters, thus making the pattern a generic prefix or suffix pattern. A single "*" can also be specified to represent all strings.
mode
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.

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

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:
<Profiler> is the name of the Profiler Library to load. Some of the available profilers support additional profiler-specific options, as described below:

To run the Java Profiling Agent in standalone mode on Windows, perform the following steps:

  1. Set TPTP_AC_HOME=<<Agent Controller Home>>
  2. Set JAVA_PROFILER_HOME=%TPTP_AC_HOME%\plugins\org.eclipse.tptp.javaprofiler
  3. Set PATH=%JAVA_PROFILER_HOME%;%PATH%;%TPTP_AC_HOME%\bin
  4. Set PATH=%PATH%;%JAVA_HOME%\bin
  5. Execute the Java application with the -agentlib parameter as described above.

Examples

  1. To profile the "HelloWorld" Java application with the CPU Profiler in standalone mode and write the results into log.trcxml:
    java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld
  2. To profile the "HelloWorld" Java application with the Heap Profiler in standalone mode, use the filters defined in myFilter.txt, and collect information about the source locations where objects are allocated:
    java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld

Format of the Class Filter file

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

where:

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

Filter patterns are processed in the order that they are specified until the first pattern match succeeds. If the class name does not match any of the specified filter patterns, the default is to INCLUDE the class.

Controlling the Java Profiling Agent

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

Notes about the Java Profiler

Uninstalling Agent Controller

To uninstall the agent controller:

  1. Stop the Agent Controller. See Stopping Agent Controller.
  2. If the agent controller was installed as a service, run the <install-dir>\bin\manageservice.exe application to delete the Windows' service. For example:
    manageservice remove "Agent Controller"
  3. Remove the <install-dir>.
  4. Remove the <install-dir>\bin directory from the PATH environment variable, if necessary.

Copyright (C) 2006, 2008 Intel Corporation.