4 Profiling With NetBeans and jvmtihprof

This chapter describes two options for profiling application performance and memory usage.

This chapter includes these topics:

Section 4.1, "Introduction"
Section 4.2, "Remote Profiling with the NetBeans IDE"
Section 4.3, "Simple Local Profiling with jvmtihprof"

4.1 Introduction

Profiling is the acquisition of runtime performance data for an application on a target runtime system. Understanding the runtime behavior of an application allows the developer to identify performance-sensitive components when tuning an application's implementation or selecting runtime features. cvm profiling provides reports that include CPU usage, heap allocation statistics, and monitor contention profiles. For more information, see http://java.sun.com/developer/technicalArticles/Programming/HPROF.html

4.2 Remote Profiling with the NetBeans IDE

This section describes how to profile remotely with the NetBeans IDE. The steps are:

Calibrate the Profiler Agent (a one-time operation)
Start cvm with the Profiler Agent
Attach the NetBeans Profiler

Before you begin, ensure that the project's compiled class files are accessible to the target host and correspond to source files loaded in the IDE. Also be sure that the profiler agent native classes are accessible on the target host. For platforms directly supported by CDC (see the Build Guide), the build creates the profiler agent as a .so or .dll library called profiler interface. For platforms that use a CDC port, the details of the profiler agent are platform-specific.

Note:

This section covers only the basics of remote profiling. Read the NetBeans online help if you need more information on the subject.

4.2.1 Calibrate the Profiler Agent

On the target host, calibrate the profiler agent by issuing commands equivalent to those shown in Example 4-1.

Calibration measures the profiler agent overhead so it can be subtracted out of measurements obtained in a profiler run. To run the NetBeans calibrator, the target host must have access to the files jfluid-server.jar and jfluid-server-cvm.jar. These are NetBeans libraries modified for CDC so they consume less target device file system space. The location of these files is target host-dependent.

Example 4-1 Calibrating the Profiler

% set CVM_HOME=yourCVM
% $CVM_HOME/bin/cvm \
-classpath $CVM_HOME/lib/profiler/lib/jfluid-server.jar:\
$CVM_HOME/lib/profiler/lib/jfluid-server-cvm.jar \
-Djava.library.path=$CVM_HOME/bin \
org.netbeans.lib.profiler.server.ProfilerCalibrator
Profiler Agent: JNI On Load Initializing...
Profiler Agent: JNI OnLoad Initialized successfully
Starting calibration...
Calibration performed successfully
For your reference, obtained results are as follows:
Approximate time in one methodEntry()/methodExit() call pair:
When getting absolute timestamp only: 3.085 microseconds
When getting thread CPU timestamp only: 3.1022 microseconds
When getting both timestamps: 5.2254 microseconds

Approximate time in one methodEntry()/methodExit() call pair
in sampled instrumentation mode: 0.7299 microseconds

4.2.2 Start `cvm` with the Profiler Agent

Launch cvm with the profiler agent using a command equivalent to that shown in Example 4-2 for a Linux target host.

Example 4-2 Launching cvm with the Profiler Agent

% set CVM_HOME=yourCVM
% $CVM_HOME/bin/cvm -Xmx32M -agentpath:profilerInstallDir/lib/deployed/cvm/linux/libprofilerinterface.so=profilerInstallDir/lib,5140 -cp /home/mydir/myclasses.zip helloworld.HelloWorld
Profiler Agent: Initializing...
Profiler Agent: Options: >profilerInstallDir/lib,5140<
Profiler Agent: Initialized successfully
Profiler Agent: Waiting for connection on port 5140 (Protocol version: 9)

5140 is the default NetBeans profiler port, which you can change in NetBeans Tools > Options > Miscellaneous > Profiler.

libprofilerinterface.so is a shared native code library. Building CDC creates this file.

4.2.3 Attach the NetBeans Profiler

Load the project to be profiled, and choose Profile > Attach Profiler.

The Attach Profiler dialog appears, similar to Figure 4-1.

Figure 4-1 Attach Profiler Dialog

Description of "Figure 4-1 Attach Profiler Dialog"
Near the bottom of the dialog, click define.

The Select Target Type screen appears, similar to Figure 4-2.

Figure 4-2 Select Target Type Screen

Description of "Figure 4-2 Select Target Type Screen "
Set the values as follows, then click Next>:
- Target Type: Application
- Attach method: Remote
- Attach invocation: Direct
The Remote System screen appears, similar to Figure 4-3.

Figure 4-3 Remote System Screen

Description of "Figure 4-3 Remote System Screen"
Enter the target host's name or IP address, select its operating system and Java virtual machine from the drop-down, then click Next>.

The Review Attach Settings screen appears, similar to Figure 4-4.

Figure 4-4 Review Attach Settings Screen

Description of "Figure 4-4 Review Attach Settings Screen"
Verify that the settings are correct, then click Next>.

The Manual Integration screen appears, similar to Figure 4-5.

Figure 4-5 Manual Integration Screen

Description of "Figure 4-5 Manual Integration Screen"
In the Manual Integration screen, click Finish.
In the Attach Profiler dialog click Attach.

Profiling results begin to appear, for example, the heap profile shown in Figure 4-6.

Figure 4-6 Sample Profile Results

Description of "Figure 4-6 Sample Profile Results"

Subsequent profiling runs are simpler because the NetBeans IDE remembers settings:

On the target host, start the application with the -agentpath option shown in Example 4-2.
In the NetBeans IDE, choose Profile > Attach Profiler.
In the Attach Profile dialog, click Attach.

4.3 Simple Local Profiling with `jvmtihprof`

Example 4-3 is a simple profiling example that creates a file of profiling data for a HelloWorld application.

Example 4-3 Using jvmtihprof

% cvm -agentlib:jvmtihprof -Xbootclasspath/a:./lib/mysamples.jar -classpath /home/mydir/myclasses.zip HelloWorld
Hello world.
Dumping Java heap ... allocation sites ... done.

The -Xbootclasspath option specifies the location of mysamples.jar, which is required for profiling. In this example, no output file name is given, so the profile data is in the default file java.hprof.txt.

The -agentlib:jvmtihprof option controls profiling features. For example:

% cvm -agentlib:jvmtihprof=heap=all,cpu=samples,file=profile.txt ...

Table 4-1 lists the profiling options.

Table 4-1 Profiling Command-Line Options

Option	Default	Description
-agentlib:jmvtihprof[=option=value, ...]		Run the VM with profiling enabled using options specified
heap=dump\|sites\|all	all	Heap profiling
cpu=samples\|times\|old	off	CPU usage
monitor=y\|n	n	Monitor contention
format=a\|b	a	ASCII or binary output
file=name	java.hprof.txt	Write data to file name and append `.txt` for ASCII format
net=host`:`port	(off)	Send data over a socket
depth=size	4	Stack trace depth
cutoff=value	0.0001	Output cutoff point
lineno=y\|n	y	Display line numbers in traces
thread=y\|n	n	Thread in trace
doe=y\|n	y	Dump on exit