Specifying profiling criteria

Profiling Java 5.0 (Java 1.5) and higher Java virtual machine based applications

Java Profiler support for profiling Java 5.0 and higher JVMs is based on the Java Virtual Machine Tool Interface (JVMTI) introduced in J2SE 5.0, which replaces the earlier experimental Java Virtual Machine Profiler Interface (JVMPI). The Profiler uses a substantially different approach from the JVMPI-based Profiler. Instead of relying on VM-generated events for monitoring application behavior (such as method entry and exit events, object allocations and so on) it uses Byte Code Instrumentation (BCI) to inject small pieces of code which track the application execution. This technique allows for efficient monitoring of specific parts of the application, without imposing a noticeable overhead on other parts of the application that are not being monitored. This approach is easy to use and scales well for large applications.

Execution Profile of an Application

The Java profiler can be used to profile any Eclipse plug-ins, Eclipse RCP applications, J2EE applications, and Java applications. To profile an application select Profile Configurations... from the Profile drop down menu or the Run menu. This opens the profile launch configuration window.

Perform the following steps:

• Create a new launch item of type Java Application.
• Select the Profile Settings tab from the profile launch configuration.
• Select Execution Time Analysis.
• Click Edit Options to set any desired filter.

Memory (Object allocation) analysis

To perform an Object Allocation analysis or Memory analysis (Heap), perform the following steps:

• Profile your application by selecting Profile Configurations... from the Profile drop down menu or the Run menu.
• Select the Profile Settings tab from the profile launch configuration.
• Select Memory Analysis.
• If you would like to track the source of your object allocation, click Edit Options and check the Track object allocation sites check box.

Thread Profile of an Eclipse Application

To perform a thread profile of your application, perform the following steps:

• Select Profile Configurations... from the Profile drop down menu or the Run menu.
• Select the Profile Settings tab from the profile launch configuration.
• Select Probe Insertion.
• Click Edit Options to select a probe by Name.

You can set profiling options for the Java Profiling data collector or the selected analysis types, by highlighting the entity and clicking Edit Options.

Follow the steps below to set profiling options on the Java Profiling data collector:

1. Highlight Java Profiling and click Edit Options.
2. By default, all relevant classes are profiled. You can change this on the Filter Set page by clearing Automatically determine filtering criteria and then specifying the filter set to be applied to your profiling session. Under the Select a filter set list, click Add a Generic Filter to add the desired filter set. Alternatively, you can preview and customize the default project based filter by clicking Customize Auto-Filter.
3. You can also specify the filtering criteria manually. Under Contents of selected filter set, click Add to add packages for which you want to collect data. The Add Filter dialog opens. An asterisk * can be used as a wildcard in a pattern when specifying package or method names.
   1. When entering a pattern for the package or method name, the pattern must be specified in one of three ways:
      1. A pattern with no wildcards. For example, org.eclipse.tptp.
      2. A pattern with a wildcard at the beginning. For example, *.sample.myapplication.
      3. A pattern with a wildcard at the end. For example, org.eclipse.*.

   2. Certain classes will always be visible in the profiling views regardless of the filter settings. The profiling agent will always collect data for objects or classes that are associated with the task being examined while collecting data specific to the task. For example, you specify a filter to collect data for a single class MyUserClass, and specify another filter to exclude the java.lang.* classes. When an instance of MyUserClass is loaded though, it has an associated class definition that gets loaded. This class definition has an associated class object, which is in turn of type java.lang.Class. This results in data collection for the java.lang.Class in addition to the MyUserClass class.

      This behavior applies to threads as well. The java.lang.Thread class will always show up in the Profiling views because the profiling agent tracks all running threads; and therefore, collects data for objects or classes associated with those threads.

   3. Filter configuration determines the scope of the data collection. Package of target application should be applied in filter configuration. For example, mypkg* * INCLUDE. It is highly not recommended to use an all inclusive set as a filtering criteria. For example, '* * INCLUDE'.
4. Specify the Package, Class, or Method Name that you wish to filter. If you want see the profiling data for these packages, classes, and methods, select Include from the Rule drop down list. If you want to exclude these packages, classes, and methods from the profiling data, click Include under the Rule column for the package, and change it to Exclude.
5. Click OK. The filter criterion is added to the contents list.
6. Click Finish.
7. You can also reuse the filtering criteria by exporting and importing the filter set.
   1. To export a filter set, select the filter set you want to export from the filter set list and click Export. Follow the wizard to choose the export file format, and then specify the export location. Click Finish to export the filter set.
   2. To import a filter set, select the filter set you want to import from the filter set list and click Import. Follow the wizard to choose the file format, and then specify the import file location. Click Finish to import the filter set into the workspace.
   Note: Currently, the filter set supports two file types, xml and txt.

   XML files (.xml)

   XML files will keep all necessary information about the filter set including content and metadata of the filter. Upon import, the metadata will be used to populate the basic filter properties (like the filter name, key, ID, and creation time).

   Plain text files (.txt)

   Plain text files only store the content of the filter set, without metadata. Plain text profiling filters are interchangeable with the profiling filters of Rational Agent Controller (RAC) because they follow the same storage conventions.

8. To start the profiling agent automatically when the application is launched, check the Automatically start monitoring when application is launched check box.
   Note: It is strongly recommended for large applications that are not required to be monitored during the initialization phase (for example, launching an instance of the workbench) that you accept the default and leave the Automatically start monitoring when application is launched check box unchecked. This will result in the profiling agent being started in pause mode so that data is not collected during the initialization stage of the application.
9. Click Finish.
10. Click Apply to save the changes.

Similarly, you can set the options of an analysis type by highlighting it and selecting Edit Options.

Profiling sample data

You can specify the project, and the monitor to use for your profiling session. You can also write the profiling data to a file.

1. In your profiling configuration, select the Destination tab.
2. Specify the Profiling Project that you want to use for your profiling session.
3. Specify the Monitor that you want to use.
4. If you want to save the profiling data to a file, select Send profiling data to a file and specify the file name in the Profiling file input box.
5. Click Apply to save the changes.
6. Click Profile to start profiling your application.
   Note: When filtering, only the first applicable filter is applied. When you are specifying filters, ensure that you declare the most specific filter criteria first.