Custom Instrumentation with CA APM

Document created by Hiko_Davis Employee on Feb 10, 2015Last modified by Hiko_Davis Employee on Aug 23, 2017
Version 10Show Document
  • View in full screen mode

NOTE: A big "Thank You!" to jakbutler for putting the original content together. There's a lot of stuff here, so make sure to thank him!

 

Metric Names

When creating custom probe definitions, it is often necessary to specify the path and name of the resulting metrics. This will control how the collected data is displayed to an end-user in the Introscope Workstation. The following examples describe three ways to specify the name and location of a metric at different levels of the metrics tree.

  • metric-name—the metric appears immediately inside the agent node.
  • resource:metric-name—the metric appears inside one resource (folder) below the agent node.
  • resource|sub-resource|sub-sub-resource:metric-name—the metric appears more than one resource (folder) level deep below the agent node. Use pipe characters (|) to separate the resources.

Note: Pay attention to which Tracer Types you are using! Some of them require only the resource path, not the actual metric name but allow you to override while others, like the BlamePointTracer, produce multiple metrics and therefore should not have a metric name, only a resource path.

 

Best Practices

  • Group related probes under the same parent metric group. In other words, if you are instrumenting related classes or methods within the same framework, such as the Messaging Client frame work, group them under the same parent metric group, e.g. "Messaging" or "Messaging|Client".
  • When specifying static resource or metric names, try to use values that will be recognizable to Support or Development staff.

 

Metric name keyword-based substitution

Keyword-based substitution allows runtime substitution of values into the metric or resource names.The parameters in the metric name in the tracer are substituted at runtime for the actual values into the metric name. This feature can be used with any directive.

 

{method}

  • Name of the method being traced

{classname}

  • Runtime class name of the class being traced

{packagename} or {namespace}

  • Runtime package name of the class being traced

{packageandclassname} or {namespaceandclassname}

  • Runtime package and class name of the class being traced

Note: If Introscope processes a class which does not have a package, it will replace {packagename} with the string "<Unnamed Package>".

 

Example 1

If the metric name for a tracer in the pbd file is:

"Custom Instrumentation|{packagename}|{classname}|{method}:Response Time (ms)"

and the tracer is applied to method myMethod with a runtime class of myClass that is in package myPackage, the resulting metric name would be as follows (⇒ signifies a level of the metric tree in the Introscope Workstation):

Agent Name  ⇒  Custom Instrumentation  ⇒  myPackage  ⇒  myClass  ⇒  myMethod  ⇒  Response Time (ms)

Note: The full metric path from within the Introscope workstation would be as follows:

Custom Instrumentation|myPackage|myClass|myMethod:Response Time (ms)

 

Example 2

If a tracer with a metric name in the .pbd file of

"Custom Instrumentation|{packageandclassname}|{method}:Response Time (ms)"

was applied to the same method, the resulting metric name would be as follows (⇒ signifies a level of the metric tree in the Introscope Workstation):

Agent Name  ⇒  Custom Instrumentation  ⇒  myPackage.myClass  ⇒  myMethod  ⇒  Response Time(ms)

Note: The full metric path from within the Introscope workstation would be as follows:

Custom Instrumentation|myPackage.myClass|myMethod:Response Time (ms)

 

Metric names with parameters

You can create a single-method tracer that creates a metric name based on parameters passed to a method using the TraceOneMethodWithParametersOfClass keyword, using this format:

TraceOneMethodWithParametersOfClass: <class-name> <method> <tracer-name> <metric-name>

Important! If you are unclear about what string the parameter will be converted to, do not use it in the metric name.

When creating a “WithParameters” Tracer in Introscope, you will use the JNI notation of the method signature. For instructions on writing this signature, see the JNI Signatures page. Certain tracers, like the custom ConditionalMethodTraceIncrementor tracer, require that the WithParameters and JNI notation be used.  Please refer to the Tracer Types page for more details.

 

Example 3

A Web site uses a class named order, with a method named process. The method has parameters for different kinds of orders, either book or music. The method looks like this:

public class com.yourco.order {

     public void process (java.lang.String orderType);

}

You can create a tracer like this:

TraceOneMethodWithParametersOfClass: order process(LJava/lang/string;)V MethodTimer "Custom Instrumentation|Order|{0}Order:Average Response Time (ms)"

This tracer produces metrics like the bellow (⇒ signifies a level of the metric tree in the Introscope Workstation):

Agent Name  ⇒  Custom Instrumentation  ⇒  Order  ⇒  BookOrder  ⇒  Average Response Time (ms)

Note: The full metric paths from within the Introscope workstation would be as follows:

Custom Instrumentation|Order|BookOrder:Average Response Time (ms)

Other "WithParameters" directives are available on the Directives page.

 

^Back to Top

Tracer Types

When a Directive requires the <Tracer> parameter, you have the ability to specify one of the below tracers. Different tracers produce different kinds of metrics regarding the execution of the traced method(s), such as a timer, the execution rate per second or interval, or a count of invocations.

Note: If default metrics names are not listed for a tracer, a custom metric name must be provided as part of the "<Investigator Tree Path>" argument in the directive. Metric names also support keyword-based substitution. Additionally, some tracers, like the BlamePointTracer, generate multiple metrics and do not require specifying metric names.

 

Common Tracer Types

Tracer NameDefinition

BlamePointTracer

The BlamePointTracer is the easiest tracer to use and the most commonly used. It produces the "Big 5" metrics: Average Response Time (ms), Responses Per Interval, Concurrent Invocations per Interval, Errors Per Interval, and Stall Count. This tracer also captures the Blame metrics (component interactions) for use in Transaction Traces.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count

Note: BlamePointTracer will always report Errors as 0. The ExceptionErrorReporter must be used in conjunction with the BlamePointTracer to track errors.

ConcurrentInvocationCounter

The ConcurrentInvocationCounter tracer type reports on the number of currently executing threads in a particular method. If you want to see where your threads are currently executing, then this is the appropriate tracer type. One especially useful tactic is to create concurrency metrics on all major application components so as to be able to spot bottleneck or resource contention anomalies downstream from them.
Default Metric Name: Concurrent Invocations or Concurrent Method Invocations 

MethodTimer / BlamedMethodTimer

The MethodTimer tracer reports the average response time in milliseconds for an instrumented method. Note that this measurement is on elapsed time, not CPU time. If you need to know how long your methods are taking to execute, then this is the appropriate tracer type. The Blamed variant, BlamedMethodTimer tracer should be used if you also want to capture Blame metrics (component interactions).
Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)

MethodRateTracer / BlamedMethodRateTracer

The MethodRateTracer tracer reports the number of method invocations per second. If you want to know how many times your methods are executing in one second, then this is the appropriate tracer type. The Blamed variant, BlamedMethodRateTracer tracer should be used if you also want to capture Blame metrics. There are also two other kinds of rate tracer types used in specialized circumstances: OverThresholdTracer and UnderThresholdTracer. These tracer types will report the number of invocations per second over (or under) a user defined threshold. If you want to gauge how an application performance compares to service levels, then these are the appropriate tracer types.
Default Metric Name: Responses Per Second or Invocations Per Second

MethodTraceIncrementor / BlamedMethodTraceIncrementor

MethodTraceDecrementor / BlamedMethodTraceDecrementor

The MethodTraceIncrementor and MethodTraceDecrementor tracer types increment/decrement on method invocations and as such, measure simple counts. They can be combined in a pair so as to be able to count arithmetic tallies. If you want to count how many times a particular method has been executed, then the MethodTraceIncrementor is the appropriate tracer type (the reported metric will never fluctuate – it will start at zero and increase by one every time the method is invoked). By combining the MethodTraceDecrementor tracer type with the MethodTraceIncrementor tracer type, one can capture custom metrics that fluctuate. The Blamed variants, BlamedMethodTraceIncrementor and BlamedMethodTraceDecrementor tracer types should be used if you also want to capture Blame metrics.

PerIntervalCounter / BlamedPerIntervalCounter

The PerIntervalCounter tracer type reports the number of method invocations per interval. If you want to know how many times your methods are executing in an interval (as opposed to one second), then this is the appropriate tracer type.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval

StalledMethodTracer

The StalledMethodTracer tracer type reports which methods take too long to execute based on a user defined threshold (in milliseconds). If you want to know if any methods in your application are taking longer than 60 seconds to execute, then this is the appropriate tracer type.
Default Metric Name: Stalled Method Count

 

To Blame or Not To Blame

Many tracers have two versions: a normal version and blamed version. The blamed version of a tracer produces the same metrics as the non-blamed version; however, a blamed tracer will add the traced component to any transaction traces, which helps to show component interaction.

 

All Tracer Types

