Migration Guide

Profiling and Debugging with WebLogic JRockit

WebLogic JRockit SDK includes the JVM profiling interface (JVMPI) and JVM debugging interface (JVMDI), interfaces that 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 debgging tools they select for the applications they are running.

This section includes information on the following subjects:

Profiling WebLogic JRockit

You can use any number of third-party profiling tools to profile WebLogic 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 WebLogic JRockit SDK.

Warning: This interface is an experimental feature in the Java 2 SDK 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.

Limitations

JVMPI has the following limitations:

The current version of JVMPI supports only one agent per VM.
You can profile with JVMPI only if you use a generational copy garbage collector (-Xgc:gencopy), unless you set the -Xjvmpi:allocs=off flag. In that case, you can use any garbage collector.

Changing the JVMPI Default Behavior

Use the following option to modify the JVMPI default behavior:

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

When WebLogic 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/products/jdk/1.2/docs/guide/jvmpi/

Debugging with WebLogic JRockit

This section describes the interface by which debugging tools can interface with WebLogic 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 WebLogic 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