Contents:

• Profiling for the First Time
  • Creating the Sample Project
  • Using the Profiler for the First Time
  • Profiling a Project for the First Time
• Selecting a Profiling Task
  • Monitoring an Application
  • Analyzing Application Performance
  • Analyzing Memory Usage
• Taking Snapshots
  • Taking and Comparing Memory Snapshots

Prerequisites

This document assumes you have some basic knowledge of, or programming experience with, the following technologies:

• Java Programming
• NetBeans IDE

Software Needed for the Tutorial

For this tutorial you need to have the following software installed on your computer:

Software or Resource	Version Required
NetBeans IDE	version 6.1 or version 6.0
Java Developer Kit (JDK)	version 6 or version 5

The profiling tool is bundled with NetBeans IDE, and no special setup is necessary in order to begin profiling an application.

Creating the Sample Project

In this document you will profile the Anagram Game sample application. To do this you will first use the New Project wizard to to create the sample application.

To create the Anagram Game application, do the following steps:

1. Choose File > New Project from the main menu.
2. In the New Projects wizard, select the Samples > Java category.
3. Select the Anagram Game project.
4. Specify a location for the project and make sure the Set as Main Project property is selected. Click Save.

When you click Finish, the IDE creates the Anagram Game sample project. You can see that the Anagram Game project is visible in the Projects window and that name is in bold indicating that it is set as the main project. By default, when using the IDE to profile a project, the IDE will profile the main project.

Using the Profiler for the First Time

To achieve accurate profiling results, you must have calibration data for each Java platform that will be used for profiling. If you are running the profiling tool for the first time, or if valid calibration data is unavailable for the Java platform, you are prompted to run the calibration process for your platform.

The calibration only needs to be performed once. However, if you make any substantial changes to the configuration of the machine that could affect machine performance, you should run the calibration again. You can run the calibration at any time by performing the following steps:

1. Choose Profiler > Advanced Commands > Run Profiler Calibration.
2. Select the Java Platform. Click OK.

When the calibration operation is complete, a dialog box appears with information about the calibration results. The calibration data for each Java platform is saved in the .nbprofile directory in your home directory.

Profiling a Project for the First Time

The first time you profile a project, you will see a dialog box informing you that the IDE needs to integrate the profiling tool with the target project. To integrate with the project, the IDE modifies the build script of your project to import an additional build script for the required profiling libraries. Before modifying the build scipt, the IDE creates a backup of the original build script.

To integrate the profiling tool with the project, click OK in the dialog box. The IDE creates a backup of build.xml named build-before-profiler.xml and adds the following line to build.xml:

<import file="nbproject/profiler-build-impl.xml"/>

You can restore the original build script by choosing Profiler > Advanced Commands > Unintegrate from the main menu.

Monitoring an Application

When you choose the Monitor task, the target application is started without any instrumentation. When monitoring an application, you obtain high-level information about several important properties of the target JVM. Because monitoring an application imposes very low overhead, you can run the application in this mode for extended periods of time.

To monitor the Anagram Game application, do the following:

1. Make sure that AnagramGame is set as the main project.
2. Choose Profile > Profile Main Project from the main menu.
3. Select Monitor in the Select Profiling Task dialog box.
4. Click Run.
   

When you click Run, the IDE launches the application and the Profiler window opens in the left pane of the IDE. The Profiler window contains the controls that enable you to do the following:

• Control the profiling task
• See the status of the current profiling task
• Display profiling results
• Manage profiling results snapshots
• See basic telemetry statistics

You can use the controls in the Profiler window or the main menu to open the windows where you can view the monitoring data. You can use the Telemetry Overview window to quickly get an overview of the monitoring data in real time.

• Choose Window > Profiling > Telemetry Overview to open the overview in the Output window.
  You can open the Telemetry Overview window and see monitoring data at any time during any profiling session.

The Telemetry Overview enables use to quickly see the status of your application. If you place the cursor over a graph, you can see more detailed statistics about the data displayed in the graph. You can double-click on any of the graphs in the Telemetry Overview window to open a larger and more detailed version of the graph.

Analyzing CPU Performance

When you choose the CPU task, the IDE profiles the method-level CPU performance (execution time) of your application and processes the results in real-time. You can choose to analyze the performance of the entire application or limit the profiling to a part of the application code, even down to a specific code fragment.

To analyze CPU performance, you choose how much of the application you want to profile by selecting one of the following options:

• Entire Application. In this mode, all of the methods of the profiled application are instrumented. The IDE records when threads enter and exit project methods enabling you to see how much time is spent in each method.
• Part of Application. In this mode, you can instrument and profile a limited subset of the application's code. This can greatly reduce the profiling overhead.

  To profile part of an application, you first need to specify one or more root methods. A root method is the method, class or package in your source code that you specify as an instrumentation root. Profiling data is collected when one of the application's threads enters and leaves the instrumentation root. No profiling data is collected until one of the application's threads enters the root method.

  Note: For some programs this option may be the only way to obtain any detailed and/or realistic performance data because profiling the entire application may generate so much profiling data that the application becomes unusable or may even cause crash.

You can also further fine tune how much code is profiled by using a filter to limit the sources that are instrumented.

You will now use the IDE to analyze the CPU performance of the Anagram Game application. You will choose the Part of Application option and then select WordLibrary.java as the profiling root. By selecting this class as our profiling root, you limit the profiling to the methods in this class.

1. Stop the previous profiling session (if still running) by clicking the Stop button in the Profiler window.
2. Choose Profile > Profile Main Project from the main menu.
3. Select CPU in the Select Profiling Task dialog box.
4. Select Part of Application.
   To use this option you also need to specify a profiling root method.