Tracer NameDefinition
BackendMarkerGenerates 5 separate metrics (listed below) for associated methods or classes. The Errors Per Interval metric will be generated, but will always report a value of 0 (zero) when this Tracer Type is used alone. To generate non-zero Errors Per Interval metric values, also apply ExceptionErrorReporter to associated methods or classes. The Stall Count metric threshold is set by the property introscope.agent.stalls.thresholdseconds in the IntroscopeAgent.profile. Metric naming is automatic. Explicitly identifies methods as Backends metrics, i.e. those that were not automatically identified by Introscope out of the box, as representing calls to backend systems. Participate in the Application Overview grid and heuristics. Generated metrics will appear under the Backends folder and Called Backends folder and are automatically named. The Investigator Tree Path name declaration is "<Resource>", without the explicit ":<Metric>" naming portion. Blame is implicit, but does not apply to Concurrent Invocations. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
BlamedComponentTimerDeprecated.
BlamedConcurrentComponentTimerDeprecated.
BlamedMethodCPUTimerReports the average CPU time (in milliseconds) used during method execution with Blame enabled. This tracer will factor in every method invocation. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
BlamedMethodCPUTimerDifferentInstancesReports the average CPU time (in milliseconds) used during method execution with Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
BlamedMethodCPUTimerDifferentMethodsReports the average CPU time (in milliseconds) used during method execution with Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
BlamedMethodInvocationCounterDeprecated.
BlamedMethodNanoCPUTimerReports the average CPU time (in nanoseconds) used during method execution. This tracer will factor in every method invocation. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Requires Java 5. Blame enabled. Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
BlamedMethodNanoCPUTimerDifferentInstancesReports the average CPU time (in milliseconds) used during method execution. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Requires Java 5. Blame enabled. Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
BlamedMethodNanoCPUTimerDifferentMethodsReports the average CPU time (in milliseconds) used during method execution. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Requires Java 5. Blame enabled. Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
BlamedMethodNanoTimerCalculates the method execution time (in nanoseconds) of methods that have completed during the reported interval. This tracer will factor in every method invocation. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. Requires Java 5. Blame enabled. Supported on Java Agents.
Default Metric Name: Average Response Time (ns)
BlamedMethodNanoTimerDifferentInstancesCalculates the method execution time (in nanoseconds) of methods that have completed during the reported interval. This tracer is applied the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. Requires Java 5. Blame enabled. Supported on Java Agents.
Default Metric Name: Average Response Time (ns)
BlamedMethodNanoTimerDifferentMethodsCalculates the method execution time (in nanoseconds) of methods that have completed during the reported interval. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. Requires Java 5. Blame enabled. Supported on Java Agents.
Default Metric Name: Average Response Time (ns)
BlamedMethodRateTracerCalculates the number of completed invocations per second with Blame enabled. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Second or Invocations Per Second
BlamedMethodRateTracerDifferentInstancesCalculates the number of invocations per second with Blame enabled. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Second or Invocations Per Second
BlamedMethodRateTracerDifferentMethodsCalculates the number of invocations per second with Blame enabled. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Second or Invocations Per Second
BlamedMethodStartTraceDecrementorPerpetual counter that decreases by 1 at the start of a method invocation from another object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedMethodStartTraceIncrementorPerpetual counter that increases by 1 at the start of a method invocation from another object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedMethodTimerCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval with Blame enabled. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)
BlamedMethodTimerDifferentInstancesCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval with Blame enabled. When aggregated for a class, This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)
BlamedMethodTimerDifferentMethodsCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval with Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)
BlamedMethodTraceDecrementorPerpetual counter that decreases by 1 for each completion of a method invocation from another object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedMethodTraceIncrementorPerpetual counter that increases by 1 for each completion of a method invocation from another object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedNormalCompletionMethodTraceDecrementorPerpetual counter that decreases by 1 for each method invocation from another object instance that completes without throwing an exception. Blame enabled. Supported on Java & .NET Agents.
BlamedNormalCompletionMethodTraceIncrementorPerpetual counter that increases by 1 for each method invocation from another object instance that completes without throwing an exception. Blame enabled. Supported on Java & .NET Agents.
BlamedNormalCompletionPerIntervalCounterCounts the number of method invocations that complete without throwing an exception, per time interval. Blame enabled. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
BlamedNormalCompletionPerIntervalCounterDifferentInstancesCounts the number of method invocations that complete without throwing an exception, per time interval. Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
BlamedNormalCompletionPerIntervalCounterDifferentMethodsCounts the number of method invocations that complete without throwing an exception, per time interval. Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
BlamedNormalCompletionSimpleDecrementorPerpetual counter that decreases by 1 for each method invocation that completes without throwing an exception, regardless of whether called from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedNormalCompletionSimpleIncrementorPerpetual counter that increases by 1 for each method invocation that completes without throwing an exception, regardless of whether called from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedOverThresholdPerIntervalCounterCalculates per interval the number of invocations that completed over the specified time threshold (in milliseconds). Blame enabled. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
BlamedOverThresholdPerIntervalCounterDifferentInstancesCalculates per interval the number of invocations that completed over the specified time threshold (in milliseconds). Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
BlamedOverThresholdPerIntervalCounterDifferentMethodsCalculates per interval the number of invocations that completed over the specified time threshold (in milliseconds). Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
BlamedPerIntervalCounterCalculates the number of invocations that completed during the time interval with Blame enabled. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval
BlamedPerIntervalCounterDifferentInstancesCalculates the number of invocations that completed during the time interval with Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval
BlamedPerIntervalCounterDifferentMethodsCalculates the number of invocations that completed during the time interval with Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval
BlamedSimpleDecrementorPerpetual counter that decreases by 1 for each completion of a method invocation, regardless of whether from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedSimpleIncrementorPerpetual counter that increases by 1 for each completion of a method invocation, regardless of whether from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedSimpleStartDecrementorPerpetual counter that decreases by 1 at the start of a method invocation, regardless of whether from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedSimpleStartIncrementorPerpetual counter that increases by 1 at the start of a method invocation, regardless of whether from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedThrownExceptionMethodTraceDecrementorPerpetual counter that decreases by 1 for each exception thrown by a method, caught or not, when called from another object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedThrownExceptionMethodTraceIncrementorPerpetual counter that increases by 1 for each exception thrown by a method, caught or not, when called from another object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedThrownExceptionPerIntervalCounterCounts the number of exceptions thrown by methods, caught or not, per time interval. Blame enabled. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
BlamedThrownExceptionPerIntervalCounterDifferentInstancesCounts the number of exceptions thrown by methods, caught or not, per time interval. Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
BlamedThrownExceptionPerIntervalCounterDifferentMethodsCounts the number of exceptions thrown by methods, caught or not, per time interval. Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
BlamedThrownExceptionSimpleDecrementorPerpetual counter that decreases by 1 for each exception thrown by a method, caught or not, regardless of whether called from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedThrownExceptionSimpleIncrementorPerpetual counter that increases by 1 for each exception thrown by a method, caught or not, regardless of whether called from another object instance or the same object instance. Blame enabled. Supported on Java & .NET Agents.
BlamedUnderThresholdPerIntervalCounterCalculates per interval the number of invocations that completed under the specified time threshold (in milliseconds). Blame enabled. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
BlamedUnderThresholdPerIntervalCounterDifferentInstancesCalculates per interval the number of invocations that completed under the specified time threshold (in milliseconds). Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
BlamedUnderThresholdPerIntervalCounterDifferentMethodsCalculates per interval the number of invocations that completed under the specified time threshold (in milliseconds). Blame enabled. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
BlamePointTracerGenerates 5 separate metrics (listed below) for associated methods or classes. The Errors Per Interval metric will be generated, but will always report a value of 0 (zero) when this Tracer Type is used alone. To generate non-zero Errors Per Interval metric values, also apply ExceptionErrorReporter to associated methods or classes. The Stall Count metric threshold is set by the property introscope.agent.stalls.thresholdseconds in the IntroscopeAgent.profile. Metric naming is automatic. The Investigator Tree Path name declaration is "<Resource>", without the explicit ":<Metric>" naming portion. Blame is implicit, but does not apply to Concurrent Invocations. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
BlamePointTracerDifferentInstancesGenerates 5 separate metrics (listed below) for associated methods or classes. The Errors Per Interval metric will be generated, but will always report a value of 0 (zero) when this Tracer Type is used alone. To generate non-zero Errors Per Interval metric values, also apply ExceptionErrorReporter to associated methods or classes. The Stall Count metric threshold is set by the property introscope.agent.stalls.thresholdseconds in the IntroscopeAgent.profile. Metric naming is automatic. The Investigator Tree Path name declaration is "<Resource>", without the explicit ":<Metric>" naming portion. Blame is implicit, but does not apply to Concurrent Invocations. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
BlamePointTracerDifferentMethodsGenerates 5 separate metrics (listed below) for associated methods or classes. The Errors Per Interval metric will be generated, but will always report a value of 0 (zero) when this Tracer Type is used alone. To generate non-zero Errors Per Interval metric values, also apply ExceptionErrorReporter to associated methods or classes. The Stall Count metric threshold is set by the property introscope.agent.stalls.thresholdseconds in the IntroscopeAgent.profile. Metric naming is automatic. The Investigator Tree Path name declaration is "<Resource>", without the explicit ":<Metric>" naming portion. Blame is implicit, but does not apply to Concurrent Invocations. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
BlamePointTracerLiteUnsupported Community Download. Generates no metrics. When applied, classes and methods will participate in Transaction Traces. Blame is implicit. This tracer will factor in every method invocation. The Directive statement will still require the "<Resource>" declaration. Works with Java Agents.
CEMTracerBusiness Processes|<CEM Business Process>|Business Transaction|<CEM Business Transaction>". In some HTTP Posts, the Stall Count and Concurrent Invocations will not be produced per CEM Business Transaction. Blame is implicit, but does not apply to Concurrent Invocations. This tracer will factor in every method invocation. Supported on Java Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
ConcurrentInvocationCounterCalculates the number of method invocations that have not completed at the end of the interval period. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Concurrent Invocations or Concurrent Method Invocations
ConcurrentInvocationCounterDifferentInstancesCalculates the number of method invocations that have not completed at the end of the interval period. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Name: Concurrent Invocations or Concurrent Method Invocations
ConcurrentInvocationCounterDifferentMethodsCalculates the number of method invocations that have not completed at the end of the interval period. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Concurrent Invocations or Concurrent Method Invocations
ConcurrentResponseTimerDeprecated.
DatabaseBackendTracerInternal use only. A version of the BackendMarker used with database drivers that will format the metric name (under the Backends Resource) based on the database URL connection string. Supports the following database driver: Microsoft for SQL Server. Supported on .NET Agents.
DbCommandTracer

