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:

Notes.

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

Setting a Profiling Point

The easiest way to set a profiling point is in the source code in the editor window. You can simply choose the line in the code where you want to set the profiling point and then open the New Profiling Point window. You can also set profiling points when you are configuring the options for the profiling session.

1. Open the file that contains the code where you want to insert the profiling point.
2. In the source editor, right-click in the line where you want to add the profiling point and choose Profiling > Insert Profiling Point to open the New Profiling Point wizard.
3. Select a profiling point type and the project. Click Next.
   
4. Type a name for the profiling point and customize the properties of the profiling point. Click Finish.

When you click Finish, an icon representing the profiling point type appears in the left margin of the source editor next to the line where you inserted the profiling point.

Enabling, Disabling and Editing Profiling Points

When no profiling session is running, you can edit, enable and disable individual profiling points in either the source editor or in the Profiling Points window. To see a list of all profiling points, open the Profiling Points window by choosing Window > Profiling > Profiling Points from the main menu. The Profiling Points window shows the current status of the profiling points.

When a profiling session is running, the Profiling Points window displays how many times each profiling point was hit and enables you to view a report of the results.

You can quickly navigate to a specific profiling point in your source code by opening the Profiling Points window and right-clicking the profiling point name and choosing Show Source.

To modify the status or the settings of a profiling point, do either of the following.

• In the source editor, right-click the profiling point icon in the margin and choose Profiling Point in the popup menu.
• In the Profiling Points window, select a profiling point and then use the toolbar to edit, remove, enable or disable the profiling point.

  Alternatively, you can right-click the profiling point name in the list and choose a command in the popup menu.

If you choose to edit a profiling point, the Customize Profiling Point dialog box opens.

Viewing Active Profiling Points in a Project

You can use profiling points when you are analyzing memory usage or application performance. When you are selecting the profiling task you can see the profiling points that are active and enabled for the profiling session.

1. Right-click the project node and choose Profile to open the Select Profiling Task dialog box.
2. Select the profiling task (CPU or Memory) and click Show active Profiling Points in the settings pane.

When you click Show active Profiling Points, a dialog box opens that lists all the profiling points that are set in the project. Profiling points that are set but disabled are greyed out.

Note. If you want to enable, disable or customize the settings of a profiling point, open the Profiling Points window or locate the profiling point in the project.

Creating the Sample Project

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

To create the Anagram Game application, perform 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 Finish.

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 the 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.

Measuring Execution Time of a Code Fragment

You use the Stopwatch profiling point to retrieve timestamps when the profiling point is hit. You can also use the Stopwatch profiling point to measure how long it takes to execute a code fragment by calculating the difference between two timestamps. You can set any number of stopwatch profiling points.

When you set a Stopwatch profiling point you choose one of the following types.

• Timestamp. This type retrieves a timestamp when the profiling point is hit.
• Timestamp and Duration. This type enables you to measure how long it takes to execute a code fragment. You specify the code fragment you want to measure by setting a Stopwatch profiling point at the point where you want the measurement to begin and another Stopwatch profiling point where you want the measurement to end. The stop and end stopwatch points are paired by their name.

To measure the execution time of a code fragment, perform the following steps.

1. Open the Anagrams.java class in the editor by expanding the com.toy.anagrams.ui source package and double-clicking Anagrams.java.
2. Locate the line in the source code where you want the measurement to start, for example at line 54.
3. Right-click in the line and choose Profiling > Insert Profiling Point from the popup menu.
4. Select Stopwatch as the Profiling Point Type. Click Next.
5. Select Timestamp and duration as the Setting.

   When you choose Timestamp and duration, the dialog box automatically sets the stopwatch to start at the beginning of the line of code and to end at the end of the following line. You can modify the lines where the stopwatch starts and ends.

6. Modify the Location (end) setting to change the end line to a couple lines after the begin line. Click Finish.
   

   When you set the profiling point, annotations for the start point and end point appear in the left margin of the editor.

   

   If you open the Profiling Points window you can see that the stopwatch profiling point is added to the list.

7. Click Profile Main Project in the toolbar.
8. In the Select Profiling Task dialog box, click the CPU profiling task.
   

   Note. Profiling points can be used when analyzing performance or memory usage.

