Java XML instrumentation examples

For your New Relic-monitored Java application, one custom instrumentation method is to use an XML file that lists the methods and classes you want to instrument. This documentation shows an example XML instrumentation file. For more information, see Java instrumentation by XML.

Edit XML file in UI

To edit your XML file directly from the New Relic UI: Go to one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Instrumentation. From here you can:

Download a sample XML file.
Select an edit existing XML file.
Search the instrumentation history.

XML file format

The XML file format includes root and child nodes.

Caution

Do not instrument all of your methods, as this can lead to a metric grouping issue.

The root node of an XML file is extension. It can have three different attributes:

Value	Definition
`name`	A unique but descriptive name identifying your XML extension.
`enabled`	Identifies whether the extension will be read by the Java agent. Default is `true`. If `false`, New Relic will ignore the extension.
`version`	The version of the extension. If two extensions have the same name, only the extension with the highest version will be used.

The pointcut is a child node of instrumentation and can have several attributes. Also, a pointcut can have several different child nodes.

Value	Definition
`transactionStartPoint`	If a transaction is not already in progress when this pointcut is reached, then a transaction will be started. If a transaction is already in progress, then that transaction will continue. A new transaction will not be created.
`metricNameFormat`	The name format to use for a metric. If not present, then this will default to the class name followed by the method name. You can only set the `metricNameFormat` on pointcuts where `transactionStartPoint` is set to `false`.
`excludeFromTransactionTrace`	When `true` the transaction trace will not be provided if this pointcut initiates the transaction. If the pointcut is reached in the middle of a transaction, then the transaction trace will still be present, but this method will be excluded from the call graph.
`ignoreTransaction`	When `true` the entire transaction will be ignored.
`transactionType`	Sets the type of the transaction. Possible values are `background` (default, reported as a non-web transaction) and `web` (reported as a web transaction).

A pointcut can have several different child nodes:

Value	Definition
`nameTransaction`	If this element is present, the agent will name the transaction using the class name and method(s) instrumented by this pointcut.
`methodAnnotation`	The case sensitive full name of an annotation class including the package name. All methods that are marked with this annotation will be matched.
`className`	The case sensitive name of the class to match, including the package name. Pair this node with the method node. If this node is present on a pointcut, then the `interfaceName` node cannot be present on the same pointcut node. The `className` node has the attribute `includeSubclasses`. If `true` the methods on the class with the matching name will be instrumented along with the matching methods on any child class of this class. If `false` (default), only methods on the exact class specified will be instrumented. The `className` must follow these rules: Inner classes can be instrumented. The full package structure with dots between packages must be used. To match subclasses of the specified class, set the attribute `includeSubclasses` to `true`.
`interfaceName`	The case sensitive name of an interface, including the package name, whose implementation classes will be matched. Pair this node with the method node. If this node is present on a pointcut, then the `className` node cannot be present on the same pointcut node. The `interfaceName` must follow this rule: The full package structure with dots between packages must be used.
`method`	A method on the class to instrument. Pair this node with a `className` node. Also, the `method` node can have children.
`traceByReturnType`	The class name, including package, in the format used in bytecode, for example `Ljava/lang/String;`. All methods that return an object of that class will be matched.
`traceLambda`	A boolean indicating whether to match lambdas. The `traceLambda` node has the attributes: `includeNonstatic` - a boolean indicating whether to match non static methods (defaults to false); `pattern` - a string with the pattern to search for the lambda methods.

The method node can have several children. For more information and examples, see Troubleshooting Java custom instrumentation.

Value	Definition
`name`	The exact case sensitive name of the method to match. A method `name` node must follow these rules: Public, protected, private, and package methods can all be instrumented. Static and instance methods can be instrumented. Constructors cannot be instrumented.
`parameters`	The parameter types of the method specified in order. If the `parameters` element is not present, then all methods matching the name will be matched. This includes private and protected declarations. A method `parameters` node contains a list of the method's parameters, specified by `type` elements. Here are the major rules for the `type` elements: Primitives are specified using their normal name: int, float, double, long, byte, short, boolean, char. Objects require a full package structure. For example, do not use `String` in the XML; instead, use `java.lang.String`. Do not use generics with collection objects. For example, write `java.util.List` instead of `java.util.List<String>`. Include brackets for arrays. For example, an array of integers will be `int[ ]` and an array of strings will be `java.lang.String[ ]`. Include two sets of brackets for an array of arrays. For example, an array of arrays of longs would be `long[ ][ ]`. To send the parameter as an analytic event to New Relic, add an XML attribute to the type element called `attributeName`. To use a method with no parameters, the `parameters` node needs to be present to match a "no arguments" method.
`returnType`	The case sensitive name of a class indicating a return type to match. All methods that return this class type will be matched.

