Skip Headers
NetBeans Developing Applications with NetBeans IDE
Release 8.0

E50452-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

8 Testing and Profiling Java Application Projects

This chapter describes how to use the tools provided by the IDE to run unit tests and to profile Java applications.

This chapter contains the following sections:

8.1 About Testing and Profiling Java Application Projects

The IDE provides tools for creating and running unit tests and for profiling Java applications. Unit tests enable you to test the code in Java applications. Profiling is the process of examining an application to locate memory or performance-related issues.

When profiling a Java application, you can monitor the Java Virtual Machine (JVM) and obtain data about application performance, including method timing, object allocation and garbage collection. You can use this data to locate potential areas in your code that can be optimized to improve performance.

You can use the IDE to test and to profile the following types of Java applications:

8.2 Testing Java Application Projects with Unit Tests

The IDE provides built-in support for generating and executing unit tests based on the JUnit and TestNG frameworks.

The JUnit framework is an open-source product that supports development of tests and provides a harness for running these tests. The IDE supports JUnit 3 and JUnit 4 unit testing.

For more information about JUnit, see the following site:

http://www.junit.org

For more information about TestNG, see the following site:

http://testng.org/doc/index.html

8.2.1 Test Types in the IDE

You can use the IDE to create the following:

  • Empty Tests. Test skeletons without testing methods, for which no class has been designated to be tested.

  • Tests for Existing Classes. Classes containing the actual testing methods which mirror the structure of the sources being tested.

  • Test Suites. Groups of test classes clustered to permit testing of an entire application or project.

You can generate tests and test suites by selecting any class or package node in the Projects window and choosing Tools > Create Tests from the main menu.

8.2.2 Unit Test Structure

The IDE represents unit tests as subtrees which mirror the project's Java package structure. By default, when the IDE generates tests each test class has the name of the class it is testing appended by the word Test (for example, MyClassTest.java).

Each standard project has a default test folder that is used to store the unit tests and test suites. This folder is displayed as the Test Packages node in the Projects window. You can add any number of test folders to your project. Test files and the source files they test cannot be located in the same source tree.

8.3 Creating a Unit Test

The unit test generator enables you to create unit test suites and compilable test classes for use as skeletons in your unit tests. You can create unit tests for single classes and entire packages, as well as empty test skeletons to be used with sources you create later.

The first time that you create a JUnit test or test suite for a project you are asked to select which JUnit version to use. The JUnit Version dialog box opens after you make your test selections in the Create Tests dialog box. All subsequent tests for the project use that version of JUnit.

JUnit 4.x is backwards-compatible with JUnit 3.x. If you decide to downgrade from JUnit 4.x to JUnit 3.x, tests using unsupported features such as annotation descriptions and static imports are ignored.

Note:

The JUnit 4.x option is only available if your project is running on the Java 5.0 platform or higher.

8.3.1 Changing the JUnit Version

You can update support for the JUnit versions by updating the JUnit libraries in the project's Test Libraries node. View the project's JUnit libraries by expanding the project's Test Libraries node in the Projects window.

To add a new library, right-click the Test Libraries node in the Projects window and choose Add Library and select the library in the Add Library dialog box. To remove a library, right-click the library and choose Remove.

8.3.2 How to Create a Unit Test

Generated tests are distinguished by appending Test to the tested classes' names (for example, MyClassTest.java).

Note:

Depending on the version of the unit testing framework you are using, the name of the test class is not required to end with Test.

To create a test, the project must have a test directory for the tests. The IDE creates a Test Packages directory by default when you create a project. If no test directory exists in your project or you want to specify a different directory for your test, you can specify a test directory in the project properties dialog.

To create a test for a single class:

  1. Right-click the class in the Projects window and choose Tools > Create Tests (Ctrl+Shift+U) to open the Create Tests dialog box.

    You can modify the default name of the test class, but some of the navigation in the IDE between classes and test classes might not function if the name of the test class does not contain the name of the class that is tested.

  2. Select a unit test framework.

  3. Select the desired code generation options and click OK.

    Alternatively, you can create a test by choosing File > New File, selecting the Unit Tests category, and selecting JUnit Test or TestNG Test Case in the File Types pane.

To create a test suite:

  1. Right-click the package node containing the source files for which you want to generate the test suite in the Projects window and choose Tools > Create Tests (Ctrl+Shift+U) from the context menu.

  2. Select a unit test framework.

  3. Select the Generate Test Suites checkbox.

  4. Select the desired code generation options and click OK.

The IDE generates test classes for all enclosed classes and stores them in the project's Test Packages node. If any of the test classes already exist, those classes are updated. By default the IDE includes all the test classes as part of the generated test suite.

Alternatively, you can create a test suite by choosing File > New File, selecting the Unit Test category, and selecting Test Suite or TestNG Test Suite in the File Types pane.

To create an empty test:

  1. Choose File > New File from the main menu.

  2. In the New File wizard, select the Unit Test category and JUnit Test or TestNG Test Case in the File Types pane. Click Next.

  3. Specify the test class name, folder and package.

  4. Select the desired code generation options and click Finish.

When you create an empty test the IDE generates a test class that does not contain any skeleton methods. The IDE creates the test suite class based on the parameters you have specified and opens the class in the editor. The test suite class then appears in the Projects window under the package-name node in the test folder.

To create a new test for an existing class:

  1. Choose File > New File from the main menu.

  2. In the New File wizard, select the Unit Test category and Test for Existing Class in the File Types pane. Click Next.

  3. Specify the test class name and folder.

  4. Select the desired code generation options and click Finish.

When you create a test for an existing class, you specify the class that you want to test and the IDE generates a test class that contains skeleton methods based on the methods in the specified class. The IDE opens the class in the editor. The test class then appears in the Projects window in the test folder. The IDE creates the test class under the package-name node that replicates the package structure of the tested class.

To specify a test directory:

  1. Right-click the project node in the Projects window and choose Properties.

  2. In the Properties window, select Sources in the Categories pane.

  3. Define the properties of the test packages folder in the Test Package Folders list.

    You can add or remove the folders that are used for test packages and modify the names of the test packages folder as it appears in the Projects window.

  4. Click Close.

Your project must have a test package folder to generate unit tests. If the test packages folder for your project is missing or unavailable, create a new folder in your project and then designate the new folder as the test packages folder in the project's Properties window.

8.4 Running a Unit Test

Once you have created a test or test suite, use the Run Test command to initiate execution of the test. Run Test commands are available on source nodes only. After you run a test, you can rerun individual test methods executed during the test and displayed in the Test Results window.

8.4.1 How to Run a Unit Test

You can run unit tests for a specific class or method or for a project.

To run tests for an entire project:

  1. Select any node or file in the project you want to test in the Projects or Files window.

  2. From the main menu, choose Run > Test Project project_name (Alt+F6).

    The IDE executes all of the project's tests.

If you want to run a subset of the project's tests or run the tests in a specific order, you can create test suites that specify the tests to run as part of that suite. After creating a test suite you run the suite in the same way you run a single test class.

You can select multiple projects in the Projects window and run tests for them at once by choosing Run > Test number_of_selected_projects Projects (Alt+F6) from the main IDE's menu.If you want to run a subset of the project's tests or run the tests in a specific order, you can create test suites that specify the tests to run as part of that suite. After creating a test suite you run the suite in the same way you run a single test class.

To run a test for a single class:

  1. Select the node of the class for which you want to run a test in the Projects or Files window.

  2. From the main menu, choose Run > Test File (CtrlF6).

You can also run a class's test by right-clicking the test class node itself in the Projects window and choosing Test File (Ctrl+F6).

To run a single test method:

  1. Run the test class or suite containing the test method.

  2. In the Test Results window, right-click the test method and choose Run Again.

To run a single test method the method must be listed in the Test Results window.

8.4.2 Working with Unit Test Output

When you run a test, the IDE shows the following test results in two panes in the Test Results window:

  • A summary of the passed and failed tests and the description of failed tests are displayed in the left pane of the window. You can use the filter icons in the left side of the window to filter the test results.

  • The textual output from the unit tests themselves is displayed in the right pane of the window.

The output from the process that builds and runs the test is displayed in the Output window. you can double-click any error to jump to the line in the code where the error occurred.