5. Click define to open the Specify Root Methods dialog box.
6. Click Add From Project to open the Select Root Methods dialog box.
7. In the Select Root Methods dialog box, expand the AnagramGame node and select Sources/com/toy/anagrams/lib/WordLibrary. Click OK.
   
8. Click OK in the Specify Root Methods dialog box.
   You can see that WordLibrary is listed as our root method.
   In the Select Profiling Task you can see that one root method is specified as the profiling root. When profiling a project you can specify multiple root methods. You can also click edit to modify the selected root method.
9. Select Profile only project classes for the Filter value.
   The filter enables you to limit the classes that are instrumented, in this case to the classes that are found in the project. You can click Show filter value to see a list of the filtered classes. You can choose from the IDE's predefined profiling filters or create your own custom filters.
   
10. Click Run in the Select Profiling Task dialog box.

When you click Run, the IDE launches the application and starts the profiling session. To view the profiling results, click Live Results in the Profiler window to open the Live Profiling Results window. The Live Profiling Results window displays the profiling data collected thus far. The data displayed is refreshed every few seconds by default. When analyzing CPU performance, the Live Profiling Results window displays information on the time spent in each method and the number of invocations of each method. You can see that in our Anagram Game application only two methods are invoked initially.

If you try to solve some of the anagrams in the Anagram Game, you can see that the IDE displays the other methods that our actions are invoking and how much time the application is spending in each of them.

You can quickly navigate to the source code containing any of the listed methods by right-clicking the name of the method and choosing Go To Source. When you click Go To Source the class opens in the Source editor.

Analyzing Memory Usage

The Analyze Memory Usage task gives you data on objects that have been allocated in the target application such as the number, type and location of the allocated objects.

To analyze memory performance, you choose how much data you want to obtain by selecting one of the following options:

• Record object creation only. When this option is selected, all classes currently loaded by the target JVM (and each new class as it is loaded) are instrumented to produce information about object allocations.
• Record both object creation and garbage collection. When selected, profiling the application gives you information on object liveness such as about how many objects of each type are still alive, their size and average age, as well as allocation data.

The first option is functional subset of the second and has a smaller performance and memory overhead. The Overhead meter in the Select Profiling Tasks window gives a rough approximation of the increase or decrease in profiling overhead according to the profiling options you select.

We will now use the IDE to analyze the memory performance of the Anagram Game application. You will choose the Record both object creation and garbage collection option. You will also select the Record stack traces for allocation so that the IDE records the full call stack. By selecting this option, when you take the memory snapshot you will be able to view the reverse call tree for method calls that allocated objects.

1. Stop the previous profiling session (if still running) by clicking the Stop button in the Profiler window.
   When you click Stop, the Anagram Game application will also stop.
2. Choose Profile > Profile Main Project from the main menu.
3. Select Memory in the Select Profiling Task dialog box.
4. Select Record both object creation and garbage collection.
5. Leave the Track every N object allocations at the default value of 10.

   This option sets the interval /proportion for stack sampling. By setting the value 10, this means that for each class only every 10th object allocation will be recorded completely. To record all information for each object, you can set the value to 1. However this will substantially increase the profiling overhead.

6. Select Record stack traces for allocation.
   Notice that when you selected this option the Overhead meter increased substantially, but our application is small enough that the performance hit should be manageable.
   
7. Click Run.

When you click Run, the IDE launches the application and starts the profiling session. To view the profiling results, click Live Results in the Profiler window to open the Live Profiling Results window. The Live Profiling Results window displays information on the size and number of objects that are allocated in our project.

By default the results are sorted and displayed by the number of Live Bytes, but you can click a column header to change how the results are displayed. You can also filter the results by typing a class name in the filter box below the list.

Taking and Comparing Memory Snapshots

For our Anagram Game application, we want to take a snapshot of our results and see the allocation stack trace for the objects of type String. We then want to take a second snapshot and compare the two. If a memory snapshot is open, you can compare it to comparable memory snapshots in your project or that are saved elsewhere on your system.

1. Make sure the profiling session is still running.
   (If you stopped the profiling session, repeat the steps to analyze memory performance and open the Live Profiling Results window.)
2. Right-click on the line containing java.lang.String in the Profiling Results window and choose Take Snapshot and Show Allocation Stack Traces.
   The IDE takes the memory snapshot and opens the snapshot to the Allocation Stack Traces tab where you can explore the reverse call tree for methods that instantiated this object.
   
3. Click the Save Snapshot to Project button in the snapshot toolbar (or Ctrl+S) to save the memory snapshot to your project. When you save the snapshot to your project, the snapshot is added to the list of Anagram Game's saved snapshots in the Profiler window. By default, snapshots are physically saved in the nbproject/private/profiler directory of your project. Saved snapshots are appended with the .nps suffix.

   Note: You can save snapshots anywhere on your filesystem, however only snapshots saved in the default location in your project will be listed in the Profiler window. You can also save snapshots as image files (.png) which can be viewed outside of the IDE.

4. Take another snapshot by clicking the Take Snapshot of Collected Results button in the Live Profiling Results toolbar (or alternatively, click the Take Snapshot button in the Profiler window). Save the snapshot.
5. In the window of one of the memory snapshots, click the Compute Difference button (  ) in the snapshot toolbar.
6. Select the second memory snapshot in the Select Snapshot to Compare dialog box and click OK.
   The Liveness Comparison window opens displaying the differences between the two memory snapshots.