In the modern software world of continuous integration and continuous deployment (CI/CD), application code changes and deploys routinely happen multiple times a day. In this new era of rapid innovation and change, APIs are becoming an increasingly popular way to empower users to build customized, integrated solutions that cater to their specific needs.

That’s why we are thrilled to announce that New Relic customers running Java applications now have the option of using our rich Java agent API to add custom instrumentation to their applications and gain unprecedented insight and visibility into their applications. These new capabilities are designed to let customers instrument their apps and develop a greater understanding of the behavior of their Java applications. With significant new functionality, our Java agent API supports both synchronous and asynchronous communications.

Synchronous and asynchronous

There are two basic ideologies that most developers follow when building applications that talk to each other: synchronous and asynchronous.

Synchronous communication models are generally used when applications depend on each other for processing information. But a new focus on minimizing latency and building applications with really fast response times is making asynchronous programming models—and the APIs that support them—increasingly popular.

The benefits of the asynchronous model can be illustrated with a simple analogy. Imagine that you run a taco truck. If the truck runs on a synchronous model, after each customer ordered, your employees would need to process the order, make the food, and deliver the food before you ask the next customer for their order.

But if you ran your truck with an asynchronous taco-production model, then you would be able take new orders even as you were cooking and serving the previous customers’ tacos. You would be able to sell more tacos to more people in a shorter amount of time, and make more customers happy.

Similarly, an asynchronous programming model lets your programs execute more tasks than synchronous programs that spend much of their time waiting. 

Powerful new API calls

Among other new functionality, our new Java Agent API supports a number of new API calls, explained here:

Create transactions: Creating meaningful transactions is critical to understanding the control flow of your code. With the New Relic Java agent APIs, you can create transactions on synchronous and asynchronous methods by adding an @Trace(dispatcher = true) annotation to any transaction that is not created automatically by New Relic. Adding this annotation gives you a breakdown of your transaction execution, including all timed methods, wait time for your asynchronous application method calls, database calls (if applicable), and capture errors thrown by your created transactions. And if there are methods in your application that are not automatically timed by New Relic, you can add an @Trace annotation API call to start timing them.

For asynchronous applications, in addition to the @Trace(dispatcher = true) annotation, you have to create and link tokens for New Relic to stitch together transactions. A getToken() method call creates a Token for linking asynchronous work to the current Transaction. A single Token can be passed between multiple threads of work that should be linked to the transaction. This token can be expired using token.expire(). This allows the transaction to end.

Once you instrument your transactions using the above API calls, they will show up in your New Relic APM dashboards, as shown in this screenshot:

java agent api New Relic APM dashboard screenshot

[click to enlarge]

For each of these transactions, a trace is collected:

transaction trace screenshot

[click to enlarge]

Time methods: For each transaction, you can see which calls are asynchronous, and how long those methods may take. Monitoring which calls are made at what time—and the control flow of your transactions—helps you notice irregularities quickly and understand your app’s behavior more easily.

Determine wait time: Not only can you time how long it takes for individual methods to run, but you can measure the time from when work gets created to when it gets executed. For example, you can see how long a piece of work is waiting to execute in a thread pool. (In the screenshot below, for example, the work waited in a threadpool for 126 ms to dispatch.)

Monitor DB calls: In New Relic APM’s Datastore tab, you can see external calls that your application has made, the response time for those calls, and how many requests happen per minute.

New Relic APM Datastore tab example

Show which errors are occurring: The error rate and the frequency of your most common errors in your async application are also visible with the asynchronous APIs. Below is an example of an error page for an app throwing a duplicate keys error. Seeing the errors your app generates can mean faster resolution and happier users.

error rate screenshot

[click to enlarge]

More new functionality

In addition to transactions, New Relic APIs now expose rich functionality such as the ability to create and accumulate custom metrics, notice errors explicitly, and trace across custom transport channels. You can now report a call to an external HTTP service, database server, message queue, or other external resource that is being traced using the Java agent APIs, and add cross application tracing when communicating with an external HTTP or JMS service that is instrumented by New Relic. For a full list of the supported API calls, please refer to our detailed API guide.

Using the New Relic Java agent APIs to instrument your custom framework is designed to lead to deeper insights, faster error recognition, and enhanced understanding of the behavior of your application. No matter how your framework or applications evolve, these APIs can help transform the way you understand your application.


Alexa Stefanko is an engineer on the Java agent team. She hails from the Bay Area but decamped to Portland to enjoy its dormant volcanoes and artisan pickles. When not thinking about software, she enjoys long-distance running with her dog and talking about movies. View posts by .

Interested in writing for New Relic Blog? Send us a pitch!