JPROF ( Java Profiler ) Version 8.6.3

General Information:

Overview

Quick Start

Using JPROF:

Invocation Options

Metric Selection Options

Runtime Control

Additional Information:

Files Produced by JPROF

Overview

JPROF is a Java profiling agent that responds to events from either the JVM Profiler Interface (JVMPI) or the JVM Tool Interface (JVMTI), based on the invocation options. On Linux, the profiling agent is named libjprof.so. JPROF is installed using the tinstall.appl command.

Common usages of JPROF are:

• Resolving JIT Addresses to Names (JITA2N) to support TPROF and ITRACE post processing.
• Capturing the state of the Java Heap that can later be post processed by HDUMP .
• Capturing information about JVM usage of locks via the Java Lock Monitor (JLM).

JPROF functions are controlled by Java Invocation Parameters and by RTDRIVER commands from a command line or from Java.

JPROF causes significant application slowdown due to additional execution pathlength in the JVM, JIT, and JPROF due to instrumentation, the overhead associated with generating and handling the events used while profiling the application. This can be on the order of 1.5 to 10 times the original pathlength.

Quick Start

A few quick examples of how to use JPROF are listed below:

• To resolve JIT Addresses to Names for TPROF (with run.tprof) using JVMPI use:

  java -Xrunjprof:tprof classfile

  or for JVMTI use:

  java -agentlib:jprof=tprof classfile

  This data is post-processed using:

  post

  together with swtrace.nrm2, to produce tprof.out.

• To capture execution flow in the generic format using instruction completed on thread as the metric for JVMPI use:

  java -Xrunjprof:generic classfile

  or for JVMTI use:

  java -agentlib:jprof=generic classfile

  To use cycles on thread as the metric use:

  java -Xrunjprof:generic,ptt_cycles classfile

Invocation Options

JPROF options are specified as a parameter on the Java command line or via the environment variable IBM_JAVA_OPTIONS or JAVA_OPTIONS. This parameter is of the form -Xrunjprof:list when using JVMPI or -agentlib:jprof=list when using JVMTI. The list of options is case-insensitive and comma delimited.

Additional options can be appended to this list by using the JPROFOPTS environment variable. This environment variable makes it easy to temporarily add options to JPROF without having to modify existing scripts.

To setup Websphere java options use the JAVA_OPTIONS or IBM_JAVA_OPTIONS environment variable.

The parameter parser supports up to five ways to specify each option. For example, pidx, the option that adds the process id as a suffix to all file names, can be specified as pidx, +pidx, allpidx, -pidx, or nopidx. "all" is an alias for "+" and "no" is an alias for "-" to make the options as readable as possible.

Many options also have aliases, such as enableheapdump and its alias, ehd.

The most important two options are help and allhelp, since they are used to display the help information built into JPROF itself. help displays information about only the most commonly used options. allhelp displays information about all options, including debugging options and those that may be obsolete or are deprecated.

Since the help information is integrated into the option parser, the help and allhelp options produce the most accurate documentation available for JPROF. This is a link to the help output from version 8.6.3.

Metric Selection Options

Metric selection can be critical when using JPROF, because different types of profiling require the use of different metrics. For example, analysis of execution path length requires instructions as a metric, while analysis of latency requires both wallclock time and cycles on thread.

There are three kinds of metrics: physical, logical, and composite. Physical metrics define what data is gathered, while logical metrics define what data is displayed. Composite metrics are logical metrics which depend on multiple physical metrics.

ptt_insts

Selects instructions completed on the thread as a physical metric. This is the default when generic or gencalib is specified

ptt_cycles

Selects cycles executed on the thread as a physical metric.

raw_cycles

Selects cycles executed on any thread as a physical metric. This is sometimes known as wallclock time. This metric is always implicitly selected to support timestamps, unless nometrics is specified.

nometrics

Selects a special metric that does not reference any physical metrics. This metric is simply a count of metric references on the thread and can be used to support basic call flow analysis in situations where physical metrics can not be used, like SMP systems where no device driver is installed.

Default metrics can be overridden using the metrics=metricname option, using any of the metric names above.

All metrics can use :n as a suffix to shift out the last n decimal digits. All metrics ending with _cycles can be scaled to seconds, milliseconds, microseconds, or nanoseconds using :sec, :msec, :usec, or :nsec.

Runtime Control

RTDRIVER commands from a command line

1. General

   RTDRIVER is a socket-based command-line application that connects to JPROF to allow starting and stopping of tracing at runtime. This allows large, long running applications to run at full speed until they arrive at the point where you wish to analyze them.