Internal use only. Supported on Java & .NET Agents, but with different meanings:

On Java, a version of the BackendMarker used with database drivers that will format the metric name (under the Backends Resource) based on the database URL connection string. Supports the following database drivers: Oracle for Oracle, BEA for Oracle, BEA for Pointbase, IBM for DB2, IBM for Informix, SAP for MaxDB, and Microsoft for SQL Server. On .NET, generates 5 separate metrics (listed below) for each SQL query, insert or update statement, based on the SQL text, without per-query parameters. Metrics will appear under the Resource "Backends|<Database Instance>|SQL".

Supports the Microsoft for .NET database drivers. Otherwise, database instance name may appear as unknown, but SQL statements will appear correctly.

Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
DriverAwareBlamedMethodRateTracerDifferentInstancesCalculates the number of invocations per second with Blame enabled. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Queries Per Second
DriverAwareBlamedMethodTimerDifferentInstancesCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval with Blame enabled. When aggregated for a class, This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Average Query Time (ms)
DriverAwareBlamedPerIntervalCounterDifferentInstancesCalculates the number of invocations that completed during the time interval with Blame enabled. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Queries Per Interval
DriverAwareConcurrentInvocationCounterDifferentInstancesCalculates the number of method invocations that have not completed at the end of the interval period. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Concurrent Invocations
DriverAwareMethodRateTracerDifferentInstancesCalculates the number of invocations per second. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Queries Per Second
DriverAwareMethodTimerDifferentInstancesCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Average Query Time (ms)
DriverAwarePerIntervalCounterDifferentInstancesCalculates the number of invocations that completed during the time interval. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Queries Per Interval
DriverAwareStalledMethodTracerCalculates the number of method invocations currently running that have not completed within the specified threshold (in milliseconds). This tracer will factor in every method invocation. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Stalled Method Count
DriverAwareStalledMethodTracerDifferentInstancesCalculates the number of method invocations currently running that have not completed within the specified threshold (in milliseconds). This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Separates metrics based on JDBC Driver name. Supported on Java Agents.
Default Metric Name: Stalled Method Count
DumpStackTraceTracerDumps a stack trace to the instrumented application's stderr for methods to which it is applied. The exception stack trace thrown by DumpStackTraceTracer is not a true Exception - it is a mechanism for printing the method stack trace. This Tracer does not produce a metric, therefore the "<Investigator Tree Path>" declaration is ignored, but is still required - must be of the form "<non-empty-character>:<non-empty character>" in order to parse properly. Warning: This feature imposes heavy system overhead. Supported on Java & .NET Agents.
ExceptionErrorReporterA per interval counter based on the number of exceptions being thrown (i.e. uncaught) from the identified method(s). If an exception is thrown, the error message is based on the return value of the getMessage() method called on the exception object. In order to capture the error message, must be used with a *WithParameters* Directive, otherwise will only increment the Errors Per Interval metric. To see error messages, requires ErrorDetector, otherwise will only increment the Errors Per Interval metric. Requires Agent be at 6.0 or later for Java Agent; 10.0 or later for .NET. Blame is implicit. Supported on Java & .NET Agents.
Default Metric Name: Errors Per Interval
FrontendMarkerGenerates 5 separate metrics (listed below) for associated methods or classes. The Errors Per Interval metric will be generated, but will always report a value of 0 (zero) when this Tracer Type is used alone. To generate non-zero Errors Per Interval metric values, also apply ExceptionErrorReporter to associated methods or classes. The Stall Count metric threshold is set by the property introscope.agent.stalls.thresholdseconds in the IntroscopeAgent.profile. Metric naming is automatic. Explicitly identifies methods as Frontends metrics, i.e. to override those that were automatically identified by Introscope out of the box as representing the entry point to the application. Generated metrics will appear under the Frontends folder and are automatically named. The Investigator Tree Path name declaration is “<Resource>”, without the explicit “:<Metric>” naming portion. To participate in the Application Overview grid and heuristics, the resource name declaration must be of the format “Apps|<Resource>”. Blame is implicit, but does not apply to Concurrent Invocations. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
HTTPErrorCodeReporterReports the number of errors sent per interval from Servlets and JSPs. Gathers the error message from the JSP and Servlet method parameter values. In order to capture the error message, must be used with a *WithParameters* Directive, otherwise will only increment the Errors Per Interval metric. Not recommended to be used in custom PBDs. To see error messages, requires ErrorDetector, otherwise will only increment the Errors Per Interval metric. Requires Agent be at 6.0 or later. Blame is implicit. Supported on Java Agents.
Default Metric Name: Errors Per Interval
HttpServletTracerApps Resource. Supported on Java Agents.
MethodCalledErrorReporterA per interval counter based on methods where the very act of the method being called means that an error has occurred. The error message is based on the class and method called. In order to capture the error message, must be used with a *WithParameters* Directive and requires ErrorDetector, otherwise will only increment the Errors Per Interval metric. Requires Agent be at 6.0 or later. Blame is implicit. Supported on Java Agents.
Default Metric Name: Errors Per Interval
MethodCPUTimerReports the average CPU time (in milliseconds) used during method execution. This tracer will factor in every method invocation. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
MethodCPUTimerDifferentInstancesReports the average CPU time (in milliseconds) used during method execution. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
MethodCPUTimerDifferentMethodsReports the average CPU time (in milliseconds) used during method execution. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Supported on Java Agents.
Default Metric Name: Average CPU Time (ms)
MethodInvocationCounterDeprecated.
MethodNanoCPUTimerReports the average CPU time (in nanoseconds) used during method execution. This tracer will factor in every method invocation. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Requires Java 5. Supported on Java Agents.
Default Metric Name: Average CPU Time (ns)
MethodNanoCPUTimerDifferentInstancesReports the average CPU time (in milliseconds) used during method execution. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Requires Java 5. Supported on Java Agents.
Default Metric Name: Average CPU Time (ns)
MethodNanoCPUTimerDifferentMethodsReports the average CPU time (in milliseconds) used during method execution. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. This tracer requires a platform monitor on the supported platform (either AIX 5.2 or RedHat Enterprise Linux 3.0). Requires Java 5. Supported on Java Agents.
Default Metric Name: Average CPU Time (ns)
MethodNanoTimerCalculates the method execution time (in nanoseconds) of methods that have completed during the reported interval. This tracer will factor in every method invocation. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. Requires Java 5. Supported on Java Agents.
Default Metric Name: Average Response Time (ns)
MethodNanoTimerDifferentInstancesCalculates the method execution time (in nanoseconds) of methods that have completed during the reported interval. This tracer is applied the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. Requires Java 5. Supported on Java Agents.
Default Metric Name: Average Response Time (ns)
MethodNanoTimerDifferentInstancesCalculates the method execution time (in nanoseconds) of methods that have completed during the reported interval. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. This tracer provides nanosecond precision, but not necessarily nanosecond accuracy; it relies on the JVM to provide the current value of the most precise available system timer, in nanoseconds. Requires Java 5. Supported on Java Agents.
Default Metric Name: Average Response Time (ns)
MethodRateTracerCalculates the number of invocations per second. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Second or Invocations Per Second
MethodRateTracerDifferentInstancesCalculates the number of invocations per second. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer is applied the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Second or Invocations Per Second
MethodRateTracerDifferentMethodsCalculates the number of invocations per second. For a 15 second interval, the remainder (14 or less) will be truncated. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Second or Invocations Per Second
MethodStartTraceDecrementorPerpetual counter that decreases by 1 at the start of a method invocation from another object instance. Supported on Java & .NET Agents.
MethodStartTraceIncrementorPerpetual counter that increases by 1 at the start of a method invocation from another object instance. Supported on Java & .NET Agents.
MethodTimerCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)
MethodTimerDifferentInstancesCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.

Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)