After you run a test class, you can right-click any test method displayed in the Test Results window and choose Run Again from the context menu to run the individual test method again or Debug to debug the test.

8.5 Debugging a Unit Test

You can debug a test class as you would any class. After you set your breakpoints in the test class you can run your unit test in the debugger and step through the code to locate problems in your test classes.

To debug a unit test:

  1. Place your breakpoints in your test class.

  2. Select the node for the class whose test you wish to debug.

  3. Choose Debug > Debug Test File (Ctrl+Shift+F6) from the main menu.

When you choose Debug Test File the IDE starts the test in the debugger and opens the Debugging window. For information on using the Debugging window, see Section 9.9, "Using the Debugger Windows."

8.6 Configuring Unit Test Settings

The IDE enables you to customize the process of test generation as you create tests. You can also edit the list of sources the IDE references when compiling tests.

8.6.1 How to Edit Unit Test Settings

Modify the test settings to create a custom tests.

To edit unit test settings as you create tests:

  1. Right-click the sources for which you wish to create tests.

  2. Choose Tools > Create Tests (Ctrl+Shift+U).

  3. Select a unit test framework.

  4. In the Create Tests dialog box, select the Code Generation options you require for the tests.

The IDE creates the tests with the specified options.

8.6.2 How to Edit the Classpath for Compiling or Running Tests

Edit the classpath as needed to include specific projects, libraries, or JAR files.

To edit the classpath for compiling or running tests:

  1. Right-click the project's Test Libraries node and choose one of the following:

    • Add Project. The build output, source files, and Javadoc files of another IDE project.

    • Add Library. A collection of binary files, source files, and Javadoc files.

    • Add JAR/Folder. A JAR file or folder somewhere on your system.

  2. Click OK.

The IDE adjusts and stores the classpath priorities based on the new settings. For information on setting the classpath for a project, see Section 5.2.3.1, "Managing the Classpath."

8.7 Starting a Profiling Session

If you have a project that is targeted to run on your local machine, you can profile the project without any additional configuration. When you profile a local project, you launch the project and start the profiling session from within the IDE.

If you want to profile a local application but you cannot or do not want to start the application from the IDE, you can profile the application by attaching the IDE to the application.

To profile a local project, the project must be open in the IDE. Each of the following profiling commands in the Profile menu invoke a dialog box where you select the profiling task for the session. You can start the profiling session after you select the profiling task.

Table 8-1 Profiling Commands

Command Description

Profile > Profile Project

The selected task is run on the project that is selected in the Projects window or on the main project if a main project is set.

Profile > Profile File

The profiling task is run on the selected file. The selected file must have a main method.

Profile > Profile Test File

If a test file is selected the profiling task is run on the test file. If the selected file is not a test file, the profiling task is run on the test file associated with the selected file.

Profile > Attach Profiler

Opens the Attach Profiler dialog box. In the Attach Profiler dialog box, you select the project, the profiling task and the mode for attaching to the application. Use this to profile remote applications, running local applications, or applications that you start outside the IDE.


Note:

Before you can use the profiler in the IDE, you must calibrate the profiler. You only have to calibrate the profiler once. For information, see Section 8.7.2, "How to Calibrate the Profiler."

8.7.1 How to Profile a Project

The first time you profile a project, the IDE must modify the project build script to integrate the profiler. A backup of the project's build script is created before the modifications are made.

To profile an individual project:

  1. Right-click a project in the Projects window and choose Profile.

    Alternatively, you can select a project in the Projects window and choose Profile > Profile Project from the main menu.

  2. Select a profiling task in the Select Profiling Task dialog box.

  3. Specify any options for the task.

  4. Click Run.

When you click Run, the IDE launches the main project and opens the Profiler window.

If a project is set as the main project, the Profile Project command in the Profile menu always profiles the main project.

To profile a specific class:

  1. In the Projects window, select the class that you want to profile. (This class must contain a runnable method.)

  2. Choose Profile > Profile File from the main menu.

  3. Select a profiling task in the Select Profiling Task dialog box.

  4. Specify any options for the task.

  5. Click Run.

To profile a project or file, the project build script needs to be modified to import a profiling build script. If the build script does not contain the profiling import task, the IDE modifies the build script and creates a backup copy of the original build script.

For information on profiling an application that you started outside the IDE, see Section 8.9, "Attaching the Profiler."

For information on monitoring threads from an application at startup, see Section 8.16, "Monitoring an Application." For information on examining CPU performance and memory usage, see Section 8.17, "Analyzing CPU Performance" and Section 8.18, "Analyzing Memory Usage," respectively.

8.7.2 How to Calibrate the Profiler

You must calibrate the IDE before you can use the IDE to profile an application. You must run the calibration process for each JDK that you use for profiling. You do this because instrumenting the bytecode of the application imposes some overhead, and the time spent in code instrumentation needs to be "factored out" to achieve more accurate results.

You only have to calibrate the IDE once for each JDK that you use. However, you should run the calibration process again when anything changes on your local or remote configuration that could affect system performance. The following could affect system performance:

  • Any hardware upgrade

  • Any significant change or upgrade of the operating system

  • An upgrade of the Java platform used for profiling

To calibrate the IDE to the local system:

  1. Close any other programs that are running.

    The IDE runs the calibration if other applications are running, but running any CPU-intensive programs when performing the calibration might affect the accuracy of profiling results.

  2. Choose Profile > Advanced Commands > Manage Calibration Data from the main menu.

  3. Select the Java Platform to be used for profiling. Click Calibrate.

    You can click Java Platforms to open the Java Platform Manager to add a new Java platform. The Manage Calibration Data dialog box displays the date that the most recent calibration was performed.

When you click Calibrate, the IDE collects calibration data on the selected Java platform. When the calibration process is complete you can start using the IDE to profile your applications.

Do not share calibration data between various computers or systems.

You cannot perform a calibration of a remote platform from the Manage Calibration Data dialog box. Calibration of a remote platform is performed the first time that you profile an application on the remote platform.

To calibrate the IDE to a remote system:

8.8 Selecting a Profiling Task

When you start a profiling session, you first select and configure the profiling task. You choose the profiling task according to the type of profiling results you want to obtain from the session.

Each profiling task has default settings that are sufficient in most situations. You can configure the basic settings of each profiling task to modify the profiling results that are returned. For greater control, you can also modify the advanced settings for the task by creating a custom configuration of the task.

Table 8-2 describes the profiling tasks and the profiling results obtained from running the task.

Table 8-2 Profiling Tasks and Results

Profiling Task Results

Monitor Application

Choose this to obtain high-level information about properties of the target JVM, including thread activity and memory allocations.

Analyze CPU Performance

Choose this to obtain detailed data on application performance, including the time to execute methods and the number of times the method is invoked.

Analyze Memory Usage

Choose this to obtain detailed data on object allocation and garbage collection.


8.8.1 How to Select a Profiling Task

Each time you start or modify a profiling session, you first select a profiling task in the Select Profiling Task dialog box. You cannot run more than one profiling session at one time. You can profile a project or an individual file if the file has a runnable method. You can also profile test classes.

To select a profiling task:

  1. Select a project or file in the Projects window and choose Profile > Profile Project from the main menu.

    Alternatively, you can right-click a project node in the Projects window and choose Profile, or right-click a file and choose Profile File or Profile Test File.

  2. Select a profiling task by clicking one of the tasks in the left pane of the Select Profiling Task dialog box.

  3. Specify the options for the task in the right pane of the dialog box.

  4. Click Run.

Select a task and click Create Custom to create a customized configuration based on one of the profiling task. A custom configurations enables you to have greater control over the internal settings for that profiling task.

8.8.2 Using a Load Generator Script

The IDE supports using a load generator to replay previously saved load testing scripts. By using a load testing script, you can simulate a heavy load on your server or application to achieve more accurate results when testing application performance.

The IDE supports the Apache JMeter load testing tool. If you have an Apache JMeter load testing script, you can load the script when profiling an application. To load the script, select the LoadGenerator Script checkbox in the Select Profiling Task dialog box and choosing the script in the drop-down menu.

To work with the Apache JMeter load testing tool in the IDE, use the Plugins manager download and install the Load Generator and JMeter Kit plugins from the Update Center.

For more about using the load generator in the IDE, see the Using a Load Generator in NetBeans IDE tutorial at https://netbeans.org/kb/docs/java/profile-loadgenerator.html.

