Probe target specifications

A target specification indicates the classes and methods to which the probe should be applied.

The target specification is optional. When no target is specified, the probe will be applied to all classes that are processed by the instrumentation engine.

The target specification lets you create filter rules to include or exclude methods from instrumentation based upon patterns that are matched against the package, class, and method name, plus the method's signature. The patterns can contain wildcards, where "*" matches zero or more characters.

If a target's wildcard patterns match a method's package, class, name and signature, the type property determines whether the method is instrumented (include) or not (exclude). If the patterns do not match a method's package, class, name and signature, by default, the method is instrumented.

The target includes the following properties:
Property Description
type Required. The type property determines whether or not a probe is applied to a target method. Specify include to apply the probe to classes and methods that match the wildcard patterns, exclude to exclude them.
package Optional. Specify a wildcard pattern to match against the package portion of class names. For example: java.util* matches every class in the java.util package and its subpackages. If not specified, the default value is *.
className Optional. Specify a wildcard pattern to match against class names. If not specified, the default value is *.
method Optional. Specify a wildcard pattern to match against method names. If not specified, the default value is *.
signature Optional. Specify a wildcard pattern to match against a method's signature. (The signature is the string representing the method's arguments and return type.) Use the Java internal format for method signatures. For example: (Ljava/lang/Object;)D is the signature of a method that takes an Object as a parameter and returns a double. This wildcard pattern can be used to distinguish among overloaded methods. If not specified, the default value is *.

Notes:

  • A probe can have multiple target specifications containing successive targeting rules. To apply a probe only to certain methods, first specify the methods that you want to include, and then add a final target specification package=* className=* method=* signature=* type=exclude.
  • Package and class names that you specify are also checked against the package and class names of any interfaces that a class implements. For example, java.util.HashMap implements the interface java.util.Map. If a probe targets the package java.util, the class name Map, and the method name size, the probe will be applied to java.util.HashMap.size(), and to the size method of any other class that implements the Map interface.
  • Pattern matching does not consider inheritance relationships. If class Derived extends class Base, and a probe targets Base.run(), the probe will not automatically be applied to Derived.run().
  • If the package pattern in a target specification is a single period character ("."), it represents the global, unnamed Java package. This lets you explicitly target classes in the global package.
  • Callsite probes match target patterns and rules against the package, class, name and signature of a called method. The matching is done against the called method as it was known at compile time; that is, against the statically known class and method names, not the actual methods that will be called due to inheritance and virtual functions. If the call is done through an interface reference, the interface name must match.
Example:

To specify a target, select Target in the tree pane of the Probes page, and click Add, then Edit in the editing pane.

This example applies the probe only to methods whose names start with Get in classes whose names end with Proxy in the package com.example. Target entries of types include and exclude; the exclude target entry uses asterisk wildcards to exclude everything; the include entry specifies the exact methods to be targeted. All other classes and methods are excluded from instrumentation.