MethodTimerDifferentMethodsCalculates the method execution time (in milliseconds) of methods that have completed during the reported interval. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Average Response Time (ms) or Average Method Invocation Time (ms) or Average Query Time (ms)
MethodTraceDecrementorPerpetual counter that decreases by 1 for each completion of a method invocation from another object instance. Supported on Java & .NET Agents.
MethodTraceIncrementorPerpetual counter that increases by 1 for each completion of a method invocation from another object instance. Supported on Java & .NET Agents.
NormalCompletionMethodTraceDecrementorPerpetual counter that decreases by 1 for each method invocation from another object instance that completes without throwing an exception. Supported on Java & .NET Agents.
NormalCompletionMethodTraceIncrementorPerpetual counter that increases by 1 for each method invocation from another object instance that completes without throwing an exception. Supported on Java & .NET Agents.
NormalCompletionPerIntervalCounterCounts the number of method invocations that complete without throwing an exception, per time interval. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
NormalCompletionPerIntervalCounterDifferentInstancesCounts the number of method invocations that complete without throwing an exception, per time interval. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
NormalCompletionPerIntervalCounterDifferentMethodsCounts the number of method invocations that complete without throwing an exception, per time interval. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
NormalCompletionSimpleDecrementorPerpetual counter that decreases by 1 for each method invocation that completes without throwing an exception, regardless of whether called from another object instance or the same object instance. Supported on Java & .NET Agents.
NormalCompletionSimpleIncrementorPerpetual counter that increases by 1 for each method invocation that completes without throwing an exception, regardless of whether called from another object instance or the same object instance. Supported on Java & .NET Agents.
OverThresholdPerIntervalCounterCalculates per interval the number of invocations that completed over the specified time threshold (in milliseconds). This tracer will factor in every method invocation. Supported on Java & .NET Agents.
OverThresholdPerIntervalCounterDifferentInstancesCalculates per interval the number of invocations that completed over the specified time threshold (in milliseconds). This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
OverThresholdPerIntervalCounterDifferentMethodsCalculates per interval the number of invocations that completed over the specified time threshold (in milliseconds). This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
PageInfoTracerApps|<Application Virtual Directory Name>|URLs|<URL Name>. Supported on .NET Agents.
PerIntervalCounterCalculates the number of invocations that completed during the time interval. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval
PerIntervalCounterDifferentInstancesCalculates the number of invocations that completed during the time interval. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval
PerIntervalCounterDifferentMethodsCalculates the number of invocations that completed during the time interval. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
Default Metric Name: Responses Per Interval or Method Invocations Per Interval
ResponseTimerDeprecated.
ResponseTimerWithPackageNameDeprecated.
ServletHeaderDecoratorDecorates HTTP responses from Servlets with a unique identifier, allowing the correllation of CEM defects and Introscope Transaction Traces. In CEM, necessary to generate application server details for defective transactions and to present hyperlinks from defect and incident detail pages to Transaction Traces and Metrics in the Introscope Workstation. Applicable only to Servlet method service() & JSP method _jspservice(). Requires that Servlet container implement 2.1 specification or later. Must be used with a *WithParameters* Directive. Does not generate Metrics. Supported on Java Agents.
SimpleDecrementorPerpetual counter that decreases by 1 for each completion of a method invocation, regardless of whether from another object instance or the same object instance. Supported on Java & .NET Agents.
SimpleIncrementorPerpetual counter that increases by 1 for each completion of a method invocation, regardless of whether from another object instance or the same object instance. Supported on Java & .NET Agents.
SimpleInstanceCounterCounts the approximate number of Object Instances for a particular class. By default, used by the InstanceCounts Tracer Group. Supported on Java & .NET Agents.
Default Metric Name: Approximate Instance Count
SimpleStartDecrementorPerpetual counter that decreases by 1 at the start of a method invocation, regardless of whether from another object instance or the same object instance. Supported on Java & .NET Agents.
SimpleStartIncrementorPerpetual counter that increases by 1 at the start of a method invocation, regardless of whether from another object instance or the same object instance. Supported on Java & .NET Agents.
SQLBackendTracerInternal use only. A version of the BackendMarker used with database drivers that will format the metric name (under the Backends Resource) based on the database URL connection string. Supports Oracle, DB2, and Microsoft SQL Server on Java. Supports Microsoft SQL Server on .NET. Supported on Java & .NET Agents.
StalledMethodTracerCalculates the number of method invocations currently running that have not completed within the specified threshold (in milliseconds). This tracer will factor in every method invocation. A Metric will not be published until a method stalls. Supported on Java & .NET Agents.
Default Metric Name: Stalled Method Count
StalledMethodTracerDifferentInstancesCalculates the number of method invocations currently running that have not completed within the specified threshold (in milliseconds). This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. A Metric will not be published until a method stalls. Supported on Java & .NET Agents.
Default Metric Name: Stalled Method Count
StalledMethodTracerDifferentMethodsCalculates the number of method invocations currently running that have not completed within the specified threshold (in milliseconds). This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. A Metric will not be published until a method stalls. Supported on Java & .NET Agents.
Default Metric Name: Stalled Method Count
StatementBackendTracer<Database Instance>|SQL". On Java, supports the following database drivers: Oracle for Oracle, BEA for Oracle, BEA for Pointbase, IBM for DB2, IBM for Informix, SAP for MaxDB, and Microsoft for SQL Server. Supported on Java Agents.
Default Metric Names: Average Response Time (ms), Concurrent Invocations, Errors Per Interval, Responses Per Interval, Stall Count
StatementExecuteQueryMethodTimerDeprecated.
StatementExecuteUpdateMethodTimerDeprecated.
ThisErrorReporterTraces the number of exceptions thrown (caught or uncaught) per interval by tracing the constructor of the specified exception class(es). The error message is based on the return value of the toString() method of the exception object. Recommended for custom exceptions. In order to capture the error message, must be used with a *WithParameters* Directive, otherwise will only increment the Errors Per Interval metric. To see error messages, requires ErrorDetector, otherwise will only increment the Errors Per Interval metric. Requires Agent be at 6.0 or later. Blame is implicit. Supported on Java Agents.
Default Metric Name: Errors Per Interval
ThresholdMethodTimerDeprecated.
ThrownExceptionMethodTraceDecrementorPerpetual counter that decreases by 1 for each exception thrown by a method, caught or not, when called from another object instance. Supported on Java & .NET Agents.
ThrownExceptionMethodTraceIncrementorPerpetual counter that increases by 1 for each exception thrown by a method, caught or not, when called from another object instance. Supported on Java & .NET Agents.
ThrownExceptionPerIntervalCounterCounts the number of exceptions thrown by methods, caught or not, per time interval. This tracer will factor in every method invocation. Supported on Java & .NET Agents.
ThrownExceptionPerIntervalCounterDifferentInstancesCounts the number of exceptions thrown by methods, caught or not, per time interval. This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
ThrownExceptionPerIntervalCounterDifferentMethodsCounts the number of exceptions thrown by methods, caught or not, per time interval. This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.
ThrownExceptionSimpleDecrementorPerpetual counter that decreases by 1 for each exception thrown by a method, caught or not, regardless of whether called from another object instance or the same object instance. Supported on Java & .NET Agents.
ThrownExceptionSimpleIncrementorPerpetual counter that increases by 1 for each exception thrown by a method, caught or not, regardless of whether called from another object instance or the same object instance. Supported on Java & .NET Agents.
UnderThresholdPerIntervalCounterCalculates per interval the number of invocations that completed under the specified time threshold (in milliseconds). This tracer will factor in every method invocation. Supported on Java & .NET Agents.
UnderThresholdPerIntervalCounterDifferentInstancesCalculates per interval the number of invocations that completed under the specified time threshold (in milliseconds). This tracer is applied to the first method invoked in the object - any successive calls within that object will be ignored until the first method finishes. Supported on Java & .NET Agents.
UnderThresholdPerIntervalCounterDifferentMethodsCalculates per interval the number of invocations that completed under the specified time threshold (in milliseconds). This tracer will run on the first method invoked in an instance with a given method name but any successive calls to other methods with the same name will be ignored until the first method finishes. This applies to calls to another method with the same name but different signature, recursive calls to the exact same method and calls to a method with the same name in the superclass. Supported on Java & .NET Agents.