For more about using Apache JMeter, see http://jakarta.apache.org/jmeter/index.html.

8.9 Attaching the Profiler

The easiest way to profile your application is to use the Profile Project command. However, if you must start your application outside of the IDE, you can use the attach mode to profile an application. For example, you might want to use the attach mode in the following cases:

You must use the attach mode in the following cases:

The Attach mode enables you to attach the profiling tool to an application that is already running, or just about to start on a local or remote machine. Using the attach mode is useful for profiling long-running applications, and in particular for profiling web or enterprise applications running on top of an application server. You can also use the Attach mode to profile the code of the application server itself.

8.9.1 How to Configure the Attach Settings

Before you can attach to an application, the startup options for the target application or server must be configured. You use the Attach Settings dialog box to specify the attachment settings for a project. You only have to configure the attachment settings once. The attachment settings are project specific, which means that each project has its own settings. You can open the Attach Settings dialog box at any time if you want to review or modify any of the attachment settings.

To configure the attach settings:

  1. Choose Profile > Attach Profiler (Attach Profile icon) from the main menu to open the Attach Profiler dialog box.

  2. Specify the location of the application and the connection method.

    Based on the details that you provide, the Attach Settings dialog box provides you with a set of instructions on how to configure the application so that you can attach the profiler.

The attach mode you choose depends on the type of profiling data you want to obtain and the details of the target JVM platform. Table 8-3 provides an overview of the attach modes:

Table 8-3 Attach Modes

Attach Mode Description

Local Dynamic

Use this mode if you want to obtain profiling data on a local application. To use this mode, the application needs to be running on JDK 1.6 or 1.7.

When you use this mode, you can attach to and detach from the application without restarting application.

Local Direct

Use this mode if you want to obtain profiling data on the startup of a local application.

When you use this mode, the target JVM and application wait until you attach the profiler before starting. After you detach from the application, you must restart the application to start another profiling session.

Remote Direct

Use this mode if you want to obtain profiling data on an application running on a remote JVM. To use this mode, you must install the Profiler Remote Pack on the remote target machine. You specify the details of the remote system and generate the Profiler Remote Pack using the Attach Settings dialog box.

When you use this mode, the remote application starts after the profiler is attached. This mode enables you to obtain profiling data on the startup of the target JVM.


To profile an applet using the Local Direct or Remote attach mode:

  • Specify the agent parameters in the Java Control Panel and restart the browser.

8.9.2 How to Attach the Profiler to a Local Application

Use the attach mode to profile a local application when you must start the application outside of the IDE. For example, you may want to use the attach mode in the following cases:

  • Your application needs to be started from the command line or uses a complex launch script.

  • You want to obtain profiling data on the startup of the application or target JVM.

  • You want to profile the application without restarting the application (Dynamic attach mode, requires JDK 1.6 or 1.7).

To attach to a local application, you must first configure the attachment settings using the Attach Settings dialog box. These settings are associated with the project you are profiling. You only have to configure the attach settings for your project once, but you can modify the settings at any time in the Attach Settings dialog box.

When you configure the settings for attaching to a local application, you can choose from the following attachment modes:

  • Dynamic. This mode allows you to detach from and attach to the application at any time without stopping the application. This mode requires JDK 1.6 or 1.7 but does not require any additional configuration.

  • Direct. This mode enables you to obtain profiling data on the startup of the local application. This mode requires you to modify the startup script and start the application when you want to attach the profiler.

Once the connection is established and the profiler is attached to the target application, you can change the profiling task you are running on the target application without stopping or restarting the application.

To attach to a local application:

  1. Choose Profile > Attach Profiler (Attach Profiler icon) from the main menu to open the Attach Profiler dialog box.

  2. Select the target application from the Attach To drop-down list at the top of the dialog box.

  3. Click define to open the Attach Settings dialog box to specify the connection method.

  4. Select Local as the Attach Method.

  5. Select either Direct or Dynamic as the connection method.

  6. Follow the instructions in the Attach Settings dialog box for configuring the application, if necessary. Click OK.

  7. In the Attach Profiler dialog box, select a profiling task and any options.

  8. Click Attach.

To detach from the application:

  • Choose Profile > Detach from the main menu or click Detach in the Profiler window.

When you detach from the application, the connection to the target JVM is closed. When you click Detach, you can choose to stop the application upon detach or allow the application to keep running. You can re-attach to the application by choosing Profile > Attach Profiler from the main menu.

To change the profiling task without detaching:

  1. Choose Profile > Modify Profiling Session (Alt+Shift+F2) from the main menu or click Modify Profiling Session (Modify Profiling Session icon) in the Profiler window.

  2. Select a new profiling command and adjust any settings.

  3. Click Run.

The target application is instrumented again without starting or stopping the application.

8.10 Attaching the Profiler to a Remote Application

You can profile an application that is running on a remote system by attaching the profiling tool to the application. When you use this attach mode, the remote application starts after the profiler is attached. This mode enables you to obtain profiling data on the startup of the target JVM.

To attach the profiling tool, you use the Attach Settings dialog box to specify the attachment settings for your project. In the Attach Settings dialog box, specify the location, OS and JVM of the remote target. Based on the details that you provide, the Attach Settings dialog box provides you with a set of instructions on how to configure the remote application to support profiling.

8.10.1 How to Attach to a Remote Application

To attach the profiler to a remote application you must configure the application to load some profiler libraries on startup to enable the profiling tool to attach to the application. You use the Attach Settings dialog box to specify the details of the remote system and to generate a Remote Profiler Pack archive that contains the necessary profiler libraries. You must copy the contents of the Remote Profiler Pack archive to the remote system and then configure the remote application to load the profiler libraries.

After you configure the remote application according to the instructions, you can start the remote application and attach the profiler. You only have to configure the attach mode once. The attachment settings are associated with that project. You can open the Attach Settings dialog box at any time to change the attachment settings.

To attach to a remote application:

  1. Choose Profile > Attach Profiler from the main menu.

  2. Select the project from the drop-down list at the top of the Attach Profiler dialog box, if available.

  3. At the bottom of the dialog box, click define to open the Attach Settings dialog box.

  4. In the Attach Settings dialog box, select Remote as the Target option.

  5. Specify the Hostname and select the OS and JVM from the drop-down list.

  6. Save the Remote Profiler Pack to your local system and then copy the contents to the remote system.

  7. Copy the profiler agent parameters in the text box of the Attach Settings dialog box and add the parameters to the startup script of the remote application.

  8. Click OK in the Attach Settings dialog box.

  9. Start the remote application.

    When you start the remote application, the application waits until the IDE is attached before starting.

  10. Select a profiling task and any profiling options.

  11. Click Attach in the Attach Profiler dialog box.

When you click Attach, the IDE attaches to the remote JVM and the remote application starts. You can view profiling data as you would for a local application.

After the IDE is attached to the remote application you can do the following:

  • Detach from the remote application.

    When you detach from the remote application, the remote application does not stop but you stop receiving profiling data about the remote application. To attach to the remote application, use the startup options provided by the Attach Settings dialog box and start the remote application again.

  • Modify the profiling session.

    You can modify the profiling session without detaching from the remote application. For example, you can change the profiling task to monitoring to reduce the profiling overhead, and then modify the task again later. This way you do not have to re-attach and restart the remote application.

8.10.2 Attaching to a Remote Server

Similar to attaching the profiler to a remote application, you must copy the profiler libraries in the Remote Profiler Pack to the remote system to attach the profiling tool to a remote server. You must also modify the server configuration files to specify the path to the JDK and to specify the path to the profiler agent. When you start the server using the modified startup script, the server waits until the profiler attaches to the server.

You can retrieve the path to the profiler agent when you use the Attach Settings dialog box to configure your attach settings. The path to the profiler agent is similar to the following path.

-agentpath:<remote>\lib\deployed\jdk16\windows\profilerinterface.dll=\lib,5140

The placeholder <remote> refers to the full path to the root directory containing the profiler libraries that you copied to the remote system. The number 5140 is the Communication Port that the profiling tool uses to connect to the application. Modify the port number in the Profiler tab in the Java category in the Options window.

Table 8-4 identifies the startup scripts and the parameters that must be modified to specify the paths to the JDK and the profiler libraries:

