New Relic's Java agent provides several options for custom instrumentation. One of those options is adding the Java agent API's @Trace
annotations to your application code. This document describes how to use annotations.
Important
To use annotations, you must modify the source code. If you can't or don't want to modify your source code, see Custom instrumentation for other instrumentation options.
Configure your agent for annotations
By default, the configuration setting enable_custom_tracing
is set to true
in the Java agent, which is the setting required for @Trace annotations to function. This setting is not included in the newrelic.yml
by default.
The only time you need to incorporate this setting into your configuration file is if you want to disable @Trace annotations altogether. To do this, set enable_custom_tracing: false
(prefaced with two spaces) in the common
stanza of your newrelic.yml
.
To detect custom traces:
Make sure that
newrelic-api.jar
appears in your classpath.Add
@Trace
annotations to your code. In each class containing a method you want to instrument, call:import com.newrelic.api.agent.Trace;Place the
@Trace
annotation on each target method.
Tip
The annotation com.newrelic.api.agent.Trace
is located in the newrelic-api.jar
.
Create a new transaction
If transactions do not appear and you want to start a new transaction, include dispatcher=true
with the @Trace
annotation:
@Trace (dispatcher=true)public void run() { // background task}
Add detail to your transactions
If your transaction traces show large blocks of uninstrumented time and you want to include some more methods within the trace, you can use the @Trace
annotation without parameters:
@Traceprotected void methodWithinTransaction() { // work}
Convert a transaction to a web request
To make a background task report as a web browser transaction with a Java agent API call: In the method annotated with @Trace(dispatcher=true)
, call:
NewRelic.setRequestAndResponse(Request request, Response response)
The arguments are implementations of the Request
and Response
interfaces in newrelic-api.jar
.
Important
Even if your Request
and Response
objects already are present, you still need to add this API call.
Define your own @Trace annotation class
If you define your own @Trace
annotation class, there is no dependency on the newrelic-api.jar
. To define the class:
package com.test;@Target(ElementType.METHOD)@Retention(RetentionPolicy.RUNTIME)public @interface Trace { public static final String NULL = ""; String metricName() default NULL; boolean dispatcher() default false; String tracerFactoryName() default NULL;}
Then, configure the agent to use this annotation in the common
section of the newrelic.yml
:
class_transformer: trace_annotation_class_name: com.test.Trace
Properties for @Trace
The @Trace
annotation supports the following properties.
More API functions
For more about the Java agent API and its functionality, see the Java agent API introduction.
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.