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, @TraceLambda or @TraceByReturnType annotations to your application code. This document describes how to use annotations.

Annotations are enabled by default

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. If you want to disable annotations, set enable_custom_tracing: false (prefaced with two spaces) in the common section of your newrelic.yml.

@Trace

Annotating a method with @Trace tells the Java agent that measurements should be taken for that method.

To add a method call as a custom trace add @Trace annotations to your method. Make sure that newrelic-api.jar appears in your classpath as it contains all these annotations.

import com.newrelic.api.agent.Trace;

...

  @Trace
  public void run() {
    // background task
  }

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.

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.

@Trace(dispatcher=true)

@Trace(async=true)

@Trace(metricName="YourMetricName")

@Trace(excludeFromTransactionTrace=true)

@Trace(leaf=true)

@Trace(excludeFromTransactionTrace=true, leaf=true)

@TraceLambda

This feature is disabled by default and must be explicitly enabled (e.g. -Dnewrelic.config.instrumentation.trace_lambda.enabled=true) for the annotations to take effect. The equivalent environment variable is NEW_RELIC_INSTRUMENTATION_TRACE_LAMBDA_ENABLED.

If your transaction traces show large blocks of uninstrumented time and you want to include lambda expressions within the trace, you can use the @TraceLambda annotation without parameters:

import com.newrelic.api.agent.TraceLambda;

@TraceLambda
class ClassContainingLambdaExpressions() {
  // work
}

Lambda expressions become static methods of the containing class after compilation. By default, static methods within classes marked with the @TraceLambda annotation matching the annotations pattern will be marked with the @Trace annotation.

Properties for @TraceLambda

The @TraceLambda annotation supports the following properties.

@TraceLambda(pattern="YourPattern")

@TraceLambda(includeNonstatic="true")

@TraceByReturnType

To include methods with a particular return type within the trace, you can use the @TraceByReturnType annotation to mark a class passing the return types as a property. Methods in annotated classes that match one of the specified return types will be marked with the @Trace annotation.

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  // ...
}

Properties for @TraceByReturnType

The @TraceByReturnType annotation supports the following properties.

@TraceByReturnType(traceReturnTypes={Integer.class, String.class})
class ClassContainingMethods() {
  public String doSomething() { // matches
    // ...
  }

  public Long somethingElse() { // does not match
    // ...
  }
}

Performance considerations

When the Java agent is present in the JVM, it will inject code on the annotated methods. The performance hit is negligible in heavyweight operations, such as database or webservice calls, but is noticeable in methods that are called frequently, such as an accessor called thousands of times a second.

More API functions

For more about the Java agent API and its functionality, see the Java agent API introduction.