Table 8-4 Startup Scripts

Server File Modification

Tomcat 7

catalina.bat/catalina.sh

Set JAVA_HOME path to JDK

For server, modify CATALINA_OPTS to include profile -agentpath parameter

GlassFish 3

asenv.bat/asenv.conf domain.xm

Set AS_JAVA path to JDK

For server, add jvm-options to include profile -agentpath parameter

WebLogic 12

startWebLogic.cmd/startWebLogic.sh

Set JAVA_HOME path to JDK

For server, modify JAVA_OPTIONS to include profile -agentpath parameter

JBoss 7

standalone.conf.bat/standalone.con

Set JAVA_HOME path to JDK

For server, modify JAVA_OPTS to include profile -agentpath parameter


For the GlassFish server, set the path to the JDK in the asenv.bat/asenv.conf file and the path to the profiler agent in domain.xml.

For more details about configuring the servers for attaching the profiler tool, see the following NetBeans FAQ: http://wiki.netbeans.org/wiki/view/FaqProfilerAttachRemoteServer

For more details about modifying server startup scripts, consult the documentation for the server.

8.11 Profiling a Free-form Project

In a free-form project, you have to create Ant targets to be able to profile a file or project. You generally want one target in your free-form project's build script for profiling a project and one target for profiling individual files.

If you do not have a profile target written for your project the IDE will offer to generate a basic target for you when you first try to profile the project. You can then inspect the target and customize it according to the specific requirements of the project.

The first time that you choose the Profile Project or Profile File command on a free-form project you must create the targets. The IDE can create the targets for you based on the information for the target that is mapped to the Run command for the project. You only have to generate the targets once.

Note:

Before the profile target is generated it is recommended that you first confirm that you have a target mapped to the Run Project command. When the IDE generates a profile target the IDE looks for the information in the target that is mapped to the Run Project command to determine details such as the run classpath and the project's main class. If a target is already mapped to the Run Project command there is a good chance that the generated profile target will work without further customization.

To profile a free-form project:

  1. Set the free-form project as the main project by choosing Run > Set Main Project in the main menu and selecting the project.

  2. Choose Profile > Profile Main Project in the main menu.

    Click Generate in the Profile Project dialog box if you are prompted to generate a target.

    When you click Generate a target named profile-nb is created in the ide-targets.xml XML file. The generated ide-targets.xml file is a build script that imports your main build.xml file. This enables your profile target to take advantage of targets and properties set by or referenced by your main build script.

    In addition, a mapping for this target is created in the project.xml file so that the target is called when you choose the Profile Project command in the IDE. If you write the target from scratch you also need to create this mapping yourself. See Section 9.8.1.1.2, "Manually Mapping a Target to a Menu Item".

  3. Configure the profiling session in the Select Profiling Task dialog and click Run.

Before profiling your free-form project, be aware of the following conditions:

8.11.1 Profiling Free-form Web Projects

Typically the server is started using a startup script, not the java command directly. Therefore you cannot use the <jvmarg .../> element to pass additional argument to it. Instead, you have to modify the server startup script to configure it for profiling.

The recommended approach is to create a new script for starting the server for profiling and use it in the profile target. The Attach Settings dialog box can provide steps to help you modify the startup script. If your target server does not support automatic integration, you can create the script by following the integration steps described in the Attach Settings dialog box. You always have to set up the integration for Local Direct attach.

The other steps for profiling a free-form web project are the same as those above for profiling a standard J2SE projects.

8.11.1.1 A Typical Free-Form Project Profile Target

The generated Ant target does the following:

  • Starts the profiler with the startprofiler task. Setting the freeform attribute to true will force displaying the profiling session configuration dialog.

  • The previous task sets the profiler.configured to true if the configuration was confirmed. It also stores the profiler agent JVM arguments in the agent.jvmargs property.

  • Establishes the runtime classpath. If the IDE is not able to determine your runtime classpath the IDE adds placeholders to the script which you need to fill in yourself.

  • Runs the application in profile mode. Setting fork="true" ensures the process is launched in a separate virtual machine.

Note:

You can add any additional JVM arguments or program arguments in the java task as well.

A generated profile target where the IDE is able to guess the runtime classpath will look similar to the following (where the italicized items would have values specific to your project).

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
        <import file="../build.xml"/>
        <target name="-profile-check">
            <startprofiler freeform="true"/>
        </target>
        <!-- TODO: edit the following target according to your needs -->
        <!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profilej2se) -->
        <target name="profile-nb" if="profiler.configured" depends="-profile-check">
            <java classname="${mainclass}" dir="." fork="true">
                <classpath>
                    <pathelement path="ClasspathSpecifiedInYourRunTarget"/>
                </classpath>
                <jvmarg line="${agent.jvmargs}"/>
            </java>
        </target>
    </project>

If you do not have a run target mapped or the IDE otherwise cannot determine the project's classpath or main class, the generated profile target includes "TODO" placeholders for you to fill in these values as in the example below.

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
        <target name="-profile-check">
            <startprofiler freeform="true"/>
        </target>
        <!-- TODO: edit the following target according to your needs -->
        <!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profilej2se) -->
        <target depends="-profile-check" if="profiler.configured" name="profile-nb">
            <path id="cp">
                <!-- TODO configure the runtime classpath for your project here: -->
            </path>
            <!-- TODO configure the main class for your project here: -->
            <java classname="some.main.Class" fork="true">
                <classpath refid="cp"/>
                <jvmarg line="${agent.jvmargs}"/>
            </java>
        </target>
    </project>

To specify the runtime classpath, insert pathelement elements within the path element and point them to the directories that contain the items in your classpath. For example, you can use the location attribute of pathelement to specify the location of the classpath items relative to your project directory. The project directory is usually the directory that contains the project's build.xml file. Below is an example of using the pathelement attributes.

<path id="cp">
    <pathelement location="libs">
    <pathelement location="build">
</path>

8.11.1.2 Writing a Target to Profile a Selected File

The process is basically the same for writing targets to debug and run a single file. The profile-selected-files target looks similar to the following:

<target name="-profile-check">
    <startprofiler freeform="true"/>
</target>
<!-- TODO: edit the following target according to your needs -->
<!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profile_sing) -->
<target depends="-profile-check" if="profiler.configured" name="profile-selected-file-in-src">
    <fail unless="profile.class">Must set property 'profile.class'</fail>
    <path id="cp">
        <pathelement location="build"/>
    </path>>
    <java classname="${profile.class}" fork="true">
        <classpath refid="cp"/>
        <jvmarg line="${agent.jvmargs}"/>
    </java>
</target>
  • This is basically the same as the profile target. Instead of passing the program main class to java you pass the profile.class property, which is set by the IDE to the currently selected file.

Then you map the profile-selected-files target to the profile.single action.

<action name="profile.single">
      <target>profile-selected-files</target>
      <context>
         <property>profile.class</property>
         <folder>${src.dir}</folder>
         <pattern>\.java$</pattern>
         <format>java-name</format>
         <arity>
            <one-file-only/>
         </arity>
      </context>
</action>
  • <property> now stores the context in the profile.class property.

  • Because java can only take a single file, you set <arity> to <one-file-only>.

  • Setting <format> to java-name and making it relative to src.dir creates a fully-qualified class name for the currently selected file.

    Note:

    The IDE does not define the ${src.dir} property for you. You need to define the property or import the .properties file that Ant is using in project.xml. See Section 5.2.4.9.1, "Using Properties in the project.xml File" for more information.

8.12 Taking a Snapshot

You can use a results snapshot to capture profiling data at a specific point in time. The data captured in a snapshot depends on the type of profiling session in progress when the snapshot is taken.

A snapshot differs from live profiling results in the following ways:

8.12.1 How to Take a Snapshot

You can only take a snapshot while a profiling session is in progress. You can take a snapshot manually or set a profiling point to take a snapshot automatically at a precise point in your application. When you use a profiling point to take a snapshot, you locate the point in your source code where you want to take a snapshot. For example, you may want to take a snapshot when a thread enters a specific method.

Perform the following steps to take a snapshot manually:

  1. Start a profiling session.

    For information, see Section 8.7, "Starting a Profiling Session."

  2. Do one of the following:

    • Click Take Snapshot in the Profiler window.

    • Click Live Results to open the Live Results window and then click Take Snapshot of Collected Results in the toolbar.

