Profiling an application in stand-alone mode

You can profile an application in stand-alone mode (that is, from the command line), without having the Hyades tools installed. However, you do need to have the Agent Controller installed on the machine where the application to be profiled resides.

You can profile an application in stand-alone mode by invoking the Java Profiling Agent, which is a library that attaches to a Java virtual machine (JVM) to capture and record the behavior of your Java application. The output from the agent is in the form of XML fragments.

Use the -Xrun Java option to invoke the Java Profiling Agent:

    -XrunpiAgent:agent_parm[,agent_parm]*

For example, to profile PerformanceExample.java, using filters that are defined in the file myFilters.txt, and directing the data from the profiling session to a file called PEProfilingData, you would type the following on a command line:
    java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml PerformanceExample

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

• server=[standalone | enabled | controlled | application]
  

  standalone

  The profiling agent runs in a headless mode, which means it is not possible to interact with it from the workbench. Configuration information is provided using configuration files and profiling data is stored in a file directly by the profiling agent. The profiling file can then be imported into the workbench at a later date.
  

  The Java Profiling Agent is manually attached to a JVM instance and generates profiling data to an output file. The default output file is called trace.trcxml, but you can specify a different file name using the file= filename parameter. When this option is selected, the Java Profiling Agent produces an enclosing traceRoot element to form a complete and valid XML document.
  

  enabled (This is the default.)

  The profiling agent runs in the background of the JVM without consuming resources until it is connected to by the workbench and asked to start monitoring. Data is then streamed over the Agent Controller data channel and consumed by the workbench.

  
  That is, the Java Profiling Agent is loaded, allows the application to run normally, but produces no profiling data until a client attaches to the agent to give it instructions. When this option is selected, the Java Profiling Agent produces only XML fragments instead of a complete XML document.
  

  controlled

  The profiling agent preempts the JVM from initialization (the agent is loaded but it blocks the application from running) until it is attached to from the workbench and given instructions to start monitoring by a client. That is, when the profiling agent is launched in controlled mode, it will appear to hang the JVM until asked to start monitoring and it will produce only XML fragments instead of a complete XML document.
  

  application

  The Java Profiling Agent is loaded, runs in the background, and allows the application to run normally as in enabled mode.

  It only produces profiling data when two conditions are satisfied. First, the application must have requested that the profiling agent start profiling using org.eclipse.hyades.collection.profiler.Profiler and second, the test client of the workbench must have attached to the Java Profiling Agent and started monitoring.
  

  Note: All profiling is controlled by the application, using the org.eclipse.hyades.collection.profiler.Profiler class.
  
  

• profile=profile file
  This option is only applicable when server=standalone. This file specifies the options with which you want the profiler to run when in standalone mode. The options specified in this file are usually set in the profiling configurations window when the user launches a Java process from the workbench; the use of this file is an equivalent way of specifying options when running in standalone mode.
  The file can be loaded in one of two ways.

  • Specify the profile=filename option, for example

    -XrunpiAgent:server=standalone,profile=<profile_filename>

  • Name the profile options file jvmpi.pro 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 -XrunpiAgent:server=standalone,profile=./jvmpi.pro as a VM argument.

  See Stand-alone profile filter options for a list of valid options for the profile file.

• filters=filename
  Used only when server=standalone is specified.
  Specifies the name of the file that contains the initial class filter definitions to be used during the  profiling session. The default file name is filters.txt in the current directory. See below for information about the file format.

• file=filename
  Used only when server=standalone is specified.
  Specifies the name of a file that the profiling data will be written to. The default is trace.trcxml in the current directory.

• help
  Displays a list of available agent options to stdout.

 

Format of class filter file

The format of the file is as follows:
   pattern mode

where:

pattern

A string with no imbedded blanks. The string may contain a single asterisk (*) either at the beginning of the string or at the end of the string. 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.

mode

Specifies whether the 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.

 

Java Profiling Agent Control

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

• If you do not specify a filter definition file name on the command line, the Java Profiling Agent tries to read the filters from the file named filters.txt in the current directory. If the file filters.txt does not exist, no filters will be used during the profiling session. If you name your filters file filters.txt and place it in the current directory, you do not need to specify the filters parameter on the command line for your filters to be used by the profiling agent.

• If you do not specify an output file for the profiling data, it will be saved in the file trace.trcxml

• You do not have to specify an extension for the output file. It automatically gets the extension .trcxml

• You do not have to specify the extension for your Java application. It can be a .class file.

Related concepts
Overview of the Profiling Tool
Profiling resources
Profiling monitor view

Related tasks
Profiling an application in standalone mode on AS/400
Launching or attaching a Java process