IBM Tivoli Composite Application Manager for Application Diagnostics, Version 7.1.0.1

Customize method profiling and method entry and exit tracing

Method profiling and method entry and exit tracing are enabled together and use the same call interceptions. Method profiling is performed at MOD L2, and method entry and exit tracing is performed at MOD L3. You may configure the data collector to change the thresholds and limits for method profiling, and to exclude some classes and methods for method entry and exit tracing.


Customize thresholds for Level 2 method profiling

The data collector will only instrument method profiling data when the method exceeds certain thresholds of CPU time and real ("wall clock") time usage. There are also limits on the total number of methods, stack size, and running thread size. You can customize the thresholds and limits.

The following properties in the data collector properties file control the thresholds and limits for method profiling.

am.mp.cpuThreshold

Default 30 milliseconds. Only the methods which take at least the minimum amount of CPU time specified in this property are captured for method profiling data. This avoids unnecessary clutter. Generally, methods with greater than the value specified in this property are considered useful. Customers can reduce or increase this value if needed.

am.mp.clockThreshold

Default 30 milliseconds. Only the methods which take at least the minimum amount of wall clock time specified in this property are captured for method profiling data. This avoids unnecessary clutter. Generally, methods with greater than the value specified in this property are considered useful. Customers can reduce or increase this value if needed.

am.mp.leagueTableSize

Default 1000. This is the maximum number of methods that are monitored for method profiling data. Customers can reduce or increase this value if needed. Decreasing it will help in reducing memory requirements.

am.mp.methodStackSize

Default 100. This is the maximum stack size of any running thread that is recorded in method profiling.


Set classes and methods for Level 3 method entry and exit tracing

By default, method entry and exit tracing on MOD L3 is performed for all classes and methods. To set specific classes and methods for method entry and exit analysis:

  1. Make a copy of the DC_home/itcamdc/etc/method_entry_exit.xml file in a temporary location. Open the copy in a text editor.

  2. Modify the parameters in the file. The following table describes the parameters you can modify:


    Parameters for the Level 3 method entry and exit analysis configuration file

    Tag name Description
    methodSelection Defines the classes and methods to be modified. By default, all classes and methods are selected. By modifying the className and methodName tags within the methodSelection tag, you can implement a more granular selection.

    Each methodSelection tag must contain exactly one className tag, and one or more methodName tags. Multiple methodSelection tags can be specified.

    className Name of a class or classes to be modified. Each methodSelection tag must contain exactly one className tag.
    methodName Identifies a method or method within the class or classes identified by the className tag to be modified for entry/exit tracing. Each methodSelection tag must contain one or more methodName tags.

    Both className and methodName tags can include wildcard characters. The following section describes how the wildcard characters works:

    • Asterisk (*) stands for zero or more occurrences of any character when used by itself. When embedded within a sequence of characters (for example, java.*.String), it matches zero or more occurrences of any character except the package separator (.).

    • Two periods (..) can be used to specify all sub-packages. It matches any sequence of characters that starts and ends with the package separator (.).

      For example, java..String matches java.lang.String and com.ibm..* matches any declaration beginning with com.ibm.

    • If the method name begins with an exclamation point (!), any methods that match the method name are specifically excluded from BCI for entry and exit tracing. This is useful for indicating that all methods within a class or group of classes are to be Byte-Code-Instrumented except for those methods that are specifically excluded.

    For example, an application with a package name of com.mycompany.myapp has the following requirements:

    • Within the Customer class, all methods should be Byte-Code-Instrumented.

    • Within the Supplier class, all methods should be Byte-Code-Instrumented except for those methods beginning with the get or set.

    The following example shows the contents of the customized method_entry_exit.xml file that accomplishes this:

      <aspect>
        <type>application</type>
        <name>com.ibm.tivoli.itcam.toolkit.ai.aspectj.apptrace.EntryExitAspect</name>
        <enabledProperty>
               com.ibm.tivoli.itcam.toolkit.ai.methodentryexittrace</enabledProperty>
         <defaultEnabled>true</defaultEnabled>
         <methodSelection>
              <className>com.mycompany.myapp.Customer</className>
              <methodName>*</methodName>
         </methodSelection>
         <methodSelection>
              <className>com.mycompany.myapp.Supplier</className>
              <methodName>!get*</methodName>
              <methodName>!set*</methodName>
         </methodSelection>
      </aspect>

  3. Complete one of the following steps:

    • Save the file in the DC_home/runtime/app_server_version.node_name.server_name/custom directory, then complete the following steps:

      1. In the toolkit custom properties file set the property am.camtoolkit.gpe.customxml.L3 to the name (without path) of the file you modified in Step 2.

      2. In the same toolkit custom properties file, set the following property to true:
        com.ibm.tivoli.itcam.toolkit.ai.methodentryexittrace=true

    • Save the file in any directory on the monitored host, and then complete the following steps:

      1. In the toolkit custom properties file set the property am.camtoolkit.gpe.customxml.L3 to the path and name for the file you modified in Step 2.

      2. Set the following property to true:
        com.ibm.tivoli.itcam.toolkit.ai.methodentryexittrace=true


Parent topic:

Lock analysis, memory leak analysis, and method profiling and tracing