When you take a snapshot, the snapshot opens in the main editor window. You can then save the snapshot to your project.

To take a snapshot using a profiling point:

  1. Open the source file containing the code where you want to place the profiling point.

  2. Right-click in the line of code and choose Insert Profiling Point.

  3. Select one of the snapshot options in the New Profiling Point wizard and click Next.

  4. Modify any of the profiling point properties in the Customize Properties page of the wizard. Click Finish.

If you use a profiling point to take a snapshot, you can choose from the following snapshot options:

  • Take Snapshot. Choose this if you want the IDE to take a snapshot when an application thread enters or leaves the specified line of code.

  • Timed Take Snapshot. Choose this if you want the IDE to take a snapshot at a specific time and date. You can also configure the IDE to take snapshots at a specified interval.

  • Triggered Take Snapshot. Choose this if you want the IDE to take a snapshot when the specified condition is met. You specify the condition by choosing one of the available triggers.

For each snapshot option you can choose to save the snapshot to your project or you can specify a location.

To save a snapshot;

  • Click Save to Project in the snapshot toolbar.

    You can also use the Options window to configure the IDE behavior when taking a snapshot.

You can save a snapshot to your project or you can save the snapshot to a location on your local file system. When you save a snapshot to your project, the snapshot is listed under Saved Snapshots in the Profiler window.

To distinguish a snapshot from other profiling snapshots you have taken of the project, you can rename it. Select a snapshot in the Saved Snapshots section of the Profiler Control Panel and click Rename to open the Rename Snapshot dialog box and enter a new name.

You can use a saved snapshot to select an existing profiling configuration to analyze performance or you can create a custom configuration. When you click OK in the Select Settings Configuration dialog box, the selected method is added to the list of instrumentation root methods to be used for that configuration setting. You can have various configuration settings with different combinations of instrumentation root methods. When you analyze application performance you can select a configuration according to the root methods that you want to use for the profiling session.

To select a configuration or create a custom configuration from a snapshot:

  • Right-click a method name in a CPU snapshot and select Add to Instrumentation Roots in the context menu to open this window.

    The text box lists the available configuration settings for the project. Select an existing setting or select <Create new configuration> to create a new custom configuration.

8.13 Taking a Heap Dump

A heap dump captures profiling data at a specific point in time. You can take a heap dump when a profiling session is in progress. When you take a heap dump, you are prompted to save the heap to your project or local file system. After you save a heap dump you can load the heap dump at any time and browse the objects on the heap, locate references to individual objects and compare heap dumps to view the differences between the snapshots. It is not necessary to run a profiling session to load and browse the heap dump.

Note:

To take a heap dump, the application must be running on a version of JDK 1.5.0_12 or later.

8.13.1 How to Take a Heap Dump

You can take a heap dump manually or set a profiling point to take a heap dump automatically at a certain point in your application. In the Options window, you can also set the IDE to automatically take a heap dump on OutOfMemory error.

To take a heap dump manually:

  1. Start a profiling session.

  2. Choose Profile > Take Heap Dump in the main menu.

When you take the heap dump, you are prompted to specify where you want to save the heap dump. You can save the heap dump snapshot to your project or to any location on your local file system.

For information on viewing profiling data, see Section 8.20.2, "How to Browse a Heap Dump." For information on comparing data from two heap dumps, see Section 8.20.3, "How to Compare Heap Dumps."

To take a heap dump using a profiling point:

  1. Open the source file containing the code where you want to place the profiling point.

  2. Right-click in the line of code where you want to place the profiling point and choose Profile > Insert Profiling Point.

  3. In the New Profiling Point wizard, select one of the following snapshot options and click Next.

    • Take Snapshot

    • Timed Take Snapshot

    • Triggered Take Snapshot

  4. In the Customize Properties page of the wizard, select Heap Dump as the type of snapshot and modify any additional settings. Click Finish.

When you use a profiling point to take a heap dump, you specify the point in your source code where you want to place the profiling point. For example, you may want to take a heap dump when a thread enters a specific method.

To take a heap dump on OutOfMemory error:

  1. Choose Tools > Options from the main menu, click the Java category and then click the Profiler tab.

  2. For the On OutOfMemory Error setting, choose an option from the drop-down list and specify a location for the saved heap dump (optional).

8.14 Setting Profiling Filters

When you analyze application performance, you can use filters to specify the classes that you want to include or exclude in the instrumentation. When you use a filter you limit the number of instrumented classes and reduce the profiling overhead.

You choose a filter by selecting a filter from the Filter drop-down list when you configure the profiling session. The drop-down list contains the following filters and also any custom filters you create.

8.14.1 How to Set a Profiling Filter

The expedient way to set a profiling filter is by using the Quick Filter feature in the IDE. You can also customize filter sets to include or exclude specific filter sets.

To modify the Quick Filter settings:

  1. Open the Set Quick Filter dialog box by selecting Quick Filter in the drop-down list and then clicking Edit Filter Value.

  2. Select either Exclusive or Inclusive as the filter type.

  3. Type or modify the filter values and click OK.

If you want to use a filter more than once, you can create a custom filter set.

To modify or create a custom filter set:

  1. Open the Customize Filter Sets dialog box by choosing CPU in the Select Profiling Task dialog box and clicking Edit Filter Sets.

  2. Select an existing filter set or click Add and type a name for the new filter set.

  3. Specify the Filter Set Type: inclusive or exclusive.

  4. In the Global Filters list, activate the global filters you want to be part of the filter set by selecting the checkbox for that filter.

    You can place your cursor over the values to see all the patterns included in that filter.

    Each global filter represents groups of patterns that are typically related to one application. For example, org.netbeans is a pattern. A filter can contain more than one pattern. Patterns can be separated by a comma and/or space.

    Filters are applied in a "starts with" manner. For example, if the filter contains org.netbeans, classes in the package org.netbeans.modules.classfile.Annotation would be matched by the filter.

  5. Click OK to save the new custom filter set.

After you create a new filter set, you can choose the filter in the Filter drop-down list. You can use the new filter when analyzing the performance of any project. For information on analyzing project performance, see Section 8.17, "Analyzing CPU Performance."

Click Edit Global Filters to create and edit the global filters.

8.15 Setting a Profiling Point

A profiling point is a marker in your source code that can invoke specific profiling actions. You set a profiling point in your code by using the context menu in the Source Editor or by using the toolbar in the Profiling Points window.

You can set the following types of profiling points:

You can use a profiling point to reset profiling results, take a snapshot or record the timestamp or execution time of a code fragment.

You can also use a profiling to stop and start a load generator script (requires the load generator plugin).

8.15.1 How to Set Profiling Points

Once you set a profiling point it becomes part of the project until you delete it. You can view, modify and delete the Profiling Points in your projects in the Profiling Points window. The Profiling Points window displays all profiling points in open projects. You can select a profiling point and then use the toolbar to edit, remove, enable and disable the profiling point.

To open the Profiling Points window:

  • Choose Window > Profiling > Profiling Points in the main menu

To set a profiling point:

  1. Locate the class where you want to add the profiling point and open the class in the Source Editor.

  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 and click Next.

  4. Customize the properties of the profiling point, if necessary and click Finish.

When you click Finish, an icon representing the profiling point type appears in the sidebar of the Source Editor next to the line where you inserted the profiling point.

To enable and disable a profiling point:

  1. Locate the class containing the profiling point and open the class in the Source Editor.

  2. In the Source Editor, right-click in the left margin of the line containing the profiling point and choose Profiling > Disable or Enable.

Alternately, you can enable and disable profiling points in the Profiling Points window.

To view active profiling point:

You can see the profiling points that are enabled for a specific profiling session in the Select Profiling Task dialog box.

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

  3. Click Show active Profiling Points.

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

To enable, disable, or customize the settings of a profiling point:

  • Choose Window > Profiling > Profiling Points.

To view details about a profiling point:

You can view information about a profiling point in the Profiling Points Report window. The information displayed is dependent on the profiling point type. Right-click a profiling point in the Profiling Points window and choose Show Report in the context menu to open this window.

8.15.2 How to Reset Profiling Results

You can use a profiling point to reset the collected profiling results each time that a thread in the application hits the profiling point. You can then use this profiling point to gather results deltas when combined with the Take Snapshot profiling point.

