Skip navigation.
Downloads | Product Documentation | Support

Developing Java Applications

# Profiling and Debugging with BEA JRockit

BEA JRockit SDK includes the JVM profiling interface (JVMPI) and JVM debugging interface (JVMDI) which enable Java applications to interact with the JVM to assist with profiling and debugging activities. While developers will need to implement these interfaces within their application code, users' exposure to JVMPI and JVMDI will usually be through the profiling and debugging tools they select for the applications they are running.

This section includes information on the following subjects:

- Profiling BEA JRockit
- Profiling with the HPROF Profiling Agent

# Profiling BEA JRockit

You can use any number of third-party profiling tools to profile BEA JRockit performance. This section describes how to use the Java Virtual Machine Profiler Interface (JVMPI) to facilitate using those tools.

## Using JVMPI

The JVM Profiler Interface allows you to use third-party profiling tools with BEA JRockit SDK.

Warning: This interface is an experimental feature in the Java 2 JDK and is not yet a standard profiling interface.

### How JVMPI Works

JVMPI is a two-way function call interface between the Java virtual machine and an in-process profiler agent. On one hand, the VM notifies the profiler agent of various events, corresponding to, for example, heap allocation, thread start, and so on. Concurrently, the profiler agent issues controls and requests for more information through the JVMPI. For example, the profiler agent can turn on/off a specific event notification, based on the needs of the profiler front-end.

The profiler front-end may or may not run in the same process as the profiler agent. It may reside in a different process on the same machine, or on a remote machine connected via the network. The JVMPI does not specify a standard wire protocol. Tools vendors may design wire protocols suitable for the needs of different profiler front-ends.

A profiling tool based on JVMPI can obtain a variety of information such as heavy memory allocation sites, CPU usage hot-spots, unnecessary object retention, and monitor contention, for a comprehensive performance analysis.

JVMPI supports partial profiling; that is, a user can selectively profile an application for certain subsets of the time the VM is up and can also choose to obtain only certain types of profiling information.

Note: JVMPI supports only one agent per VM.

### Changing the JVMPI Default Behavior

Use the following option to modify the JVMPI default behavior:

>     -Xjvmpi [:<argument1>=<value1>[,<argumentN>=<valueN>]]

When BEA JRockit runs with a profiling agent attached, by default a number of events are enabled that can create significant overhead. Since JVMPI doesn't require all of these events to be sent, you can disable them by setting the `-Xjvmpi` flag. Use the arguments listed in Table 4-1 to modify the default behavior.:

Table 4-1 Command Line Arguments for `-Xjvmpi`

Argument | Description
--- | ---
`entryexit=off|on` (default `on`) | Setting this to `off` disables the following method entry and exit events sent by JVMPI: `JVMPI_EVENT_METHOD_ENTRY` `JVMPI_EVENT_METHOD_ENTRY2` `JVMPI_EVENT_METHOD_EXIT`
`allocs=off|on` (default `on`) | Setting this to `off` disables these object allocation and free events: `JVMPI_EVENT_OBJECT_ALLOC` `JVMPI_EVENT_OBJECT_MOVE` `JVMPI_EVENT_OBJECT_FREE` `JVMPI_EVENT_ARENA_NEW` `JVMPI_EVENT_ARENA_DELETE`
`monitors=off|on` (default `on`) | Setting this to `off` disables these monitor contention events: `JVMPI_EVENT_RAW_MONITOR_CONTENDED_ENTER` `JVMPI_EVENT_RAW_MONITOR_CONTENDED_ENTERED` `JVMPI_EVENT_RAW_MONITOR_CONTENDED_EXIT` `JVMPI_EVENT_MONITOR_CONTENDED_ENTER` `JVMPI_EVENT_MONITOR_CONTENDED_ENTERED` `JVMPI_EVENT_MONITOR_CONTENDED_EXIT` `JVMPI_EVENT_MONITOR_WAIT` `JVMPI_EVENT_MONITOR_WAITED`
`arenadelete=off|on` (default `off`) | Setting this to `on` will enable the `JVMPI_EVENT_ARENA_DELETE` event. This event is suppressed by default to be compatible with Sun's VM which does not send this event. The event can be enabled if a profiler wishes to receive the event.

### Additional JVMPI Documentation

As JVMPI is an experimental interface, Sun Microsystems provides the documentation for tools vendors who have an immediate need for profiling hooks in the Java VM. You can find this documentation at:

http://java.sun.com/j2se/1.5.0/docs/guide/jvmpi/index.html

## Profiling with the HPROF Profiling Agent

An ancillary component to JVMPI is the HPROF profiling agent, which is shipped with the Java 2 JDK. HPROF is a dynamically-linked library that interacts with the JVMPI and writes profiling information either to a file or to a socket. You can then process that information by using a profiler front-end tool.

HPROF displays such information as CPU usage, heap allocation statistics, and monitor contention profiles. It can also report complete heap dumps and states of all the monitors and threads in BEA JRockit.

To run HPROF, use the `-Xrunhprof` command at startup; for example:

>     java -Xrunhprof ClassToProfile

Depending on the type of profiling requested, HPROF instructs the virtual machine to send it the relevant JVMPI events and processes the event data into profiling information. For example, the following command obtains the heap allocation profile:

>     java -Xrunhprof:heap=sites ToBeProfiledClass

### HPROF Documentation

HPROF is distributed as part of the J2SE JDK. You can find complete documentation for this feature at:

>     http://java.sun.com/j2se/1.5.0/docs/guide/jvmpi/jvmpi.html#hprof

# Debugging with BEA JRockit

This section describes the interface by which debugging tools can interface with BEA JRockit to debug Java applications.

## Java Virtual Machine Debugger Interface (JVMDI)

JVMDI is a low-level debugging interface used by debuggers and other programming tools. It allows you to inspect the state and to control the execution of applications running in the BEA JRockit JVM.

JVMDI describes the functionality a JVM provides to enable debugging of Java applications running within the JVM. JVMDI defines the services a JVM must provide for debugging. JVMDI services include requests for information (for example, current stack frame), actions (set a breakpoint), and notification (when a breakpoint has been hit).

## How JVMDI Works

JVMDI is a two-way interface:

- The JVMDI client can be notified of interesting occurrences through events.
- The JVMDI can query and control the application through many different functions, either in response to events or independent of them.

JVMDI clients run in the same VM as the application being debugged and access JVMDI through a native interface. The native, in-process interface allows maximum control with minimal intrusion of a debugging tool. Typically, JVMDI clients are relatively compact. They can be controlled by a separate process that implements the bulk of a debugger's functionality without interfering with the target application's normal execution.

## JVMDI Documentation

Sun Microsystems provides complete reference documentation for the Java Platform Debug Architecture and JVMDI. For more information, go to:

http://java.sun.com/j2se/1.4.1/docs/guide/jpda/index.html