Value

Definition

name

The exact case sensitive name of the method to match.

A method name node must follow these rules:

Public, protected, private, and package methods can all be instrumented.
Static and instance methods can be instrumented.
Constructors cannot be instrumented.

parameters

The parameter types of the method specified in order. If the parameters element is not present, then all methods matching the name will be matched. This includes private and protected declarations.

A method parameters node contains a list of the method's parameters, specified by type elements. Here are the major rules for the type elements:

Primitives are specified using their normal name: int, float, double, long, byte, short, boolean, char.
Objects require a full package structure. For example, do not use String in the XML; instead, use java.lang.String.
Do not use generics with collection objects. For example, write java.util.List instead of java.util.List<String>.
Include brackets for arrays. For example, an array of integers will be int[ ] and an array of strings will be java.lang.String[ ].
Include two sets of brackets for an array of arrays. For example, an array of arrays of longs would be long[ ][ ].
To send the parameter as an analytic event to New Relic, add an XML attribute to the type element called attributeName.
To use a method with no parameters, the parameters node needs to be present to match a "no arguments" method.

returnType

The case sensitive name of a class indicating a return type to match. All methods that return this class type will be matched.

Example

Here is a sample class and an XML file that could be used to instrument that class.

package test;

import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

public class SampleTester {

    private String configName;
    private Map<String, Long> maxSampleTimes;

    public SampleTester(String pConfigName) {
        configName = pConfigName;
        maxSampleTimes = new HashMap<>();
    }

    public void checkSample(String name, long[] times) {
        if (times != null) {
            maxSampleTimes.put(name, getFirst(times));
        } else {
            maxSampleTimes.put(name, (long) getFirst());
        }
    }

    private Long getFirst(long[] times) {
        return times[0];
    }

    private int getFirst() {
        return 0;
    }

    public void printMaxRepeat(final long max) throws Exception {
        Runnable myRunnable = new Runnable() {
            public void run() {
                try {
                    printMax(max);
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        };

        ScheduledExecutorService scheduledExecutor = Executors.newScheduledThreadPool(1);
        scheduledExecutor.scheduleWithFixedDelay(myRunnable, 0, 10000, TimeUnit.MILLISECONDS);
    }

    private void printMax(long max) {
        System.out.println("max is " + max);
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="https://newrelic.com/docs/java/xsd/v1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="newrelic-extension extension.xsd"
  name="customExtension" version="1.0">

  <instrumentation metricPrefix="EXAMPLE">
    <pointcut transactionStartPoint="true">

      <!--class name is preceded by package name-->
      <className>test.SampleTester</className>
      <method>
        <name>checkSample</name>
        <parameters>
          <type attributeName="sampleName">java.lang.String</type>
          <type>long[]</type>
        </parameters>
      </method>
      <!--two methods with the same name but different signatures can share one node-->
      <method>
        <name>getFirst</name>
      </method>
      <method>
        <name>run</name>
      </method>
    </pointcut>

    <pointcut transactionStartPoint="false" 
      ignoreTransaction="false"
      excludeFromTransactionTrace="false"
      metricNameFormat="SampleTester/methods">
  
      <className>test.SampleTester</className>
      <method>
        <name>printMaxRepeat</name>
      </method>
      <method>
        <name>printMax</name>
      </method>
    </pointcut>

  </instrumentation>
</extension>

The first block of the XML file specifies the name and version of the extension. As the XML extension is default enabled, that attribute is not specified.

The second block specifies the methods in SampleClass that should be instrumented. A transaction is started at the beginning of the block. It is worth noting that in the example class, there are two methods that share a name (getFirst) but have different signatures. These are instrumented with a single method node. By removing the parameters node, all methods with the same name can be matched under one method node.

In the third block, the specified methods do not have a transaction started on them. This is because the transaction has already been started in run. The transaction will not be ignored, and will be included in the transaction trace.

Edit XML file in UI

XML file format

Caution

Root node: extension

Instrumentation (child of extension)

Pointcut (child of instrumentation)

Child nodes for pointcut

Child nodes for method

Example

Sample class

Sample XML instrumentation file and explanation

Java XML instrumentation examples

Edit XML file in UI .css-21sua1{background:none;border:none;width:0;padding:0;}

XML file format

Caution

Instrumentation (child of extension)

Pointcut (child of instrumentation)

Child nodes for pointcut

Child nodes for method

Example

Sample class

Sample XML instrumentation file and explanation

Edit XML file in UI