To reset a profiling point:

  1. Click Add Profiling Point or Edit Profiling Point in the Profiling Points window.

  2. Select the Reset Results profiling point type and select the desired project.

  3. Click Next.

  4. Specify a name that identifies that profiling point.

  5. Specify the line number containing the profiling point and whether the profiling point is hit when a thread hits the beginning or end of that line (the file name is automatically filled in).

8.15.3 How to Set a Stopwatch Profiling Point

You can obtain a timestamp each time that a profiling point is hit instead of calling the System.currentTimeMillis() method. Setting a Stopwatch profiling point lets you measure the time between the start and stop locations to obtain the execution time of a method fragment.

To set a Stopwatch profiling point:

  1. Click Add Profiling Point in the Profiling Points window.

  2. Select the Stopwatch profiling point type and select the desired project.

  3. Click Next.

  4. Specify a name that identifies that profiling point.

  5. Select whether you want to obtain a timestamp or a timestamp and the execution duration.

  6. Specify the file in which to set the profiling point.

  7. Specify the line number containing the profiling point at which point time measurement begins (the file name is automatically filled in).

  8. If you selected Timestamp and duration, specify the line at which to stop the measurement (the file name is automatically filled in).

8.16 Monitoring an Application

When you choose Monitor Application in the Select Profiling Task dialog box, the target application is run without any instrumentation. The results show only high-level information about some properties of the target JVM, including thread activity and memory allocations.

To monitor an application:

  1. Select the project in the Projects window and choose Profile > Profile Project from the main menu.

  2. Click Monitor Application.

  3. (Optional) Select Enable Threads Monitoring.

    Select this option to monitor threads from application startup.

  4. Click Run.

When you click Run, the target application launches and the profiling task starts. Click Telemetry or Threads in the Profiler window to view the results. For information on examining telemetry results, see Section 8.19.1, "How to View VM Telemetry Results."

By default, application thread activity is not monitored. You can start monitoring thread activity at any time during a profiling session by opening the Threads tab and clicking Threads. For information, see Section 8.19.2, "How to View Thread Activity."

If you want to monitor threads from application startup, select Enable Threads Monitoring when you start the profiling session.

For information on examining results when a profiling session is in progress, see Section 8.19, "Working with Live Profiling Results."

For information on viewing a snapshot of profiling results, see Section 8.20, "Working with Captured Profiling Results."

8.17 Analyzing CPU Performance

This task analyzes the performance of the target application. You can choose to profile the entire application or limit the code that is instrumented by specifying a root method or use filters to control the classes that are profiled.

When you run this profiling task you receive the following profiling results:

To analyze performance of the application:

  1. Select the project in the Projects window and choose Profile > Profile Project from the main menu.

  2. Click CPU in the left pane of the Select Profiling Task window.

    When you click CPU, the button expands to give you the option of using the default configuration, creating a new custom configuration or using an existing custom configuration.

  3. Select one of the profiling options in the right pane:

    • Quick

    • Advanced

    If you select Advanced, you have the option to specify root methods to instrument.

  4. Specify a filter.

  5. If desired, you can use profiling points to control profiler actions.

  6. Click Run.

    The target application launches and the profiling session starts.

You can facilitate performance analysis by setting profiling filters to narrow the results to only those instrumented classes you want to examine. For more information, see Section 8.14.1, "How to Set a Profiling Filter." You can also limit the instrumented source code output to analyze by specifying a root method. For more information, see Section 8.17.2, "How to Specify a Root Method."

For information on examining results when a profiling session is in progress, see Section 8.19, "Working with Live Profiling Results."

8.17.1 How to Create a Custom Configuration

When you create a custom configuration you have complete control over all of the available internal settings for that profiling task. You can create, store, and assign names to separate sets of custom profiling settings. The custom configuration is associated with a specific project and is listed in the Select Profiling Task window when you profile the project.

You can modify the custom configurations in the Select Profiling Task dialog box. Click Advanced Settings to set more advanced profiling options. Custom configurations are automatically saved between IDE work sessions so that they can be reused and modified.

To create a custom configuration:

  1. Select the project in the Projects window and choose Profile > Profile Project from the main menu.

  2. Click CPU in the left pane of the Select Task window to expand the button.

  3. Click Create Custom.

  4. Type a name for the configuration.

  5. Select the initial settings for the configuration and click OK.

    You then modify the initial settings when you customize the configuration.

  6. Select one of the following profiling options:

    • Quick

    • Advanced

    If you select Advanced, you also have the option to specify the root methods to instrument.

  7. Specify a filter.

    For information on setting filters, see Section 8.14, "Setting Profiling Filters."

  8. If desired, you can use profiling points to control profiler actions.

    For more information on profiling points, see Section 8.15, "Setting a Profiling Point."

  9. Click Advanced Settings to set more advanced profiling options.

  10. Click Run to start the profiling session.

    The target application launches and the profiling task starts.

For information on viewing a snapshot of profiling results, see Section 8.20, "Working with Captured Profiling Results."

To create a duplicate profiling configuration:

  • Right-click the name of the configuration that you want to duplicate in the left pane of the Select Profiling Task dialog box and choose Duplicate from the context menu to open the Duplicate Configuration dialog box.

To rename a custom profiling configuration:

  • Right-click the name of an existing custom configuration in the left pane of the Select Profiling Task dialog box and choose Rename from the context menu to open the Rename Configuration dialog box.

8.17.2 How to Specify a Root Method

When analyzing application performance, you can choose to limit the source code that is instrumented by specifying a root method. When you profile an application by instrumenting a root method, profiling data is collected when one of the application's threads enters and leaves the root method.

When you specify a root method, the method is added to the list of selected root methods which you can choose to instrument when profiling application performance. The selected root methods are listed in the Specify Root Methods dialog box. Each profile application performance configuration is associated with a specific set of selected root methods.

You can specify root methods in the source code of a class or in the Select Profiling Task dialog box when setting options for analyzing application performance.

To specify a single root method in a class:

  1. Locate the class containing the method you want to add and open the class in the Source Editor.

  2. In the Source Editor, right-click in the method you want to add and choose Profiling > Add as Profiling Root Method.

  3. Select a profiling configuration and click OK.

    The method is added to the root methods that are associated with that profiling configuration.

To specify multiple root methods in a class:

  1. Locate the class containing the method you want to add and open the class in the Source Editor.

  2. In the Source Editor, right-click in the source code and choose Profiling > Select Profiling Root Methods.

  3. Select a profiling configuration and click OK to open the Select Root Methods dialog box.

  4. Expand the package and method nodes, select the methods you want to add as root methods and click OK.

    The selected methods are added to the root methods that are associated with that profiling configuration.

    Note:

    If you right-click in an object that is part of another class, the Select Root Methods dialog box enables you to select root methods in that class.

Be aware of the following considerations when setting a root method:

  • You might need to first mount the file system or a JAR file that contains your root method's class. For example, if this class does not belong to your application's classpath. That is the case, for example, when profiling code running on top of a Web/J2EE server.

  • If you choose a given method as a root when a thread is already executing it, profiling does not start. To begin profiling, a "fresh" call to the root method is required. Once partial application profiling is initiated, profiling data is not collected until one of the application's threads enters the profiling root method.

To specify root methods when setting options for analyzing application performance:

  1. Open the Select Profiling Task dialog box and select the analyze CPU task.

  2. Select Advanced.

  3. Click custom profiling roots (if no methods are defined) to open the Specify Root Methods dialog box.

    If some methods are already defined, click edit.

  4. Expand the tree and select the nodes for the root methods to instrument.

    You can use the Select View drop-down list to modify the project tree view.

  5. (Optional) Click Advanced to further edit the list of root methods.

  6. Click OK.

    The root method is added to the list of root methods to be instrumented. Click customize or edit in the Select Profiling Task dialog box to modify the list at any time.

For more, see the following NetBeans FAQ at http://wiki.netbeans.org/wiki/view/FaqProfilerProfilingRootMethods.

8.18 Analyzing Memory Usage

The Analyze Memory Usage task gives you data on objects that have been allocated in the target application. When you analyze memory usage, you can use the default configuration settings or create a custom configuration for the task.

