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.

To edit your XML file directly from the New Relic UI: From the New Relic menu bar, select APM > (Applications) > (selected app) > Settings > Live Instrumentation. From here you can:

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

For basic info about XML instrumentation, see Java instrumentation by XML.

XML file format overview

Here is a summary of the XML file format's root and child nodes.

Root node: extension

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.
Instrumentation (child of extension)

The instrumentation node is a child of extension. It can have one attribute: metricPrefix. This is the prefix used for the metric names when the nameTransaction node is not specified. Default is CUSTOM.

Pointcut (child of instrumentation)

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

Value Definition
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.

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.

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.
When true the entire transaction will be ignored.
Sets the type of the transaction. Possible values are background (default) and web. When set to web, the transaction will be reported as a web transaction.
Child nodes for pointcut

A pointcut can have several different child nodes:

Value Definition
If this element is present, the agent will name the transaction using the class name and method(s) instrumented by this pointcut.
The case sensitive full name of an annotation class including the package name. All methods that are marked with this annotation will be matched.

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.

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.
Child nodes for method

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

Value Definition

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.

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 Insights, 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.

Matching multiple methods

Multiple methods with the same name but different signatures can be matched with one method node. For example, you want to match the following methods:

private void performWork(int value);
public java.lang.String performWork(List entities);
public int performWork(int value1, long value2, double value3);

These three methods can all be matched with the following method node in the XML:


By removing the parameters node, all methods with the same name will be matched.

Class examples

Here are two classes which can be instrumented with a Java agent custom instrumentation XML file:

Class: package-test
package test;

import java.util.List;
import java.util.Map;

public class SampleTester {

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

  public SampleTester() {

  public SampleTester(String pConfigName) {
    configName = pConfigName;

  public void checkSample(String name, long[] times) {
    maxSampleTimes.put(name, getMax(times));

  private Long getMax(long[] times) {
    long max = 0;
    if (times != null) {
      for (long current : times) {
        if (current > max) {
          max = current;
    return Long.valueOf(max);

  protected static boolean isValidNames(List<String> names) {
    if (names == null) {
      return false;

    for (String current : names) {
      if (!isValidName(current)) {
        return false;

    return true;

  private static boolean isValidName(String name) {
    return (name != null && !name.isEmpty());

  public static int add (int one, int two) {
    return one + two;

Class: package com.sample
package com.sample;

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

public class CustomSample {

  public void sampleMethod() throws Exception {
    Runnable myRunnable = new Runnable() {

      public void run() {
        try {
        } catch (Exception e) {

    ScheduledExecutorService scheduledExecutor = Executors
    scheduledExecutor.scheduleWithFixedDelay(myRunnable, 0, 10000,

  private void firstPart() {
    System.out.println("In the first part.");

  private void secondPart() {
    System.out.println("In the second part.");


XML examples

Here is a sample XML file that instruments all of the methods in the two classes. For more examples, review the extension-example.xml file in the New Relic Java agent zip.

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

Sample XML instrumentation file
<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns=""
  xsi:schemaLocation="newrelic-extension extension.xsd "
    name="customExtension" version="1.0">
  <instrumentation metricPrefix="EXAMLE">

    <pointcut transactionStartPoint="true">
          <type attributeName="sampleName">java.lang.String</type>

    <pointcut transactionStartPoint="true">

    <pointcut transactionStartPoint="false" ignoreTransaction="false"


For more help

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at