^Back to Top

Directives

Directives are the actionable lines in a PBD file; each line must start with a directive unless it is a commented out (starting with the # symbol) or an empty line. Directives can be simple keywords that associate tracers into groups or enable/disable groups or they can specify probe definitions. For Introscope to recognize and process tracers, you must use a specific syntax when constructing custom tracers. A tracer is composed of a directive and information about the method or class to trace, in the following format:

<directive>: [arguments]

 

where [arguments] is a list, and is directive-specific.

Note: Depending on the directive used, only a subset of these parameters are required. A more complex, but versatile, method of specifying tracer definitions is to use tracer groups.

 

Using quotes in custom probe definitions

Custom probes can contain metric names with spaces in them. When using spaces in your custom metric names, CA Technologies highly recommends putting quotes ("") around all metric names.

Important! Do not place quotes around class names. This causes the custom tracers to malfunction. For example:

Correct

IdentifyClassAs: MyClass MyTracers

 

Incorrect

IdentifyClassAs: "MyClass" MyTracers

 

If you create a metric name that contains a class name or similar keyword-based substitution, you must use quotes around the whole metric name. Metric names are allowed to have spaces, and all spaces in metric names must be contained within quotes. For example, the metric name "{classname}|Test One Node" should be represented as follows:

Correct

TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer "{classname}|Test One Node"

 

Incorrect

TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer {classname}|Test One Node

Important! Introscope will not monitor classes having invalid class file names. For example, in the class file name:

org/jboss/seam/example/seambay/AuctionImage$JaxbAccessorM_getData_setData_[B:

 

The _[B: causes the class file name to be invalid. You cannot use an open square brackets ([) as part of the Java class file name. When Introscope encounters such classes having invalid class names, it fails to instrument them and reports them as an error message in the agent logs. Please see the JNI Signatures page for more information.

The following sections are examples of some of the many available method tracers as well as the appropriate use of quotation marks in a probe definition.

 

Average tracer example

This tracer tracks the average execution time of the given method in milliseconds.

TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlamedMethodTimer "Petstore|Catalog|search:Average Method Invocation Time (ms)"

 

 

Rate tracer example

This tracer counts the number of times the method is called per second, and reports this rate under the specified metric name.

TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search BlamedMethodRateTracer "Petstore|Catalog|search:Method Invocations Per Second"

 

 

Per interval counter tracer example

This method tracer counts the number of times the method is called per interval, and reports the per interval count under the specified metric name.

TraceOneMethodOfClass: com.sun.petstore.catalog.Catalog search PerIntervalCounter "Petstore|Catalog|search:Method Invocations Per Interval"

 

The interval is determined by the monitoring logic in the Enterprise Manager, such as the Graph frequency. The preview pane in the Investigator defaults to 15 second intervals.

 

Counter tracer example

This tracer counts the total number of times the method is called.

TraceOneMethodOfClass: com.sun.petstore.cart.ShoppingCart placeOrder BlamedMethodTraceIncrementor "Petstore|ShoppingCart|placeOrder:Total Order Count"

 

 

Combined counter tracers example

These tracers combine incrementor and decrementor Tracers to keep a running count.

TraceOneMethodOfClass: com.sun.petstore.account.LoginEJB login MethodTraceIncrementor "Petstore|Account:Logged In Users"

TraceOneMethodOfClass: com.sun.petstore.account.LogoutEJB logout MethodTraceDecrementor "Petstore|Account:Logged In Users"

 

 

Tracer Groups 

The majority of tracing directives, wherein a class and method(s) are selected for instrumentation, are single-line directives. As such, they cannot be toggled on or off without either A) deleting the directive from the .pbd or B) disabling the .pbd containing the directive. Tracer groups, however, allow you greater flexibility in controlling the instrumentation, including the ability to remotely enable or disable any tracer groups not explicitly enabled or disabled already. When using tracer groups, the tracer group is first created with a flag, then classes and included or excluded from the group. Next, the tracers to apply along with the metrics to generate for the tracer groups. Optionally, the tracer is then activated within the PBD file.

 

Directives matching the follow patterns are used when working with tracer groups:

Creating the Tracer Group
  • SetFlag
Including Classes in the Tracer Group
  • Identify*As
Excluding Classes from the Tracer Group
  • Skip*Flag
Applying Tracers to Methods / Selecting Metrics to Generate
  • Trace*IfFlagged
Excluding methods from the Tracer Group
  • Skip*ForFlag
Activating the Tracer Group
  • TurnOn

 

 

Common Directives

DirectiveDefinition
IdentifyClassAsOnly used when creating tracer groups. Associates a specific class to the specified Tracer Group. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

IdentifyClassAs: <class> <Tracer Group>
IdentifyInheritedAsOnly used when creating tracer groups. Associates all direct subclasses of the specified class or all direct implementations of the specified interface to the Tracer Group. The specified class or interface should be the fully qualified name. Supported on Java & .NET Agents.

Format:

IdentifyInheritedAs: <class or interface> <Tracer Group>
SetFlagOnly used when creating tracer groups. Declaration for a new Tracer Group identified by its Flag. Supported on Java & .NET Agents.

Format:

SetFlag: <Tracer Group>
TraceOneMethodOfClass / TraceOneMethodIfFlaggedTraces a specific method in the specified class or tracer group. Class name should be fully qualified when not using tracer groups. Supported on Java & .NET Agents.

Format:

TraceOneMethodOfClass: <class> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodIfFlagged: <Tracer Group> <method> <Tracer> "<Investigator Tree Path>"
TraceAllMethodsOfClass / TraceAllMethodsIfFlaggedTraces all methods except for constructors (<init>) and static initializers (<clinit>) in the specified class or tracer group. Class name should be fully qualified when not using tracer groups. Supported on Java & .NET Agents.

Format:

TraceAllMethodsOfClass: <class> <Tracer> "<Investigator Tree Path>"
TraceAllMethodsIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>"
TraceOneMethodIfInheritsDoes not support tracer groups. Traces a specific method in all direct subclasses of the specified class or in all direct implementations of the specified interface. The specified class or interface should be the fully qualified name. Supported on Java & .NET Agents.

Format:

TraceOneMethodIfInherits: <class or interface> <method> <Tracer> "<Investigator Tree Path>"

TraceAllMethodsIfInherits

Does not support tracer groups. Traces all methods except for constructors (<init>) and static initializers (<clinit>) in all direct subclasses of the specified class or direct implementations of the specified interface. The specified class or interface should be the fully qualified name. Supported on Java & .NET Agents.

Format:

TraceAllMethodsIfInherits: <class or interface> <Tracer> "<Investigator Tree Path>"
TurnOn / TurnOffOnly used when creating tracer groups. A toggle for activating or deactivating the specified Tracer Group. Supported on Java & .NET Agents.

Format:

TurnOn: <Tracer Group>
TurnOff: <Tracer Group>

 

All Directives

Directive NameDefinition
ConditionallyTraceOneMethodWithLabelIfInherits

Traces a specific method in all subclasses of the specified class or in all implementations of the specified interface, conditionally to the fact that the calling method in the calling class is part of the Thread stack. The specified classes or interfaces names should be the fully qualified. The label parameter assigned to the tracer is used for query by Dynamic Instrumentation (DI) API. Supported on Java & .NET Agents.

Format:

ConditionallyTraceOneMethodWithLabelIfInherits: <class> <method> <label> <Tracer> <Tracer Group> "<Investigator Tree Path>" <calling class> <calling method>
ConditionallyTraceOneMethodWithLabelOfClass

Traces a specific method of the specified class, conditionally to the fact that the calling method in the calling class is part of the Thread stack. The specified class or interface should be the fully qualified name. The label parameter assigned to the tracer is used for query by Dynamic Instrumentation (DI) API. Supported on Java & .NET Agents.

Format:

ConditionallyTraceOneMethodWithLabelOfClass: <class> <method> <label> <Tracer> <Tracer Group> "<Investigator Tree Path>" <calling class> <calling method>
DoNotSkipMethodForClass

Include method in tracing even, if there is a skip directive that matches it. It is used to make exceptions for class or package based skip directives. Supported on Java & .NET Agents.

Format:

IdentifyAllClassesAs: <class> <method>
IdentifyAllClassesAs

Associates all classes inspected by ProbeBuilder to the specified Tracer Group. Do NOT use in production environments. Supported on Java & .NET Agents.

Format:

IdentifyAllClassesAs: <Tracer Group>
IdentifyAnnotatedClassAs

Associates all classes which are annotated with the specified class to the specified Tracer Group. Supported on Java & .NET Agents.

Format:

IdentifyAnnotatedClassAs: <class> <Tracer Group>
IdentifyAttributeMarkedClassAs

Associates a class to the specified Tracer Group, if it has been marked with specified attribute. Supported on .NET Agents.

Format:

IdentifyAttributeMarkedClassAs: <attribute> <Tracer Group>
IdentifyClassAs

Associates a specific class to the specified Tracer Group. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

IdentifyClassAs: <class> <Tracer Group>
IdentifyCorbaAs

Associates all CORBA classes to the specified Tracer Group. CORBA classes are limited to stubs and skeleton classes, and are identified by matching the patterns "_st_" & "_sk_" in class names. Supported on Java Agents.

Format:

IdentifyCorbaAs: <Tracer Group>
IdentifyDeepInheritedAnnotatedClassAs

Associates a subclasses of an annotated class or interface to the specified Tracer Group, if it has specified annotation. Annotation name should be fully qualified. The annotated class or interface is also associated to the Tracer Group. Supported on Java & .NET Agents.

Format:

IdentifyDeepInheritedAnnotatedClassAs: <annotation class> <Tracer Group>
IdentifyDeepInheritedAs

Associates all subclasses of the specified class or all implementations of the specified interface to the Tracer Group. The specified class or interface should be the fully qualified name. The specified class or interface is also associated to the Tracer Group. Supported on Java & .NET Agents.

Format:

IdentifyDeepInheritedAs: <class> <Tracer Group>
IdentifyDeepInheritedAttributeMarkedClassAs

Associates all subclasses of a class marked by a specified attribute to the specified Tracer Group, if the class has been marked with specified attribute. The marked class itself is also associated to the Tracer Group. This directive is specific for .NET agent.

Format:

IdentifyDeepInheritedAttributeMarkedClassAs: <attribute> <Tracer Group>
IdentifyFlagAs

Assigns the classes associated with the 1st Tracer Group listed to also be associated with the 2nd Tracer Group. In addition, the 2nd Tracer Group can be activated by turning on either the 1st Tracer Group or the 2nd Tracer Group. See java2.pbd for examples. Supported on Java & .NET Agents.

Format:

IdentifyFlagAs: <Tracer Group> <Tracer Group>
IdentifyInheritedAnnotatedClassAs

Associates all direct subclasses of an annotated class or all direct implementations of an annotated interface to the specified Tracer Group. Annotation name should be fully qualified. Supported on Java & .NET Agents.

Format:

IdentifyInheritedAnnotatedClassAs: <annotation class> <Tracer Group>
IdentifyInheritedAs

Associates all direct subclasses of the specified class or all direct implementations of the specified interface to the Tracer Group. The specified class or interface should be the fully qualified name. Supported on Java & .NET Agents.

Format:

IdentifyInheritedAs: <class or interface> <Tracer Group>
IdentifyInheritedAttributeMarkedClassAs

Associates all direct subclasses of a class to the specified Tracer Group, if the class has been marked with specified attribute. Supported on .NET Agents.

Format:

IdentifyInheritedAttributeMarkedClassAs: <attribute> <Tracer Group>
IdentifyMatchingClassesAs

Associates all classes that match the class name expression to the specified Tracer Group. The quotes around the class name expression are optional. The class name expression can only contain one type of wildcard * which matches any number of any characters. The wildcard may appear as many times as desired. Requires Agent be at 6.0 or later. Supported on Java & .NET Agents.

Format:

IdentifyMatchingClassesAs: "<class name expression>" <Tracer Group>
IdentifyTwoFlagIntersectionAsAggregateFlag

Identifies an Aggregate Tracer Group for two member Tracer Groups. When the Aggregate Tracer Group is associated with tracing Directives, activation is dependent on both member Tracer Groups being turned on with the TurnOn Directive. See j2ee.pbd for examples. Supported on Java & .NET Agents.

Format:

IdentifyTwoFlagIntersectionAsAggregateFlag: <member Tracer Group> <member Tracer Group> <aggregate Tracer Group>
IdentifyTwoFlagUnionAsAggregateFlag

Identifies an Aggregate Tracer Group for two member Tracer Groups. When the Aggregate Tracer Group is associated with tracing Directives, activation is dependent on either member Tracer Group being turned on with the TurnOn Directive. Classes associated with activated member Tracer Groups will be probed with the tracing Directives associated with the Aggregate Tracer Group. See taglibs.pbd for examples. Supported on Java & .NET Agents.

Format:

IdentifyTwoFlagUnionAsAggregateFlag: <member Tracer Group> <member Tracer Group> <Aggregate Tracer Group>
InstrumentBootstrapClass

Force instrumentation of the class at bootstrap. It overrules any skip directive. If the parameter specified is "true", then the class is instrumented before the pre-main method returns, i.e. before any code is executed on the monitored application. Supported on Java & .NET Agents.

Format:

InstrumentBootstrapClass: <class> <true|false>

Supported flag values: true, false

InstrumentPoint

A toggle for enabling or disabling capturing ThrownException and CaughtException stack traces. Also used to initialize the starting of the agent when not using JVM AutoProbe (AgentInitialization). Supported on Java & .NET Agents.

Format:

InstrumentPoint: <Flag>

Supported flag values: ThrowException, CatchException, AgentInitialization

InstrumentTraceClass

Set the name of the class that will trace events generated by the instrumented classes. The class must provide a one static method for each instrumentation point. Supported on Java & .NET Agents.

Format:

InstrumentTraceClass: <class>
MarkNotToggled

Used to define the tracer groups that cannot be toggled on or off through the Dynamic Instrumentation (DI) API.

Format:

MarkNotToggled: <Tracer Group>
SetFlag

Declaration for a new Tracer Group identified by its Flag. Supported on Java & .NET Agents.

Format:

SetFlag: <Tracer Group>
SetTracerClassMapping

Internal Use Only. Maps Tracers to instrumentation classes. Supported on Java & .NET Agents.

Format:

SetTracerClassMapping: <Tracer Type> <Instrumentation Class> <Metric/Resource Name Validation Class>
SetTracerOrdering

Specifies order in which the tracers are run, if multiple tracers are put on single method. The tracers with lower order number are executed first.

Format:

SetTracerParameter: <Tracer Type> <priority> <Parameter Value>

Supported priority values: any signed integer.

SetTracerParameter

Internal Use Only. Sets a Tracer parameter. For example, the amount that incrementors add and the amount that decrementors subtract from a perpetual counter. Supported on Java & .NET Agents.

Format:

SetTracerParameter: <Tracer Type> <Parameter Name> <Parameter Value>
SkipAnnotatedForFlag

Prevents all classes that are explicitly annotated with specified annotation from being traced by the specified Tracer Group. Annotation name must be fully qualified.Supported on Java & .NET Agents.

Format:

SkipAnnotatedForFlag: <annotation class> <Tracer Group>
SkipAssembly

Prevents all methods in all classes contained within the specified assembly from being traced. Supported on .NET Agents.

Format:

SkipAssembly: <assembly-specification>
SkipAssemblyForFlag

Prevents all methods in all classes contained within the specified assembly from being traced by the specified Tracer Group. Supported on .NET Agents.

Format:

SkipAssembly: <assembly-specification> <Tracer Group>
SkipAssemblyPrefix

Prevents all methods in all classes contained within an assembly which begins with the specified assembly prefix from being traced. Supported on .NET Agents.

Format:

SkipAssembly: <assembly-specification prefix>
SkipAssemblyPrefixForFlag

Prevents all methods in all classes contained within an assembly which begins with the specified assembly prefix from being traced by the specified Tracer Group. Supported on .NET Agents.

Format:

SkipAssemblyPrefixForFlag : <assembly-specification prefix> <Tracer Group>
SkipClass

Prevents all methods in the specified class from being traced. Supported on Java & .NET Agents.

Format:

SkipClass: <class>
SkipClassForFlag

Prevents all methods in the specified class from being traced by the specified Tracer Group. Supported on Java & .NET Agents.

Format:

SkipClassForFlag: <class> <Tracer Group>
SkipIfInheritedForFlag

Prevents all direct subclasses of a class from being traced by the specified Tracer Group. Class name must be fully qualified. Supported on Java & .NET Agents.

Format:

SkipIfInheritedForFlag: <class> <Tracer Group>
SkipMethodForClass

Prevents the specified method in the associated class from being traced. Class name must be fully qualified. Supported on Java & .NET Agents.

Format:

SkipMethodForClass: <class> <method>
SkipMethodForFlag

Prevents the specified method(s) from being traced by the specified Tracer Group. Supported on Java & .NET Agents.

Format:

SkipMethodForFlag: <Tracer Group> <method>
SkipNamespace

Prevents all methods in all classes in the specified namespace from being traced. Supported on .NET Agents.

Format:

SkipNamespace: <namespace>
SkipNamespaceForFlag

Prevents all methods in all classes in the specified namespace from being traced by the specified Tracer Group. Supported on .NET Agents.

Format:

SkipNamespace: <namespace> <Tracer Group>
SkipNamespacePrefix

Prevents all methods in all classes contained within namespaces which begin with the specified namespace prefix from being traced. Supported on .NET Agents.

Format:

SkipNamespacePrefix: <namespace prefix>
SkipNamespacePrefixForFlag

Prevents all methods in all classes contained within namespaces which begin with the specified namespace prefix from being traced by the specified Tracer Group. Supported on .NET Agents.

Format:

SkipNamespacePrefixForFlag: <namespace prefix> <Tracer Group>
SkipPackage

Prevents all methods in all classes in the specified package from being traced. Supported on Java Agents.

Format:

SkipPackage: <package>
SkipPackageForFlag

Prevents all methods in all classes in the specified package from being traced by the specified Tracer Group. Supported on Java Agents.

Format:

SkipPackageForFlag: <package> <Tracer Group>
SkipPackagePrefix

Prevents all methods in all classes that begin with the specified package prefix from being traced. Supported on Java Agents.

Format:

SkipPackagePrefix: <package prefix>
SkipPackagePrefixForFlag

Prevents all methods in all classes that begin with the specified package prefix from being traced by the specified Tracer Group. Supported on Java Agents.

Format:

SkipPrefixForFlag: <package prefix> <Tracer Group>
SkipStaticMethodsForFlag

Prevents all static methods from being traced by the specified Tracer Group. Supported on Java & .NET Agents.

Format:

SkipStaticMethodsForFlag: <Tracer Group>
TraceAllComplexMethodsIfFlagged

On Java, traces all methods, except constructors (<init>) and static initializers (<clinit>), which call any other method, for classes associated with specified Tracer Group. On .NET, traces all methods, except instance constructors (".ctor") and class constructors (".cctor"), which call any other method, for classes associated with specified Tracer Group. Supported on Java & .NET Agents.

Format:

TraceAllComplexMethodsIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>"
TraceAllComplexMethodsWithThresholdIfFlagged

On Java, traces all methods that call any other method, except constructors (<init>) and static initializers (<clinit>), which finish before or beyond the threshold specified in milliseconds, for classes associated with specified Tracer Group. On .NET, traces all methods that call any other method, except instance constructors (".ctor") and class constructors (".cctor"), which finish before or beyond the threshold specified in milliseconds, for classes associated with specified Tracer Group. Works with variations of the following Tracers: StalledMethodTracer, OverThresholdPerIntervalCounter, and UnderThresholdPerIntervalCounter. Supported on Java & .NET Agents.

Format:

TraceAllComplexMethodsWithThresholdIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>" <threshold>
TraceAllMethodsIfCorba

Traces all methods except for constructors (<init>) and static initializers (<clinit>) for CORBA-related classes. CORBA classes are limited to stubs and skeleton classes, and are idntified by matching the patterns "_st_" & "_sk_" in class names. For use with Single-Metric Tracers. Supported on Java Agents.

Format:

TraceAllMethodsIfCorba: <Tracer> "<Investigator Tree Path>"
TraceAllMethodsIfFlagged

Traces all methods except for constructors (<init>) and static initializers (<clinit>) for classes associated with specified Tracer Group. Supported on Java & .NET Agents.

Format:

TraceAllMethodsIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>"
TraceAllMethodsIfInherits

Traces all methods except for constructors (<init>) and static initializers (<clinit>) in all direct subclasses of the specified class or direct implementations of the specified interface. The specified class or interface should be the fully qualified name. Supported on Java & .NET Agents.

Format:

TraceAllMethodsIfInherits: <class or interface> <Tracer> "<Investigator Tree Path>"
TraceAllMethodsOfClass

Traces all methods except for constructors (<init>) and static initializers (<clinit>) in the specified class. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

TraceAllMethodsOfClass: <class> <Tracer> "<Investigator Tree Path>"
TraceAllMethodsWithThresholdIfFlagged

Traces all methods that finish before or beyond the threshold specified in milliseconds except for constructors (<init>) and static initializers (<clinit>) for classes associated with specified Tracer Group. Works with variations of the following Tracers: StalledMethodTracer, OverThresholdPerIntervalCounter, and UnderThresholdPerIntervalCounter. Supported on Java & .NET Agents.

Format:

TraceAllMethodsWithThresholdIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>" <threshold>
TraceAllMethodsWithThresholdOfClass

Traces all methods that finish before or beyond the threshold specified in milliseconds except for constructors (<init>) and static initializers (<clinit>) for the specified class. Works with variations of the following Tracers: StalledMethodTracer, OverThresholdPerIntervalCounter, and UnderThresholdPerIntervalCounter. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

TraceAllMethodsWithThresholdOfClass: <class> <Tracer> "<Investigator Tree Path>" <threshold>
TraceAnnotatedMethodsIfFlagged

Traces all methods which are annotated by the specified class for classes associated with the specified Tracer Group. Supported on Java & .NET Agents.

Format:

TraceAnnotatedMethodsIfFlagged: <Tracer Group> <class> <Tracer> "<Investigator Tree Path>"
TraceAnnotatedMethodsWithParametersIfFlagged

Traces all methods which are annotated by the specified class for classes associated with the specified Tracer Group. In addition, records passed argument values. Primarily used to capture argument values passed in method invocations to display separate Metrics per argument value or with ErrorDetector-related Tracer Types to display error messages in Error Snapshots. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Supported on Java & .NET Agents.

Format:

TraceAnnotatedMethodsWithParametersIfFlagged: <Tracer Group> <class> <Tracer> "<Investigator Tree Path>"
TraceAttributeMarkedMethodsIfFlagged

Traces all methods that are marked with specified attribute for classes associated with specified Tracer Group. Supported on .NET Agents.

Format:

TraceAttributeMarkedMethodsIfFlagged: <Tracer Group> <class> <Tracer> "<Investigator Tree Path>"
TraceAttributeMarkedMethodsWithParametersIfFlagged

Traces all methods that are marked with specified attribute for classes associated with specified Tracer Group and reports metrics separately by value(s) of parameter(s) passed. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Supported on .NET Agents.

Format:

TraceAttributeMarkedMethodsWithParametersIfFlagged: <Tracer Group> <class> <Tracer> "<Investigator Tree Path>"
TraceComplexMethodsIfFlagged

On Java, traces all public or package-visible non-synthetic methods that call any other method, except constructors (<init>) and static initializers (<clinit>) for classes associated with specified Tracer Group. On .NET, traces all public non-synthetic methods that call any other method, except instance constructors (".ctor") and class constructors (".cctor") for classes associated with specified Tracer Group. Synthetic methods are ones that do not appear in the source code and are added by the compiler. Supported on Java & .NET Agents.

Format:

TraceComplexMethodsIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>"
TraceComplexMethodsWithParametersIfFlagged

Traces all public or package-visible non-synthetic methods that call any other method, except constructors (<init>) and static initializers (<clinit>) for classes associated with specified Tracer Group. In addition, records passed argument values. Primarily used to capture argument values passed in method invocations to display separate Metrics per argument value or with ErrorDetector-related Tracer Types to display error messages in Error Snapshots. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Synthetic methods are ones that do not appear in the source code and are added by the compiler. Supported on Java Agents. Requires 7.0p6 or later.

Format:

TraceComplexMethodsWithParametersIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>"
TraceComplexMethodsWithThresholdIfFlagged

On Java, traces all public or package-visible non-synthetic methods that call any other method, except constructors (<init>) and static initializers (<clinit>), which finish before or beyond the threshold specified in milliseconds, for classes associated with specified Tracer Group. On .NET, traces all public non-synthetic methods that call any other method, except instance constructors (".ctor") and class constructors (".cctor"), which finish before or beyond the threshold specified in milliseconds, for classes associated with specified Tracer Group. Synthetic methods are ones that do not appear in the source code and are added by the compiler. Works with variations of the following Tracers: StalledMethodTracer, OverThresholdPerIntervalCounter, and UnderThresholdPerIntervalCounter. Supported on Java & .NET Agents.

Format:

TraceComplexMethodsWithThresholdIfFlagged: <Tracer Group> <Tracer> "<Investigator Tree Path>" <threshold>
TraceOneMethodIfCorba

Traces a specific method in CORBA classes. CORBA classes are limited to stubs and skeleton classes, and are identified by matching the patterns "_st_" & "_sk_" in class names. Supported on Java Agents.

Format: <preTraceOneMethodIfCorba: <method> <Tracer> "<Investigator Tree Path>"</pre>

TraceOneMethodIfFlagged

Traces a specific method in all classes associated with the specified Tracer Group. Supported on Java & .NET Agents.

Format:

TraceOneMethodIfFlagged: <Tracer Group> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodIfInherits

Traces a specific method in all direct subclasses of the specified class or in all direct implementations of the specified interface. The specified class or interface should be the fully qualified name. Supported on Java & .NET Agents.

Format:

TraceOneMethodIfInherits: <class or interface> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodOfClass

Traces a specific method in the specified class. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

TraceOneMethodOfClass: <class> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodWithLabelIfInherits

Traces a specific method in the specified class. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

TraceOneMethodWithLabelIfInherits: <class> <method> <label> <Tracer> <Tracer Group> "<Investigator Tree Path>"
TraceOneMethodWithLabelOfClass

Traces a specific method in the specified class. Class name should be fully qualified. Supported on Java & .NET Agents.

Format:

TraceOneMethodWithLabelOfClass: <class> <method> <label> <Tracer> <Tracer Group> "<Investigator Tree Path>"
TraceOneMethodWithParametersIfCorba

Traces a specific method in CORBA classes. In addition, records passed argument values. Primarily used to capture argument values passed in method invocations to display separate Metrics per argument value or with ErrorDetector-related Tracer Types to display error messages in Error Snapshots. CORBA classes are limited to stubs and skeleton classes, and are identified by matching the patterns "_st_" & "_sk_" in class names. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Supported on Java Agents.

Format:

TraceOneMethodWithParametersIfCorba: <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodWithParametersIfFlagged

Traces a specific method in all classes associated with the specified Tracer Group. In addition, records passed argument values. Primarily used to capture argument values passed in method invocations to display separate Metrics per argument value or with ErrorDetector-related Tracer Types to display error messages in Error Snapshots. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Supported on Java & .NET Agents.

Format:

TraceOneMethodWithParametersIfFlagged: <Tracer Group> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodWithParametersIfInherits

Traces a specific method in all direct subclasses of the specified class or in all direct implementations of the specified interface. In addition, records passed argument values. Primarily used to capture argument values passed in method invocations to display separate Metrics per argument value or with ErrorDetector-related Tracer Types to display error messages in Error Snapshots. The specified class or interface should be the fully qualified name. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Supported on Java & .NET Agents.

Format:

TraceOneMethodWithParametersIfInherits: <class or interface> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodWithParametersOfClass

Traces a specific method in the specified class. In addition, records passed argument values. Primarily used to capture argument values passed in method invocations to display separate Metrics per argument value or with ErrorDetector-related Tracer Types to display error messages in Error Snapshots. Class name should be fully qualified. The Metric name can include strings like "{#}" that are substituted with the value of the parameter at index # (where 0 is the first parameter, 1 is the second parameter, etc). Supported on Java & .NET Agents.

Format:

TraceOneMethodWithParametersIfInherits: <class or interface> <method> <Tracer> "<Investigator Tree Path>"
TraceOneMethodWithThresholdIfFlagged

Traces a specific method for classes associated with specified Tracer Group and reports metrics for invocations that finish before or beyond the threshold specified in milliseconds. Works with variations of the following Tracers: StalledMethodTracer, OverThresholdPerIntervalCounter, and UnderThresholdPerIntervalCounter. Supported on Java & .NET Agents.

Format:

TraceOneMethodWithThresholdIfFlagged: <Tracer Group> <method> <Tracer> "<Investigator Tree Path>" <threshold>
TraceOneMethodWithThresholdOfClass

Traces a specific method for a specified class and reports metrics for invocations that finish before or beyond the threshold specified in milliseconds. Class name should be fully qualified. Works with variations of the following Tracers: StalledMethodTracer, OverThresholdPerIntervalCounter, and UnderThresholdPerIntervalCounter. Supported on Java & .NET Agents.

Format:

TraceOneMethodWithThresholdOfClass: <class> <method> <Tracer> "<Investigator Tree Path>" <threshold>
TraceRemoteMethodsIfCorbaTraces methods exposed via RMI in CORBA classes. CORBA classes are limited to stubs and skeleton classes, and are identified by matching the patterns "_st_" & "_sk_" in class names. Directive selects methods based on whether or not they throw an RMIException. Supported on Java Agents.

Format:

TraceRemoteMethodsIfCorba: <Tracer> "<Investigator Tree Path>"
TraceRemoteMethodsIfFlaggedTraces methods exposed via RMI in classes associated with the specified Tracer Group. Directive selects methods based on whether or not they throw an RMIException. Supported on Java Agents.

Format:

TraceRemoteMethodsIfFlagged: <Tracer> <Tracer Group> "<Investigator Tree Path>"
TraceRemoteMethodsIfInheritsTraces methods exposed via RMI in all direct subclasses of the specified class or in all direct implementations of the specified interface. Directive selects methods based on whether or not they throw an RMIException. The specified class or interface should be the fully qualified name. Supported on Java Agents.

Format:

TraceRemoteMethodsIfInherits: <class> <Tracer> "<Investigator Tree Path>"
TraceRemoteMethodsOfClassTraces methods exposed via RMI in the specified class. Directive selects methods based on whether or not they throw an RMIException. Class name should be fully qualified. Supported on Java Agents.

Format:

TraceRemoteMethodsOfClass : <class> <Tracer Group> "<Investigator Tree Path>"
TurnOff

A toggle for deactivating the specified Tracer Group. It overrules the TurnOn directive. Supported on Java & .NET Agents.

Format:

TurnOff: <Tracer Group>
TurnOn

A toggle for activating the specified Tracer Group. Supported on Java & .NET Agents.

Format:

TurnOn: <Tracer Group>

^Back to Top

JNI Signatures

When instrumenting a method in a PBD file, it can often be useful to use the JNI signature of the Java method rather than just the method name. This allows you to select a specific overloaded method. Particularly in situations where the overloaded methods are chained, as below, specifying the method JNI signature can allow you to avoid unnecesasry redundency when instrumenting:

public void start(String param1) {

      start(param1, null);

}

public void start(String param1, String param2) {

      start(param1, null, null);

}

public void start(String param1, String param2, String param3) {

      //Do stuff

}

 

Overview

There are three parts to the signature. The first is the method name itself, which is the Java method name in UTF-8 form. You can specify the method name for a constructor of a class by enclosing the word "init" within angle brackets (this appears as "<init>").The second part is enclosed within the parentheses and represents the method's arguments. The third portion follows the closing parenthesis and represents the return type.

The general form of a method signature argument is:

method-name(argument-types)return-type 

 

The mapping between the Java type and C type is:

Type SignatureJava Type
Zboolean
Bbyte
Cchar
Ddouble
Ffloat
Ishort
Jlong
Lobject
Sshort
Vvoid
Lfully-qualified-class;fully-qualified-class
[typearray of type[]

Note: To specify an object, the "L" is followed by the object's fully qualified package & class name (e.g. java/lang/String) and ends with a semi-colon, ';'. Additionally, array types are indicated by a leading square bracket ([) followed by the type (in using JNI type signatures) of the array elements.

 

Examples

MethodSignature
void f1()f1()V
int f2(int n, long l)f2(IJ)I
boolean f3(int[] arr)f3([I)B
double f4(String s, int n)f4(Ljava/lang/String;I)D
void f5(int n, String[] arr, char c)f5(I[Ljava/lang/String;C)V
long f6(int n, String s, int[] arr)f6(ILjava/lang/String;[I)J
String f7(Boolean b, boolean b2)f7(Ljava/lang/Boolean;Z)Ljava/lang/String;

 

To eliminate the mistakes in deriving method signatures by hand, you can use the javap tool (included with the JDK) to show the signature to be used in JNI and can be used against any class:

C:\>javap -s java.awt.Label

Compiled from Label.java

public class java.awt.Label extends java.awt.Component {

      public java.awt.Label(java.lang.String);

           /* (Ljava/lang/String;)V */

      public java.awt.Label(java.lang.String,int);

          /* (Ljava/lang/String;I)V */

      public void setText(java.lang.String);

           /* (Ljava/lang/String;)V */

 

C:\>javap -s -p Prompt

Compiled from Prompt.java

class Prompt extends java.lang.Object

     /* ACC_SUPER bit set */

{

      private native getLine (Ljava/lang/String;)Ljava/lang/String;

      public static main ([Ljava/lang/String;)V

      <init> ()V

      static <clinit> ()V

}

Note: The "-s" flag informs javap to output signatures rather than normal Java types. The "-p" flag causes private members to be included

^Back to Top

5 people found this helpful

Attachments

    Outcomes