IBM Tivoli Composite Application Manager for Application Diagnostics, Version 7.1.0.1

Customize lock analysis

By default, if lock analysis is enabled, lock acquire and release requests for all application classes are Byte-Code-Instrumented. With default settings, lock contention information is provided in MOD L2 and MOD L3. You may configure the data collector to modify the lock information provided on the different MOD levels, and to exclude some classes from BCI for lock analysis.


Configure lock analysis information for MOD levels

The following properties in the data collector properties file control the lock analysis information provided by the data collector.

internal.lockanalysis.collect.Ln.lock.event

This property whether lock acquisition/release events are collected and passed to the Managing Server. (If the Managing Server is not used, this parameter is ignored). The variable n can represent MOD L1, L2 or L3. Possible values are true or false. In most cases, the recommended setting at all levels is false as there is little benefit in displaying lock acquisition events if they do not involve contention; lock contention events are collected separately. However, you may wish to enable lock event collection for some development tasks.

Example: 

internal.lockanalysis.collect.L1.lock.event = true

internal.lockanalysis.collect.Ln.contend.events

This property controls whether lock contention events are collected and passed to the Managing Server. (If the Managing Server is not used, this parameter is ignored). The variable n can represent MOD L1, L2 or L3. Possible values are true, false or justone.

True indicates contention records are collected. For each lock acquisition request that results in contention, a pair of contention records are written for each thread that acquired the lock ahead of the requesting thread. False indicates contention records are not written. Justone indicates contention records are written, however, a maximum of one pair of contention records are written for each lock acquisition request that encounters contention, regardless of how many threads actually acquired the lock prior to the requesting thread.

Set this property to true enables you to determine whether a single thread is holding a lock for an excessive time, or if the problem is due to too many threads all attempting to acquire the same lock simultaneously.

The recommended setting at L1 is false. The recommended setting at L2 is justone, this enables you to collect just one pair of contention records for each lock acquisition that encountered contention. The recommended setting at L3 is true, in order to identify every thread that acquired the lock ahead of the requesting thread; this setting has a high performance cost, which is common for L3 monitoring, and the user should only enable L3 for a limited time to reduce performance impact.

Example: 

internal.lockanalysis.collect.L2.contend.events = justone

internal.lockanalysis.collect.Ln.contention.inflight.reports

This parameter controls whether data is collected for the Lock Contention report, available in the Visualization Engine of the Managing Server. (If the Managing Server is not used, this parameter is ignored). The variable n can represent Mod L1, L2 or L3. Possible values are true or false. The recommended setting at L1 is false. The recommended setting at L2 and L3 is true.

Example: 

internal.lockanalysis.collect.L3.contention.inflight.reports = true


Set classes for lock analysis instrumentation

To set classes for lock analysis instrumentation:

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

  2. Modify the lockingClasses specification in the file.

    This element defines the classes for which lock requests will be Byte-Code-Instrumented. By default, all lock requests in all application classes are selected. By modifying this tag, you can implement a more granular selection, although within a class all lock requests are Byte-Code-Instrumented. Multiple lockingClasses tags can be specified.

    The lockingClasses element can include wildcard characters. The following section describes how the wildcard characters work:

    • 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 locking class name begins with an exclamation point (!), any classes matching the classes identified in the tag are specifically excluded from BCI for lock analysis. This is useful for indicating that all classes are to be Byte-Code-Instrumented except for those classes that are specifically excluded.

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

    • Only classes that begin with Cus or Sup should be Byte-Code-Instrumented for lock analysis.

    • The Supplier class should not be Byte-Code-Instrumented for lock analysis.

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

       <aspect>
     <type>application</type>
     <name>com.ibm.tivoli.itcam.toolkit.ai.aspectj.apptrace.CaptureLock</name>
     <enabledProperty>
             com.ibm.tivoli.itcam.toolkit.ai.enablelockanalysis</enabledProperty>
     <defaultEnabled>true</defaultEnabled>
     <lockingClass>com.mycompany.myapp.Cus*</lockingClass>
     <lockingClass>com.mycompany.myapp.Sup*</lockingClass>
     <lockingClass>!com.mycompany.myapp.Supplier</lockingClass>
  </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 (see The Toolkit properties file), set the property am.camtoolkit.gpe.customxml.lock 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.enablelockanalysis=true

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

      1. In the toolkit custom properties file (see The Toolkit properties file), set the property am.camtoolkit.gpe.customxml.lock to the path and name for 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.enablelockanalysis=true


Parent topic:

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

+

Search Tips   |   Advanced Search