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 > APM > (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.
Do not instrument all of your methods, as this can lead to a metric grouping issue.
- 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
. Iffalse
, 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 ofextension
. It can have one attribute:metricPrefix
. This is the prefix used for the metric names when thenameTransaction
node is not specified. Default isCUSTOM
. - Pointcut (child of instrumentation)
-
The
pointcut
is a child node ofinstrumentation
and can have several attributes. Also, apointcut
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 wheretransactionStartPoint
is set tofalse
.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) andweb
(reported as a web transaction). - Child nodes for pointcut
-
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 attributeincludeSubclasses
. Iftrue
the methods on the class with the matching name will be instrumented along with the matching methods on any child class of this class. Iffalse
(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
totrue
.
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, themethod
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 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 bytype
elements. Here are the major rules for thetype
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, usejava.lang.String
. - Do not use generics with collection objects. For example, write
java.util.List
instead ofjava.util.List<String>
. - Include brackets for arrays. For example, an array of integers will be
int[ ]
and an array of strings will bejava.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 One, 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.
- Sample 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); } }
- Sample XML instrumentation file and explanation
-
<?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 theparameters
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.