Java agent API: Instrument using annotation

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:

@Trace
protected 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.

Type:	Boolean
Default:	`false`

If true, the agent will start a transaction when it reaches a method with this @Trace annotation if a transaction is not already in progress. If a transaction is already in progress, the method with this annotation will be included in the ongoing transaction, rather than starting a new one.

If false (default), no metrics will be recorded if the agent has not started a transaction before the @Trace annotation is reached. For example:

@Trace(dispatcher=true)

Type:	Boolean
Default:	`false`

If true, this method is marked as asynchronous and the agent will trace this method if it linked to an existing transaction. For example:

@Trace(async=true)

If false (default), the method is not marked as asynchronous. If other @Trace annotations are present and the method is not executing asynchronously, it will still be traced.

Type:	String
Default:	(none)

This property affects transaction traces and error reporting. By default, the metric name will include the class name followed by the method name. If you do not want class followed by method, then you can use this property to change the metric name.

If you set the metricName, as in @Trace(metricName="YourMessageHere"), then the time spent in this method will appear as YourMessageHere in any transaction trace.

If you set the metricName in addition to the dispatcher, as in @Trace(metricName="YourMessageHere", dispatcher=true), then the transaction name will appear as YourMessageHere in the APM Transactions page but the time spent in this method will not appear as YourMessageHere in any transaction trace.

Here is an example:

@Trace(metricName="YourMetricName")

Important

Do not use brackets [suffix] at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses (suffix) or other symbols if needed.

Type:	Boolean
Default:	`false`

If true, the method will be excluded from the transaction trace. The agent will still collect metrics for the method. Here is an example:

@Trace(excludeFromTransactionTrace=true)

Type:	Boolean
Default:	`false`

A leaf tracer has no child tracers. This is useful when you want all time attributed to the tracer, even if other trace points are encountered the tracer's execution.

Database tracers often act as a leaf so that all time is attributed to database activity, even if instrumented external calls are made. Here is an example:

@Trace(leaf=true)

If a leaf tracer does not participate in transaction traces, the agent can create a tracer with lower overhead. Here is an example:

@Trace(excludeFromTransactionTrace=true, leaf=true)

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.

Java agent API: Instrument using annotation

Important

Configure your agent for annotations

Tip

Create a new transaction

Add detail to your transactions

Convert a transaction to a web request

Important

Define your own @Trace annotation class

Properties for @Trace

`dispatcher`

`async`

`metricName`

Important

`excludeFromTransactionTrace`

`leaf`

More API functions

For more help

Java agent API: Instrument using annotation

Important

Configure your agent for annotations

Tip

Create a new transaction

Add detail to your transactions

Convert a transaction to a web request

Important

Define your own @Trace annotation class

Properties for @Trace

async

metricName

excludeFromTransactionTrace

leaf

More API functions

.css-s3mb0o{fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}.css-1bvd50p{width:1rem;height:1rem;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}For more help

`async`

`metricName`

`excludeFromTransactionTrace`

`leaf`

For more help