• /
  • Log in
  • Free account

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.


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:

  1. Make sure that newrelic-api.jar appears in your classpath.

  2. Add @Trace annotations to your code. In each class containing a method you want to instrument, call:

    import com.newrelic.api.agent.Trace;
  3. Place the @Trace annotation on each target method.


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:

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.


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;
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:

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:

Create issueEdit page
Copyright © 2021 New Relic Inc.