NetBeans Developing Applications with NetBeans IDE Release 7.4 E40142-08 |
|
|
PDF · Mobi · ePub |
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:
Section 8.1, "About Testing and Profiling Java Application Projects"
Section 8.2, "Testing Java Application Projects with Unit Tests"
Section 8.10, "Attaching the Profiler to a Remote Application"
The IDE provides tools for creating and running unit tests. 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 profile the following types of Java applications:
Java SE projects
Java EE and Web applications
Java Free-form projects
NetBeans Modules and Module suites
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:
For more information about TestNG, see the following site:
http://testng.org/doc/index.html
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.
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.
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.
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 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.
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.
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:
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.
Select a unit test framework.
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.
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.
Select a unit test framework.
Select the Generate Test Suites checkbox.
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.
Choose File > New File from the main menu.
In the New File wizard, select the Unit Test category and JUnit Test or TestNG Test Case in the File Types pane. Click Next.
Specify the test class name, folder and package.
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:
Choose File > New File from the main menu.
In the New File wizard, select the Unit Test category and Test for Existing Class in the File Types pane. Click Next.
Specify the test class name and folder.
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.
Right-click the project node in the Projects window and choose Properties.
In the Properties window, select Sources in the Categories pane.
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.
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.
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.
You can run unit tests for a specific class or method or for a project.
To run tests for an entire project:
Select any node or file in the project you want to test in the Projects or Files window.
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:
Select the node of the class for which you want to run a test in the Projects or Files window.
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).
Run the test class or suite containing the test method.
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.
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 Ant 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.
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.
Place your breakpoints in your test class.
Select the node for the class whose test you wish to debug.
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.8, "Using the Debugger Windows."
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.
Modify the test settings to create a custom tests.
To edit unit test settings as you create tests:
Right-click the sources for which you wish to create tests.
Choose Tools > Create Tests (Ctrl+Shift+U).
Select a unit test framework.
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.
Edit the classpath as needed to include specific projects, libraries, or JAR files.
To edit the classpath for compiling or running tests:
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.
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."
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.
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."
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:
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.
Select a profiling task in the Select Profiling Task dialog box.
Specify any options for the task.
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.
In the Projects window, select the class that you want to profile. (This class must contain a runnable method.)
Choose Profile > Profile File from the main menu.
Select a profiling task in the Select Profiling Task dialog box.
Specify any options for the task.
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.
You must calibrate the IDE before you can use the IDE to profile an application. You must run the calibration process for each JDK 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 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:
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.
Choose Profile > Advanced Commands > Run Profiler Calibration from the main menu.
Choose the Java Platform to be used for profiling and click OK.
When you click OK, 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.
To calibrate the IDE to a remote system:
To calibrate the IDE to a remote system, see the NetBeans FAQ at http://wiki.netbeans.org/wiki/view/FaqProfilerCalibration
.
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. |
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.
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.
Select a profiling task by clicking one of the tasks in the left pane of the Select Profiling Task dialog box.
Specify the options for the task in the right pane of the dialog box.
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.
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
.
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:
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
You must use the attach mode in the following cases:
You want to profile an application running on a remote JVM, such as a remote application server
You want to profile a Java EE or web application and the target server is not Tomcat, GlassFish, WebLogic or JBoss
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.
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:
Choose Profile > Attach Profiler () from the main menu to open the Attach Profiler dialog box.
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:
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.
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:
Choose Profile > Attach Profiler () from the main menu to open the Attach Profiler dialog box.
Select the target application from the Attach To drop-down list at the top of the dialog box.
Click define to open the Attach Settings dialog box to specify the connection method.
Select Local as the Attach Method.
Select either Direct or Dynamic as the connection method.
Follow the instructions in the Attach Settings dialog box for configuring the application, if necessary. Click OK.
In the Attach Profiler dialog box, select a profiling task and any options.
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:
Choose Profile > Modify Profiling Session (Alt+Shift+F2) from the main menu or click Modify Profiling Session () in the Profiler window.
Select a new profiling command and adjust any settings.
Click Run.
The target application is instrumented again without starting or stopping the 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.
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:
Choose Profile > Attach Profiler from the main menu.
Select the project from the dropdown list at the top of the Attach Profiler dialog box, if available.
At the bottom of the dialog box, click define to open the Attach Settings dialog box.
In the Attach Settings dialog box, select Remote as the Target option.
Specify the Hostname and select the OS and JVM from the dropdown list.
Save the Remote Profiler Pack to your local system and then copy the contents to the remote system.
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.
Click OK in the Attach Settings dialog box.
Start the remote application.
When you start the remote application, the application waits until the IDE is attached before starting.
Select a profiling task and any profiling options.
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.
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:
Server | File | Modification |
---|---|---|
Tomcat 7 |
|
Set For server, modify |
GlassFish 3 |
|
Set For server, add jvm-options to include profile |
WebLogic 12 |
|
Set For server, modify |
JBoss 7 |
|
Set For server, modify |
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.
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.
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.
To profile a free-form project:
Set the free-form project as the main project by choosing Run > Set Main Project in the main menu and selecting the project.
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.
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:
The project output must be set before you can profile a free-form application.
If you click Generate in the Profile Project dialog box to generate the targets the IDE creates a build script named ide-targets.xml
and generates a target named profile-nb
. Verify that the generated profile-nb
target properly takes into account all of the elements of your project. In some cases, you might have to modify the classpath argument in the target if it does not include all of the items in your run classpath.
The IDE also modifies project.xm
l to map the profile-nb
target to the Profile Project command in the IDE. If you write the target from scratch, you must also create this mapping yourself.
For example, the profile-nb
target that the IDE generates inide-targets.xml
might look similar to the following example:
Example 8-1 Sample profile-nb Target
<?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 --> <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>
In this example the IDE attempted to guess the runtime classpath for the 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.
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.
For more about how to profile a free-form project and arguments you can use, see Creating a Target to Profile Your Java SE Application at http://netbeans.org/kb/articles/freeform-config.html#profilej2se.
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:
Snapshots can be examined when no profiling session is running.
Snapshots contain a more detailed record of profiling data than live results.
Snapshots can be easily compared.
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:
Start a profiling session.
For information, see Section 8.7, "Starting a Profiling Session."
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:
Open the source file containing the code where you want to place the profiling point.
Right-click in the line of code and choose Insert Profiling Point.
Select one of the snapshot options in the New Profiling Point wizard and click Next.
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.
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.
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.
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.
Start a profiling session.
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 filesystem.
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:
Open the source file containing the code where you want to place the profiling point.
Right-click in the line of code where you want to place the profiling point and choose Profile > Insert Profiling Point.
In the New Profiling Point wizard, select one of the following snapshot options and click Next.
Take Snapshot
Timed Take Snapshot
Triggered Take Snapshot
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:
Choose Tools > Options from the main menu, click the Java category and then click the Profiler tab.
For the On OutOfMemory Error setting, choose an option from the drop-down list and specify a location for the saved heap dump (optional).
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 dropdown list when you configure the profiling session. The dropdown list contains the following filters and also any custom filters you create.
Profile all classes. When selected, all classes on the classpath are instrumented. This imposes a high profiling overhead.
Profile only project classes. When selected, only the classes in the selected project are instrumented. To see the classes that to be instrumented, select the filter and click Show Filter Value. Click To Quick Filter in the Show Filter Value dialog box to add the listed classes to the Quick Filter.
Profile project & subprojects classes. When selected, all projects packaged as part of the project are also instrumented. For example, you should choose this filter if you are profiling an enterprise application project and you also want to instrument the web application or EJB module (the subprojects). This filter is not available if the project has no subprojects.
Quick filter. When selected, only the classes specified by the Quick Filter are instrumented. You use the Quick Filter to rapidly create a filter for use during a single profiling session.
Exclude Java Core Classes. When selected, only the classes specified by the Java Core Classes filter set are instrumented. The Java Core Classes is a filter set that is created by default. Click Edit Filter Sets to modify the Java Core Classes filter set or to create a custom filter set.
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:
Open the Set Quick Filter dialog box by selecting Quick Filter in the dropdown list and then clicking Edit Filter Value.
Select either Exclusive or Inclusive as the filter type.
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:
Open the Customize Filter Sets dialog box by choosing CPU in the Select Profiling Task dialog box and clicking Edit Filter Sets.
Select an existing filter set or click Add and type a name for the new filter set.
Specify the Filter Set Type: inclusive or exclusive.
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.
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.
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:
Reset Results
Stopwatch
Take Snapshot
Load Generator
Timed Take Snapshot
Triggered Take Snapshot
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).
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
Locate the class where you want to add the profiling point and open the class in the Source Editor.
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.
Select a profiling point type and the project and click Next.
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:
Locate the class containing the profiling point and open the class in the Source Editor.
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.
Right-click the project node and choose Profile to open the Select Profiling Task dialog box.
Select the profiling task (CPU or Memory).
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.
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.
Click Add Profiling Point or Edit Profiling Point in the Profiling Points window.
Select the Reset Results profiling point type and select the desired project.
Click Next.
Specify a name that identifies that profiling point.
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).
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:
Click Add Profiling Point in the Profiling Points window.
Select the Stopwatch profiling point type and select the desired project.
Click Next.
Specify a name that identifies that profiling point.
Select whether you want to obtain a timestamp or a timestamp and the execution duration.
Specify the file in which to set the profiling point.
Specify the line number containing the profiling point at which point time measurement begins (the file name is automatically filled in).
If you selected Timestamp and duration, specify the line at which to stop the measurement (the file name is automatically filled in).
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.
Select the project in the Projects window and choose Profile > Profile Project from the main menu.
Click Monitor Application.
(Optional) Select Enable Threads Monitoring.
Select this option to monitor threads from application startup.
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."
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:
Time in percentage and real time for executing methods in context
Number of times each method is invoked in context
Chains of method calls leading to method invocation
Time / number for executing methods in context
To analyze performance of the application:
Select the project in the Projects window and choose Profile > Profile Project from the main menu.
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.
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.
Specify a filter.
If desired, you can use profiling points to control profiler actions.
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."
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:
Select the project in the Projects window and choose Profile > Profile Project from the main menu.
Click CPU in the left pane of the Select Task window to expand the button.
Click Create Custom.
Type a name for the configuration.
Select the initial settings for the configuration and click OK.
You then modify the initial settings when you customize the configuration.
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.
Specify a filter.
For information on setting filters, see Section 8.14, "Setting Profiling Filters."
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."
Click Advanced Settings to set more advanced profiling options.
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.
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:
Locate the class containing the method you want to add and open the class in the Source Editor.
In the Source Editor, right-click in the method you want to add and choose Profiling > Add as Profiling Root Method.
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:
Locate the class containing the method you want to add and open the class in the Source Editor.
In the Source Editor, right-click in the source code and choose Profiling > Select Profiling Root Methods.
Select a profiling configuration and click OK to open the Select Root Methods dialog box.
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:
Open the Select Profiling Task dialog box and select the analyze CPU task.
Select Advanced.
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.
Expand the tree and select the nodes for the root methods to instrument.
You can use the Select View dropdown list to modify the project tree view.
(Optional) Click Advanced to further edit the list of root methods.
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
.
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.
Select the project in the Projects window and choose Profile > Profile Project from the main menu.
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.
Select one of the following profiling options.
Quick
Advanced
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
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:
Select the project in the Projects window and choose Profile > Profile Project from the main menu.
Click Memory in the left pane of the Select Task window to expand the button.
Click Create Custom.
Type a name for the configuration.
Select the initial settings for the configuration and click OK.
You then modify the initial settings when you customize the configuration.
Select one of the following profiling options.
Quick
Advanced
Select any additional options in the Basic Settings pane.
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.
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."
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.
VM Telemetry and VM Telemetry Overview. The VM Telemetry window displays high-level data on thread activity and memory heap and garbage collection in the VM. The VM Telemetry Overview window displays smaller versions of the graphs that are presented in the VM Telemetry window.
Threads. The Threads window displays detailed information about application thread activity.
Live Results. The Live Results window displays the live data from the running profiling session. The live results displayed depend on the selected profiling task. Note: The Live Results view is not available when you are monitoring an application.
You can open any of these windows by choosing Window > Profiling > window_name from the main menu.
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 () 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 |
Exports the results as a text file. |
Save Current View |
Saves the results as a |
Zoom In |
Increases the detail of the graph. |
Zoom Out |
Decreases the detail of the graph. |
Scale to Fit |
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.
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 ().
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."
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 |
Updates results at short intervals when enabled (default state). When disabled, click Update Results Now to update the results. |
Update Results Now |
Updates the results immediately. |
Run Garbage Collection and Update Results |
Starts garbage collection and updates results. |
Reset Collected Results |
Discards the accumulated profiling results. |
Take Snapshot of Collected Results |
Saves the results as snapshot. The unsaved snapshot is opened in the Source Editor. |
Export to |
Exports the displayed results as a |
Save Current View |
Saves the displayed results as a |
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 () 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."
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.
Open the Live Results or window or snapshot.
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.
Choose one of the following filtering parameters for the term from the drop-down menu:
Starts with
Contains
Ends with
Regular expression
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.
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:
Snapshot. Displays the captured results of a profiling session. The data contained in the snapshot depends upon the profiling task that is running when the snapshot is taken.
Heap. Displays a heap dump. In this view you can examine the contents of the heap.
Image. Displays the current results in a results window. Click Save Current View to Image () in the toolbar to save a
.png
image of the current view.
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.
Command | Function |
---|---|
Save Snapshot to Project |
Saves the snapshot to your project. The snapshot is saved to the profiler directory in |
Save Snapshot to Custom File |
Saves the snapshot file in a location other than to your project. |
Save Current View |
Saves the snapshot file as a |
Find |
Finds the occurrence of a search term. |
Find Next Occurrence |
Finds the next occurrence of a search term. |
Find Previous Occurrence |
Finds the previous occurrence of a search term. |
Compare Snapshots |
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. |
In the Saved Snapshots section of the Profiler window, select your project from the drop-down list.
Double-click a snapshot in the list.
Choose Profile > Compare Snapshots in the main menu.
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.
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 () 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 () to selecting a filter option.
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.
Choose Profile > Load Heap Dump in the main menu.
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."
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:
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.
Click the Classes tab in the Heap window.
Click Compare with another heap dump at the top of the Classes tab.
The IDE opens the Select Heap Dump to Compare dialog box.
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.
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.
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.
Type an OQL query in the Query Editor.
Alternatively, you can select a query in the Saved Queries pane and click Open.
Click Execute in the Query Editor.
The results of the query are displayed in the Query Results pane.
(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.