New Relic's Java agent collects and reports information on web transactions and non-web transactions, such as background tasks. The agent should instrument supported frameworks automatically, without any need to modify your application code. However, in addition to custom code and frameworks or technology not listed in the Compatibility and requirements for the Java agent documentation, some implementations of supported frameworks may require custom instrumentation.
This document describes how to use the Java agent API to instrument external calls, messaging frameworks, cross application tracing (CAT), datastores, and web frameworks. 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 External API enables applications to report external service calls to New Relic. This information appears on the External services page in APM. To report HTTP external activity, simply create an instance of
ExternalParameters using the
HttpParameters builder, and call
reportAsExternal(ExternalParameters parameters) on the traced method you want to report.
There are several builders to create
These builders create the input parameter object for
reportAsExternal API call. These parameter objects are used for things like linking HTTP external calls via cross application tracing, tracing external calls to a datastore, tracing external calls to a datastore with additional slow query processing, as well as tracing calls between message producers and consumers.
All of the methods of this class have the potential to expose sensitive private information. Use caution when creating the arguments, paying particular attention to URIs and string values.
The cross application tracing (CAT) API allows the New Relic Java agent to link transactions across applications monitored by New Relic. The API uses client and server wrappers that allow the agent to read headers from requests, and add headers to responses.
For the agent to write outbound request headers in the client initiating the request, use the
OutboundHeaders interface. For example:
For the agent to read inbound response headers in the client receiving the response, implement the
InboundHeaders. For example:
For the agent to get web request headers, you must extend the
For the agent to set the web response headers, implement the
Using the wrapper objects described in the previous sections, you can enable the Java agent to do cross application tracing (CAT) on the client and server side. For example:
In this sample code, the agent is configured to report an external call using CAT on the client that is initiating the request. These steps can be summarized as follows:
InboundHeadersusing framework classes on the client.
addOutboundRequestHeaders(OutboundHeaders outboundHeaders)to have the agent add appropriate headers to the outbound request.
HttpParametersbuilder and provide inbound response headers.
- Report as an external request using
In this sample code, the agent is configured to report an external call using CAT on the server that is responding to the request. These steps can be summarized as follows:
Responseand extend the
ExtendedRequestclass using framework classes on the server.
setWebResponse(Response response)to convert the transaction into a web transaction and together provide the agent with the inbound request headers and a place to record the outbound headers.
It's important to use both
setWebResponse(Response response)together, because the transaction name depends on the request object, and the response code depends on the response object.
addOutboundResponseHeaders()to have the agent add appropriate headers to the outbound response.
Mark the end of the response with a call to
The messaging API allows applications to report interactions with message queue brokers. It builds on top of the External API by providing the
This API generates the necessary metrics to identify message broker interactions. The UI will use these metrics to display messaging data including segments in transactions with the appropriate action and count (message put, or message take), a dedicated messages tab in transaction traces, and more. Providing inbound and outbound headers to the API also allows the agent to add CAT headers, and record CAT metrics, which enables the UI to draw service maps that show connections between applications.
The messaging API relies on two-way communication between producers and consumers. If your producer does not receive an acknowledgment from a consumer, like in a fire-and-forget pattern, the messaging API will not accurately reflect the interactions with message queue brokers.
The following example demonstrates how to instrument a fictional JMS library.
To simplify things, the agent assumes that
sendMessageToQueue always puts a message in a named queue. In reality, a message can be sent to different destination types, including named queues, temporary queues, topics, and temporary topics. The API provides an enum to report messages to different destination types:
TEMP_TOPIC. It's important to specify the appropriate destination type because the UI will display the names of named queues and named topics and will omit the names of temporary queues and temporary topics.
If the library is capable of transmitting CAT headers, an
OutboundHeaders object will be provided to the API so that the agent can add CAT headers.
When a traced method is reported as an external datastore call, the call is shown in the APM Databases page. Because datastores are external to the running application, the method is reported as datastore activity using the
reportAsExternal(ExternalParameters params) method. The only difference is that a different builder,
DatastoreParameters, is used to create the appropriate
This API call provides the same behavior as the Datastore API call and extends it to allow slow query information to be tracked. The same
reportAsExternal(ExternalParameters params) method and builder are used, but with an additional builder method.
The WebFrameworks API allows the agent to report additional identifying information about the application.
// Set the dispatcher name and version which is reported to APM.// The dispatcherName is intended to represent the type of server that this// application is running on such as: Tomcat, Jetty, Netty, etc.NewRelic.setServerInfo(String dispatcherName, String version)// Set the app server port which is reported to APM.NewRelic.setAppServerPort(int port)// Set the instance name in the environment.// A single host:port may support multiple JVM instances.// The instance name is intended to help identify a specific JVM instance.NewRelic.setInstanceName(String instanceName)
These values can be set only once. Subsequent calls will have no effect.
Additional documentation resources include:
- New Relic Java agent API Javadoc (detailed API documentation on GitHub)
- Java agent API example (example application using custom instrumentation for cross application tracing and external datastore calls)
- Java agent API guide (goal-driven guide to using the Java agent API)
- Java instrumentation by annotation (how to use annotations to instrument your application code)