To analyze memory usage:

  1. Select the project in the Projects window and choose Profile > Profile Project from the main menu.

  2. Click Memory in the left pane of the Select Profiling Task window to expand the button.

    You can use the default configuration, create a new custom configuration or use an existing custom configuration.

  3. Select one of the following profiling options.

    • Quick

    • Advanced

  4. Select any additional options (only available when you select the Advanced profiling option):

    • Record Full Object Lifestyle

    • Select Record Stack Traces

    • Use defined Profiling Points

  5. Click Run.

    The target application launches and the profiling session starts.

When you create a custom configuration you have complete control over all of the available internal settings for that profiling task. You can create, store, and assign names to separate sets of custom profiling settings. The custom configuration is associated with a specific project and is listed in the Select Profiling Task window when you profile the project. You can modify the custom configurations in the Select Profiling Task dialog box. Custom configurations are automatically saved between IDE work sessions so that they can be reused and modified.

To create a custom configuration:

  1. Select the project in the Projects window and choose Profile > Profile Project from the main menu.

  2. Click Memory in the left pane of the Select Task window to expand the button.

  3. Click Create Custom.

  4. Type a name for the configuration.

  5. Select the initial settings for the configuration and click OK.

    You then modify the initial settings when you customize the configuration.

  6. Select one of the following profiling options.

    • Quick

    • Advanced

  7. Select any additional options in the Basic Settings pane.

  8. Click Advanced Settings and modify any of the advanced settings.

    The options that are available in the Advanced Settings pane depend upon the options that you select in the Basic Settings pane.

  9. Click Run.

    The target application launches and the profiling task starts.

You can facilitate performance analysis by setting profiling filters to narrow the results to only those instrumented classes you want to examine. For more information, see Section 8.14.1, "How to Set a Profiling Filter." You can also set markers in the source code to invoke specific profiling operations. For more information, see Section 8.15, "Setting a Profiling Point."

For information on examining results when a profiling session is in progress, see Section 8.19, "Working with Live Profiling Results."

8.19 Working with Live Profiling Results

The profiling results obtained from a profiling session depend upon the profiling task you select. When a profiling session is in progress, you can see the live results of the profiling task. At any point during the profiling session you can capture and save the results.

The Live Results windows show the results of the profiling task over time while the profiling session is in progress. The IDE displays live profiling results in the following windows.

You can open any of these windows by choosing Window > Profiling > window_name from the main menu.

8.19.1 How to View VM Telemetry Results

You can view high-level data on thread activity and memory heap and garbage collection in the VM Telemetry window. The VM Telemetry window is typically visible in the main Editor window.

To open the VM Telemetry window, do one of the following during a profiling session:

  • Choose Window > Profiling > VM Telemetry from the main menu.

  • Click VM Telemetry (Telemetry Window icon) in the Profiler window.

VM Telemetry results are displayed in the following tabs:

  • Memory (Heap). This tab displays the total size and used size of the heap.

  • Memory (GC). This tab displays the relative time spent in garbage collection and the number of surviving generations.

  • Threads/Loaded Classes. This tab displays the total number of threads in the profiled application JVM.

In each of the tabs, you can place your cursor over the graph to invoke a tooltip that displays more detailed data.

Table 8-5 displays the commands in the VM Telemetry window toolbar.

Table 8-5 VM Telemetry Commands

Command Function

Export

Export Telemetry Results icon

Exports the results as a text file.

Save Current View

Save Current View icon

Saves the results as a .png image file.

Zoom In

Zoom In icon

Increases the detail of the graph.

Zoom Out

Zoom Out icon

Decreases the detail of the graph.

Scale to Fit

Scale To Fit icon

Toggles between a scalable view and a fixed-scale view.


Go to the VM Telemetry Overview window (located below the editing area) to view high-level data on thread activity, memory heap and garbage collection in the VM.

To open the VM Telemetry Overview window:

  • Choose Window > Profiling > VM Telemetry Overview from the main menu.

Relative time is measured as a percentage of the total execution time that the target JVM spends running garbage collection with all application threads suspended.

Surviving generations displays the number of different ages for all objects allocated on the JVM heap since the moment the Profiler was attached.

Age of object is measured as the number of garbage collections survived.

8.19.2 How to View Thread Activity

During a profiling session, you can view detailed information about application thread activity in the Threads window. Start monitoring thread activity at any time during a profiling session by opening the Threads tab and clicking Threads. By default, application thread activity is not monitored until invoked.

To open the Threads window during a profiling session:

  • Choose Window > Profiling > Threads from the main menu.

  • Click Threads in the Profiler window (Threads button).

If you want to monitor threads from application startup, select Enable Threads Monitoring when you start the profiling session. For more information configuring profiling tasks, see Section 8.8, "Selecting a Profiling Task."

8.19.3 How to View Live Results

The Live Results window displays the live results of the running profiling session. Use the toolbar and context menus to work with the results displayed in the Live Results window.

To open the Live Results window, do one of the following during a profiling session:

  • Choose Window > Profiling > Live Results from the main menu.

  • Click Live Results in the Profiler window.

Table 8-6 describes the command in the Live Results toolbar:

Table 8-6 Live Results Commands

Command Function

Update Results Automatically

Update Results Automatically button

Updates results at short intervals when enabled (default state). When disabled, click Update Results Now to update the results.

Update Results Now

Update Results Now button

Updates the results immediately.

Run Garbage Collection and Update Results

Run Garbage Collection and Update Results button

Starts garbage collection and updates results.

Reset Collected Results

Reset Collected results button

Discards the accumulated profiling results.

Take Snapshot of Collected Results

Take Snapshot of Collected Results button

Saves the results as snapshot. The unsaved snapshot is opened in the Source Editor.

Export to

Export icon.

Exports the displayed results as a .xml, .csv, or .html file.

Save Current View

Save Current View button

Saves the displayed results as a .png image.


Click on the respective column header to sort the results in the table. Right-click result entries in the table to choose commands from the context menu. The results that are displayed and the context menu items that are available depend upon the profiling task that is running.

If you are profiling application performance and instrumenting methods in your profiling session, click DrillDown (Drill Down button) to open the DrillDown Window to view a graphic overview of the information in the Live Results window and explore the profiled methods according to general predefined categories. The percentage of methods in each predefined category is displayed below the graph.

Click on a category area displayed in the graph to drill down to view methods in that category. You can use this to filter the list of methods displayed in the Live Results window.

Click on a category to drill down to view the methods grouped in that category.

Click on a method in the Live Results window to view the category for that method in the DrillDown window. It also displays the HTTP Request URI for the selected method, if applicable.

If you want to examine profiling data captured at a specific time during execution, you can take a snapshot of the data. For more information, see Section 8.12, "Taking a Snapshot."

To refine the profiling results, you can set filters for a profiling session. For more information, see Section 8.14, "Setting Profiling Filters."

8.19.4 How to Filter Live Results

In the Live Results window and in result snapshots you can use the filter box located below the displayed results to filter the results by name.

To filter results by name:

  1. Open the Live Results or window or snapshot.

  2. Type the filter term in the filter box below the displayed results.

    In snapshots, the filter box is available in the HotSpots and Combined tabs in CPU snapshots, and in the Memory tab in memory snapshots.

  3. Choose one of the following filtering parameters for the term from the drop-down menu:

    • Starts with

    • Contains

    • Ends with

    • Regular expression

  4. Click the check on the right to apply the filter to the results.

Click the arrow to the right of the filter box to see and select previous filter terms. To restore the full unfiltered results, click Clear Filter to the right of the filter box.

8.19.5 How to Detect Lock Contention

In the Lock Contention window you can view details about locked threads and the threads that are monitoring and holding locks. You need to enable lock contention monitoring to view the data.

To monitor lock contention:

  1. Choose Profile > Profile Project from the main menu to open the Select Profiling Task wizard.

  2. Select a profiling task and select the Enable lock contention monitoring option.

    The Enable lock contention monitoring option is available as a basic option when you monitor the application. The option is available as an advanced option when you analyze application performance or memory.

  3. Click Run to start the profiling session.

    When you click Run the profiling session starts and the Lock Contention window opens in the IDE.

In the Lock Contention window you can choose Threads or Monitors in the View drop-down list. Choose Threads to view the threads that are locked and expand the nodes to view the owners of the locks. Choose Monitors to view the threads that are locking other threads.

8.20 Working with Captured Profiling Results

