Page History
...
<config-file> ${indepth.j2ee.home}/config/${indepth.j2ee.server_id}/Custom.xml</config-file>
Enabling an additional configuration file
The following procedure describes how you can enable an additional configuration file.
...
<config-file> JNDI.xml
</config-file>
Adding your own custom instrumentation configuration file
The following procedure describes how you can add your own custom instrumentation configuration file.
...
3. Modify the new XML configuration file to include the interfaces, classes, and methods you want to instrument. See the next section for more information.
About custom instrumenter configuration
Precise for J2EE allows you great flexibility in instrumenting Java applications. You can instrument specifically named packages, interfaces, classes, and methods. In addition, you can instrument all classes in a package or all methods in a class using the wildcard character. Sub-elements of <instrumenter-config> also allow you to target the behavior of methods so that you can instrument all calls to a method as well as all calls the method makes, or calls from a specific method to another specific method. Precise for J2EE instrumentation also takes advantage of various Java language properties, allowing you, for example, to instrument all classes that extend a common subclass or interface, or to instrument classes and methods marked with a runtime-visible annotation.
...
public void stop(boolean force) { }
}
About instrumenting interfaces
Instrumentation can be applied to methods in abstract and concrete classes that implement specific interfaces.
About instrumenting methods in implementations of an interface
The <custom-config> element can be used to cause instrumentation to be applied to methods of abstract and concrete classes that implement an interface.
...
• RecoverableTaskAdapter.stop(boolean)
However, instrumentation is not applied to the following methods:
...
• RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method was not declared in the Task interface
About restricting instrumentation to methods that match a signature
The <params> element can be included within a <method> element to restrict instrumentation to a method that is based on a signature. See “About method signature matching” on page 218.
...
• RecoverableTaskAdapter.stop() because the method does not match the specified signature of (boolean) See “About method signature matching” on page 218.
About extending instrumentation to interfaces matching a wildcard
Inheritance is not considered when wildcards are used with <class-name> element. It is not possible to use wildcards to cause instrumentation to be applied to all abstract or concrete class's that implement interface's that match a wildcard pattern.
...
See “About using the wildcard character *” on page 219.
About extending instrumentation to methods that match a wildcard
Wildcards can be used in the <name> element.
...
• RecoverableTaskAdapter.stop(boolean) because the method does not match the signature of ()
About extending instrumentation to methods that are declared in extending interfaces
By default, instrumentation is restricted to methods that are declared in the matching interface. The <apply-to-subtypes> element can be used to extend instrumentation to apply to methods that are declared in extending interfaces.
...
• RecoverableTaskAdapter.stop(boolean) because the method does not match the specified wildcard pattern of sta*
About extending wildcards to apply to methods that are declared in implementations
By default, instrumentation is restricted to methods that are declared in the matching interface. The <apply-to-implementations> element can be used to extend instrumentation to apply to methods that are declared in abstract and concrete classes that implement the matching interface.
...
• RecoverableTaskAdapter.stop(boolean) because the method does not match the specified wildcard pattern of sta*
About instrumenting classes
Instrumentation can be applied to methods in abstract and concrete classes.
About instrumenting methods in abstract and concrete classes
The <custom-config> element can be used to cause instrumentation to be applied to methods of abstract and concrete classes.
...
• RecoverableTaskAdapter.recover(RecoverableTaskContext) because the method was not declared in the AbstractTask class
About restricting instrumentation to methods that match a signature
The <params> element can be included within a <method> element to restrict instrumentation to a method that is based on signature.
...
• RecoverableTaskAdapter.stop() because the method does not match the specified signature of (boolean) See “About method signature matching” on page 218.
About extending instrumentation to classes matching a wildcard
Inheritance is not considered when wildcards are used with a <class-name> element. It is not possible to use wildcards to cause instrumentation to be applied to all abstract or concrete classes that extend classes that match a wildcard pattern.
However, wildcards can be used to apply instrumentation to all abstract or concrete classes whose names match the wildcard pattern that is specified in the <class-name> element.
About extending instrumentation to methods that match a wildcard
Wildcards can be used in the <name> element.
...
• RecoverableTaskAdapter.stop(boolean) because the method does not match the specified signature of ()
About extending instrumentation to methods that are declared in extending classes
By default, instrumentation is restricted to methods that are declared in the matching class. The <apply-to-subtypes> element can be used to extend instrumentation to apply to methods that are declared in extending classes.
...
• RecoverableTaskAdapter.stop(boolean) because the method does not match the specified wildcard pattern of sta*
About instrumenting using annotations
Instrumentation can be applied to classes and interfaces that are annotated with a specific annotation
About instrumenting annotated classes and interfaces
The <annotation-name> element can be added to the <java-class> element to cause instrumentation to be applied to classes that are annotated with a specific annotation.
...
• RecoverableTaskAdapter.stop
About instrumenting annotated methods
The <annotation-name> element can be added to the <method> element to cause instrumentation to be applied to methods that are annotated with a specific annotation.
...
Based on these rules, custom-type instrumentation is applied to the following methods:
• AbstractTask.start
About instrumenting annotated methods in implementing or inheriting classes
The <apply-to-subtypes> element can be added to the <method> element along with the <annotation-name> element, to cause classes that override or implement an annotated method to be instrumented.
...
• RecoverableTaskAdapter.start
About instrumenting only classes that are not assignable to a class or interface
The < not-assignable-to> element can be added to the <java-class> element to prevent the rule from being applied to classes that are assignable to specific types.
...
Based on these rules, custom-type instrumentation is applied to the following methods:
• AbstractTask.start
About instrumenting all calls from a method
Instrumentation can be applied to all calls from methods that match criteria specified in a <java-classes> element. This instrumenter configuration file causes instrumentation to be applied to all calls from the methods that match the <java-classes> element.
...
The rules that apply to the <java-classes> element that is documented in preceding sections are applied when it is used inside the <all-calls-from-method> element.
About instrumenting calls to methods
The <all-calls-to-method> element can be used to apply instrumentation to all calls to specific methods.
...
The <invoked-method> represents a fully-qualified method name. The portion of the <invoked-method> after the last dot (“.”) is considered to be the method name, and the portion of the <invoked-method> before the last dot is considered to be the class name. When you use wildcards, it is important to use a wildcard pattern that fits the scheme described. For example, the wildcard pattern *.set* matches all methods whose name starts with set of all classes, and xmp.task.*.* matches all methods in all classes whose name starts with xmp.task.
The <invoked-method> may also include a method signature. The method signature should follow these rules:
...
• The method signature may include wildcards.
About preventing instrumentation for classes, methods, and calls to methods
Instrumentation can be prevented for specific packages and sub-packages, classes, methods, or calls to methods. The <ignore-config> element in instrumenter configuration files is used to illustrate how to prevent instrumentation from being applied to specific packages and sub-packages, classes, method, or calls to methods. See About instrumenter configuration file reference.
As with the <custom-config>, <all-calls-from-method>, <all-calls-to-method>, and <calls-from-method-to-method> elements, the <ignore-config> element can be placed in its own instrumenter configuration file. The examples should be considered to imply that the <ignore-config> element must be included in an instrumenter configuration file that contains other instrumentation directives.
About preventing instrumentation for all methods of classes in a package and sub-packages
The <java-classes> element can be used within an <ignore-config> element to prevent instrumentation from being applied to all methods of classes in a package and sub-packages using wildcards in the <class-name>.
...
• RecoverableTaskAdapter.stop(boolean)
About preventing instrumentation for methods of a class
The <java-classes> element can be used within an <ignore-config> element to prevent instrumentation from being applied to some or all methods of abstract or concrete classes, or to all methods of a class in a specific package and its sub-packages.
...
• RecoverableTaskAdapter.stop(boolean)
About preventing instrumentation for calls from a method
The <all-calls-to-method> element can be used within an <ignore-config> element to prevent instrumentation from being applied to all calls to specific methods.
...
</ignore-config>
</instrumenter-config>
About preventing instrumentation for calls to a method
The <invocation-relationship> element can be used within an <ignore-config> element to prevent instrumentation from being applied to calls to specific methods from specific calling methods.
...
</ignore-config>
</instrumenter-config>
About instrumenting calls to EJB business method implementations
The J2EE specification does not require that an EJB implementation implement the remote interface directly. Application servers typically generate a skeleton that implements the remote interface directly and delegates calls to the EJB implementation.
Because there is no direct relationship between an EJB implementation and the remote interface, it is difficult to instrument the business methods of an EJB implementation without first identifying the remote interfaces and then manually instrumenting the methods.
About the Calls to EJB instrumentation feature
The “Calls to EJB implementations” instrumentation feature adds a configurable extension to the instrumenter to allow calls to EJB implementations to be instrumented.
...
implementationMarkerInterface Any Number Identifies the classes that must be implemented by calls with a matching name and signature.
Applying instrumentation using the "Calls to EJB" instrumentation feature
The following procedure describes how to apply instrumentation using the "Calls to EJB" instrumentation feature.
...
Figure 18-1 Instrumenter Configuration
About the master configuration file
Instrumentation for each monitored JVM is configured from a master configuration file. The master configuration file, InstrumenterConfigList.xml, contains references to instrumenter configuration files that contain specific rules that are used to determine where and how to apply instrumentation to a monitored JVM.
...
• ${indepth.j2ee.jvm_id} expands to the JVM ID (with a sequence number)
About the instrumenter configuration files
Instrumenter configuration files contain specific rules that are used to determine where and how to apply instrumentation. There are several default instrumenter configuration files located in the
...
SmartuneInstrumentation.xml Optional SmarTune instrumentation for servlet include and session analysis
About the structure of instrumenter configuration files
The instrumenter configuration files have the following general structure:
...
See “About calls from method to method instrumentation configuration” on page 216. See “About ignore instrumentation configuration” on page 217.
About custom instrumentation configuration
The <custom-config> element has the following structure:
...
</java-classes>
</custom-config>
About all calls to method instrumentation configuration
The <all-calls-to-method> element has the following structure:
...
</methods>
</all-calls-to-method>
About all calls from method instrumentation configuration
The <all-calls-from-method> element has this structure:
...
</java-classes>
</all-calls-from-method>
About calls from method to method instrumentation configuration
The <calls-from-method-to-method> element has this structure:
...
See “About method signature matching” on page 218.
About ignore instrumentation configuration
Use the <ignore-config> element to configure rules that are used to determine when to prevent instrumentation from being applied to all methods in specifically matched classes or packages, to specifically matched methods, or to specifically matched calls to methods.
...
The <name> element must represent a fully qualified method name. The portion of the <name> element after the last dot (“.”) is considered to be the method name, and the portion of the <name> element before the last dot is considered to be the class name. When you use wildcards, it is important to use a wildcard pattern that fits the scheme described. For example, the wildcards pattern *.* matches all methods of all classes.
About common instrumenter configuration matching techniques
Common instrumenter configuration matching techniques are method signature matching and using the wildcard character *.
About method signature matching
The <params> element configures rules that are used to match method signatures for processing by the instrumenter. The <params> element has the following structure:
...
<invoked-method> com.acme.shared.comm.Connector.<init> (java.lang.String,int[][]) </invoked-method>
About using the wildcard character *
In addition to using specific names to reference items such as classes, interfaces, and methods, for instrumentation, you can also use the wildcard character * to instruct Precise for J2EE to instrument all classes, methods, or packages within the scope of the instruction.
...
*$* xmp.task.AbstractTask$1 xmp.server.Main xmp.task.AbstractTask xmp.task.util.TaskUtilities
NOTE Use wildcard characters only when discovering the methods to instrument. Otherwise, it may result in instrumentation that does not yield meaningful performance metrics but introduces unwanted overhead. Do not implement wildcarded instrumentation in production environments.
Including application server classes in Leak Seeker instrumentation
To obtain information on collections and arrays with the most elements, Leak Seeker instruments all user application classes but, by default, excludes application server classes. In special circumstances, you may want Leak Seeker to collect information on application server classes as well.
...