2. Starting RTDRIVER

   RTDRIVER is a client-side socket connection. Since JPROF always opens a socket connection for commands, RTDRIVER connects to JPROF and presents the user with a command line. The simplest case with client and server on the same machine is shown below:

   1. rtdriver -l (local machine as host)

   2. When RTDRIVER connects to the host socket a command prompt will appear. The complete list of supported interactive commands is listed below. RTDRIVER supports some abbreviations for convenience. See rtdriver-usage (interactive commands).
3. Rtdriver Commands

   Rtdriver commands supported in jprof are listed below. These commands can be issued via the rtdriver application or the RtDriver.class.

   Multiple commands can be separated by commas, such as fgc,hd to force garbage collection and immediately perform a heapdump.

   start[=n]

   Begins collecting data. Optional n second delay.

   shutdown

   Produces final file and kills the process

   off

   Permanently disables all events to allow JVM to return to full speed. This command is DEPRECATED.

   fgc

   Force Garbage Collection.

   jlmstart[=n]

   Start Java Lock Monitor with hold time accounting. Optional n sec delay.

   jlmstartlite[=n]

   Start Java Lock Monitor hold without time accounting. Optional n sec delay.

   jlmreset

   Stop Java Lock Monitor and restart in previous mode (default to time)

   jlmdump

   Request Java Lock Monitor dump (creates log-jlm.n_pid file)

   jlmstop

   Stop Java Lock Monitoring

   hd or heapdump=2

   request a detailed heap dump (log-hd.n_pid and log-hdcnm.n_pid files)
   

   hds or heapdump=1

   request a heap class summary only (log-hdcnm.n_pid file)

   thread_dump

   Signal for a java coredump (includes thread stack dump)

In addition to the RTDRIVER commands described above, you can also control JPROF using APIs in RtDriver.class. The methods in RtDriver.class are static, so you do not need to instantiate the class.

The RtDriver.command method allows you to send any valid RTDRIVER command to the copy of JPROF that was loaded by your JVM.

public static void command(String cmd)

To send the start command, followed by the hd command, simply add these statements to your java program:

import jperf.RtDriver;
...
RtDriver.command("start");
RtDriver.command("hd");

Some command abbreviations are implemented only in RTDRIVER and not in RtDriver.class. Over time, these abbreviations will be moved to JPROF and eliminated from RTDRIVER, making both command sets the same.

Controlling Java Compilation

• IBM SOV JVM

  • Compiling control. The java JIT compiler compiles methods based on a variety of criteria. One criteria is the number of times the method has been called. To control this feature use the following environment variable :
    IBM_MIXED_MODE_THRESHOLD=n

    This will cause "jitting" after n calls.

  • Inlining control. By default the java JIT compiler will at times inline methods in order to increase performance. For code flow analysis it may by useful to disable that function. The following JAVA environment variable does this :
    JITC_COMPILEOPT=NINLINING

• IBM J9 JVM

  • Compiling is controlled by the count= JIT option, as shown below:
    -Xjit:count=n

    This will cause "jitting" after n calls.

  • Inlining is controlled by the disableInlining JIT option, as shown below:
    -Xjit:disableInlining

  • You specify -Xjit:options as a command line parameter when invoking Java. For example, to specify both of these options when executing your classfile, you could invoke Java with the following command:
    java -Xjit:disableInlining,count=n classfile

Files Produced by JPROF

The logpath=path option can be used to select a different directory, while the logprefix=prefix option will change the prefix used to create the filenames. For example, if logpath=abc,logprefix=def is specified, then log-msg would be replaced by abc/def-msg.

Unless you specify nopidx, all of the files will use a _PID extension, such as log-msg_1234 for process 1234.

The types of files produced by JPROF and their contents are:

log-msg

All messages generated by JPROF. This is always produced.

log-gen

The call tree of methods in generic form. This is produced in GENERIC mode.

log-hd

The raw data from a heapdump. This is produced whenever a heapdump command is received or at JVM termination when the hd option is used with JVMTI. This file is post-processed by HDUMP.

log-hdcnm

A summary of the heapdump by class name. This is produced whenever any heapdump command is received or at JVM termination when the hd option is used with JVMTI.

log-jita2n

Address-to-Name translations for all Jitted methods, plus bytes of instructions if the jinsts option is specified. This is produced in tprof and itrace modes or when jita2n is specified. This file is used by post when post-processing .nrm2 files and other trace files.

log-jitinfo

JIT related output. This is produced in tprof and itrace modes when the jitinfo option is specified.

log-jtnm

Thread start and stop information, by name. This is produced in tprof and itrace modes or when the threadinfo option is specified.

log-out

Various internal debugging information. This is produced only in OUTPUT mode.

log-vt

VTUNE related output. This is produced only in VTUNE mode.