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}

• Runtime package name of the class being traced

{packageandclassname}

• 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 pathes 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.