9. Select Use defined Profiling Points.

   If you click Show active profiling points you can view the profiling points that are enabled for the profiling session.

   
10. Click Run.

When you click Run, the IDE launches the Anagram Game application and starts the profiling session. If you open the Profiling Points window you can see if the Stopwatch profiling point was hit. After the profiling point is hit you can click report in the Results column of the window opens the window displaying data about the profiling point and the length of time it took to execute the code fragment between the begin and end stopwatch profiling points.

Note. If this is the first time that you are profiling a project, see Introduction to Profiling Java Applications in NetBeans IDE for details on calibration and profiler integration.

Taking a Snapshot or Heap Dump

If you want to capture profiling data at a very precise moment you can use a profiling point to take a snapshot of profiling results or of the heap (heap dump). To take a profiling results snapshot (either memory or CPU) or a heap dump, you place a Take Snapshot profiling point in the source code, choose the type of snapshot and specify where you want the files to be saved. If you do not specify a location, all snapshots will be saved in the main project folder (nbproject/private).

Note. You should exercise caution when placing a snapshot profiling point because the profiling point might be hit several hundred times if it is placed in frequently executed code.

To take a snapshot using a profiling point, perform the following steps.

1. Open the Anagrams.java class in the editor by expanding the com.toy.anagrams.ui source package and double-clicking Anagrams.java.
2. Locate the line in the source code where you want to place the profiling point.
3. Right-click in the line and choose Profiling > Insert Profiling Point from the popup menu.
4. Select Take Snapshot as the Profiling Point Type. Click Next.
5. Select either Profiling data snapshot or Heap dump as the Setting.
6. Specify a location where you want the files to be saved or keep the default location. Click Finish.
   
7. Click Profile Main Project in the toolbar.
8. In the Select Profiling Task dialog box, click either CPU or Memory.
9. Select Use defined profiling points.

   If you click Show active profiling points you can view the profiling points that are enabled for the profiling session.

10. Click Run.

When you click Run, the IDE launches the Anagram Game application and starts the profiling session. If you open the Profiling Points window you can see if the Take Snapshot profiling point was hit. If the profiling point was hit, you can click report in the Results column to open a window displaying data about the profiling point. To view the snapshot, click "open snapshot" in the window.

Snapshot points can be effectively paired with Reset points to produce heap deltas.

When you use a Take Snapshot profiling point, the resulting snapshots or heap dumps are automatically saved to the specified location. If you specified that the snapshots should be saved to the project folder, the saved snapshots automatically appear in the Saved Snapshots list in the Profiler window. You can open snapshots in the Saved Snapshots list by selecting the item and clicking Open.

Note. If you specify that snapshots should be saved in a location other than the project folder, the snapshots are not automatically listed in the Saved Snapshots list. To open snapshots not listed in the Saved Snapshots list, click the Load button next to the list and navigate to the location of the saved snapshot.

For more about working with snapshots and heap dumps, see the following documents.

• See the Taking Snapshots section of the Introduction to Profiling tutorial for more about viewing and comparing snapshots.

Resetting Profiling Results

You can reset collected results (either memory or CPU) at any given precise point by placing a Reset Results profiling point in the source code.

To set a Reset Results profiling point, perform the following steps.

1. Open the Anagrams.java class in the editor by expanding the com.toy.anagrams.ui source package and double-clicking Anagrams.java.
2. Locate the line in the source code where you want to place the profiling point.
3. Right-click in the line and choose Profiling > Insert Profiling Point from the popup menu.
4. Select Reset Results as the Profiling Point Type. Click Next.
5. Specify a name for the profiling point and ensure the location of the profiling point is correct. Click Finish.
   
6. Click Profile Main Project in the toolbar.
7. In the Select Profiling Task dialog box, click either CPU or Memory.
8. Select Use defined Profiling Points.

   If you click Show active profiling points you can view the profiling points that are enabled for the profiling session.

9. Click Run.

When you click Run, the IDE launches the Anagram Game application and starts the profiling session. If you open the Profiling Points window you can see if the Reset Results profiling point was hit. If the profiling point was hit, you can click report in the Results column to open a window displaying data about the profiling point.