The Captured Results windows show profiling data at a certain point in time during the profiling session. You can capture results at any time during a profiling session and save the results to your project or local system. It is not necessary to run a profiling session to view saved captured results.

The IDE displays captured profiling results in the following windows:

8.20.1 How to Work with Snapshots

A results snapshot captures profiling data at a specific point in time. The data captured in a snapshot depends on the type of profiling session in progress when the snapshot is taken. You can explore snapshots using the toolbar in the Snapshot window and by filtering the displayed results. You can also right-click a result and select additional commands in the context menu.

When a snapshot is open, you can use the toolbar at the top of the snapshot to help you work with the snapshot. The tools in the toolbar enable you to save snapshots, refine the display and search for terms within the results. The following table describes the items in the snapshot toolbar.

Table 8-7 Snapshot Commands

Command Function

Save Snapshot to Project

Save Snapshot to Project button

Saves the snapshot to your project. The snapshot is saved to the profiler directory in nbproject > private directory in your project. Saved snapshot files are visible in the Saved Snapshots section of the Profiler window.

Save Snapshot to Custom File

Save Snapshot to Custom File button

Saves the snapshot file in a location other than to your project.

Save Current View

Save Current View button

Saves the snapshot file as a .png image file.

Find

Find button

Finds the occurrence of a search term.

Find Next Occurrence

Find Next Occurrence button

Finds the next occurrence of a search term.

Find Previous Occurrence

Find Previous Occurrence button

Finds the previous occurrence of a search term.

Compare Snapshots

Compare Snapshots button

Compares two saved snapshots. When you click the button in the toolbar of an open snapshot you are prompted to choose a snapshot file to compare to the open snapshot.


To open a saved snapshot:

  1. In the Saved Snapshots section of the Profiler window, select your project from the drop-down list.

  2. Double-click a snapshot in the list.

To compare two snapshots:

  1. Choose Profile > Compare Snapshots in the main menu.

  2. Click Browse in the Select Snapshots to Compare dialog box to locate the two snapshots and click OK.

    When you are locating snapshots in the file browser, the snapshot file type for memory snapshots and CPU snapshots is indicated by.nps appended to the file name. You cannot identify the type of snapshot by the file name in the file browser if you used the default names that were generated by the IDE when you saved the snapshots.

    When choosing the snapshots that you want to compare, make sure the snapshots are of the same type and contain similar details based on the options that were selected for the profiling session when the snapshot was taken.

    The comparison that is displayed depends upon the data that is contained in the snapshots. The data that is captured in the snapshot depends upon the options that were selected for the profiling session.

8.20.1.1 Comparing Snapshots

The CPU Snapshot Comparison window displays a table showing the method call chain and the time spent and the number of invocations for executing threads and methods in each context. The IDE compares the two CPU snapshots and displays the differences between the two snapshot in the number of invocations and the amount of time spent in invocations.

You can perform the following actions in the CPU snapshot comparison window:

  • Click Show or Hide Result Columns to modify the columns that are displayed in the table.

  • Click a column header to sort the order that the results are displayed.

  • Right-click in the row for a class and choose Go To Source to load the source .java file of the class.

  • Right-click in the row for a method and choosing Add to Instrumentation Roots to add a method as a profiling root method.

  • Filter the list by the name of the method, class or package by typing the filter criteria in the Filter field at the bottom of the window and clicking the filter icon (Filter icon) to selecting a filter option.

The Memory Snapshot Comparison window displays a table with details about the number of object instances and the amount of memory occupied by the objects at the time the snapshots were taken. The IDE compares the two snapshot and for each object displays the changes that occurred between the snapshots

You can perform the following actions in the memory comparison window:

  • Click a column header to sort the order that the results are displayed.

  • Load the source .java file of a class by right-clicking in the row for the class and choosing Go To Source.

  • Filter the list by the class name by typing the filter criteria in the Class Name Filter at the bottom of the window and clicking the filter icon (Filter icon) to selecting a filter option.

8.20.2 How to Browse a Heap Dump

A heap dump captures profiling data at a specific point in time. You can load and browse any heap dump saved on your local system. It is not necessary to run a profiling session to load and browse a heap dump.

To open a heap dump:

  1. Choose Profile > Load Heap Dump in the main menu.

  2. Locate the heap dump on your system and click Open.

    The heap dump opens in the HeapWalker in the Heap window.

The default location for heap dump files (the file name is appended with.hprof) that you save to your project is in the PROJECT_ROOTDIR/nbproject/private/profiler folder.

The HeapWalker enables you to evaluate Java heap contents and search for memory leaks. Use the HeapWalker to view the following information.

  • List of classes present on the heap. For each class you can see the number of instances of that class and total size of all instances.

  • List of instances of each class. You can see individual instances and their size (size of instances of the same class varies only for arrays).

  • Fields of each instance or class. You can browse (static) fields to identify individual instances by field values and determine dependencies among them.

  • References to each instance. You can browse instances or classes holding reference to a particular instance to find unnecessary references and discover memory leaks.

When the heap dump is loaded and open in the Heap window, use the following tabs to view information about the heap dump:

  • Summary. This tab displays general information about the heap dump such as total numbers of classes, instances. The Summary tab also provides you with information about the environment and system properties of the machine where the heap dump was taken.

  • Classes. This tab displays a list of classes with information about the number of instances of the class and total size of the instances. You can use the Static Fields and Classes tab to modify the information that is displayed in the tab. Click Static Fields at the top of the Classes tab to view the static fields of the selected class. Use the Class Name Filter to limit the classes that are displayed.

    You can double-click any class in the list to view the instances of that class in the Instances tab. Alternatively, you can right-click a class and choose Show in Instances View.

  • Instances. This tab displays the instances for a class that you select in the Classes tab. For each instance, you can do the following:

    • Select an instance to browse the fields of the instance in the Field Browser.

    • Select an instance to browse the references to the instance in the Reference Browser.

    If you click Compute retained size at the top of the Instances tab the IDE calculates and displays the size of each instance and the total size for all the instances of the selected class.

    Click Instances, Fields, or References in the toolbar to hide or reveal the individual windows.

  • OQL Console. This tab displays the OQL editor, saved OQL queries and a window that displays the query results. Use any of the sample OQL queries or create a query to filter and select heap data to locate the information that you want from the Java heap. After you choose or write a query, run the query against the Java heap and view the results. For information on using OQL to analyze data from the Java heap, see Section 8.20.4, "How to Analyze a Heap Dump Using OQL."

8.20.3 How to Compare Heap Dumps

Compare two heap dumps to view the differences between two heap snapshots that were taken at different times.It is not necessary to run a profiling session to compare heap dumps.

To compare two heap snapshots:

  1. If no heap dump is open in the Heap window, open a heap dump by choosing Profile > Load Heap Dump.

    Alternatively, you can open heap dump snapshots from the Profiler Control Panel if an open project has snapshots associated with the project.

  2. Click the Classes tab in the Heap window.

  3. Click Compare with another heap dump at the top of the Classes tab.

    The IDE opens the Select Heap Dump to Compare dialog box.

  4. Select a heap dump that is saved in your project or select From File and click Browse to locate a heap dump that is saved outside of your project on your local system.

  5. Click OK.

    The IDE updates the Heap window to display the differences between the two heap dumps.

Click reset view at the top of the Heap window to display the initial heap dump.

8.20.4 How to Analyze a Heap Dump Using OQL

OQL is a SQL-like query language to query a Java heap that enables you to filter/select information wanted from the Java heap. While pre-defined queries such as "show all instances of class X" are already supported by the tool, OQL adds more flexibility. OQL is based on the JavaScript expression language.

When you load a Java heap in the Heap window, you can click the OQL Console tab of the window to open the OQL editor. The OQL Console contains a Query Editor pane, a Saved Queries pane and a Query Results pane. You can use any of the sample OQL queries or create a query and then run the query against the Java heap and view the results.

To run an OQL query:

  1. Type an OQL query in the Query Editor.

    Alternatively, you can select a query in the Saved Queries pane and click Open.

  2. Click Execute in the Query Editor.

    The results of the query are displayed in the Query Results pane.

  3. (Optional) Click Save to add the query to the list of saved queries.

For more details on using OQL to analyze a heap dump, see http://visualvm.java.net/oqlhelp.html.