Guide to using Java agent API

You can use the New Relic Java agent API to set up custom instrumentation of your Java app and collect more in-depth data.

This document is a goal-focused guide to using the Java agent API. In the tables below, find the objective you want to accomplish, and then select a link to be taken to the relevant section of the complete Java agent API Javadoc.

For best results when using the API, ensure that you have the latest Java agent release. Several APIs used in the examples require Java agent 3.36.0 or higher.

The Java agent also has an option for XML instrumentation. The XML option is simpler and doesn't require modification of your app code, but it lacks the complete functionality of the Java agent API.

API usage examples

For detailed code examples of the APIs in use, see:

Transactions

To instrument Transactions in your application, use the following APIs:

If your goal is... Use...
To create a Transaction when New Relic does not create one automatically... @Trace(dispatcher = true) on the method that encompasses the work to be reported.
To capture the duration of a method that New Relic doesn't automatically trace... @Trace() on the method you wish to time.
To set the name of the current Transaction... NewRelic.setTransactionName(...)
To start the timer for the response time of the current​ Transaction and to cause a Transaction you create to be reported as a Web transaction, rather than as an Other transaction... NewRelic.setRequestAndReponse(...)
To add custom attributes to Transactions and TransactionEvents... NewRelic.addCustomParameter(...)
To prevent a Transaction from being reported to New Relic... NewRelic.ignoreTransaction()
To exclude a Transaction when calculating your app's Apdex score... NewRelic.ignoreApdex()

Instrument asynchronous work

For detailed instructions, see Java agent API for asynchronous applications.

If your goal is... Use...
To trace an asynchronous method if it is linked to an existing Transaction... @Trace(async = true)
To link the Transaction associated with the Token on the current thread... Token.link() or Token.linkAndExpire()
To expire a Token associated with the current Transaction... Token.expire()
To stop timing a Segment and have it report as part of its parent Transaction... Segment.end()
To stop timing a Segment and not have it report as part of its parent Transaction Segment.ignore()

Trace calls to external services

To track external calls and add cross application tracing, use the following APIs:

If your goal is... Use...

To trace across a custom transport channel that New Relic does not support by default, such as a proprietary RPC transport...

Transaction.getRequestMetadata(), .processRequestMetadata(...), .getResponseMetadata(),
.processResponseMetadata(...)

See the Obtain references to New Relic entities table for details on using Transaction.

To view or change the metric name or a rollup metric name (a metric not scoped to a specific transaction, such as OtherTransaction/all, which represents all background transactions) of a TracedMethod...

TracedMethod.getMetricName(), .setMetricName(...), .setRollupMetricName(...)

See the Obtain references to New Relic entities table for details on using TracedMethod.

To report a call to an external HTTP service, database server, message queue, or other external resource that is being traced using the Java agent API's @Trace annotation...

TracedMethod.reportAsExternal(...) passing arguments constructed using ExternalParameters builder.

See the Obtain references to New Relic entities table details on using TracedMethod.

To enable and add cross application tracing when communicating with an external HTTP or JMS service that is instrumented by New Relic...

TracedMethod.addOutboundRequestHeaders(...) along with TracedMethod.reportAsExternal(...)

See the Obtain references to New Relic entities table for details on using TracedMethod.

To add timing for an application server/dispatcher that is not supported automatically...

Transaction.setRequest(...), Transaction.setResponse(...), or NewRelic.setRequestAndResponse(...), and Transaction.markResponseSent()

See the Obtain references to New Relic entities table for details on using Transaction.

Obtain references to New Relic entities

Other tasks require the New Relic Agent object. The Agent object exposes multiple objects that give you the following functionality:

If your goal is... Use...
To get a reference to the current Transaction... NewRelic.getAgent().getTransaction()
To get a Token to link asynchronous work... NewRelic.getAgent().getTransaction().getToken()
To start andget get a reference to a Segment... NewRelic.getAgent().getTransaction().startSegment()
To get a reference to the method currently being traced... NewRelic.getAgent().getTracedMethod()
To get a reference to the Agent logger... NewRelic.getAgent().getLogger()
To get a reference to the Agent configuration... NewRelic.getAgent().getConfig()
To get a reference to an aggregator for custom metrics... NewRelic.getAgent().getAggregator()
To get a reference to Insights in order to record custom events... NewRelic.getAgent().getInsights()

Additional API functionality

These APIs provide additional functionality, such as setting app server info, reporting errors, adding page load timing info, recording custom metrics, and sending custom events to Insights:

If your goal is... Use...
To explicitly set port, name, and version info for an application server/dispatcher and instance name for a JVM... NewRelic.setAppServerPort(...), .setServerInfo(...), and .setInstanceName(...)
To report an error that New Relic does not report automatically... NewRelic.noticeError(...)
To add browser page load timing for Transactions that New Relic does not add the header to automatically... NewRelic.getBrowserTimingHeader(), .getBrowserTimingFooter(), .setUserName(String name), .setAccountName(String name), and .setProductName(String name)
To create and accumulate custom metrics... NewRelic.recordMetric(...), .recordResponseTimeMetric(...), or .incrementCounter(...)

To record Insights custom events...

Insights.recordCustomEvent(...)

Use NewRelic.addCustomParameter(...) to add custom attributes to the New Relic-defined TransactionEvent type.

See the Obtain references to New Relic entities table for details on using Insights.

For more help

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.