5 ways to customize your New Relic Java agent

There are lots of ways to customize your agent in New Relic APM and New Relic Insights, but it’s not always easy to figure out which approach is right for your particular needs. Let’s take a quick run-through of the various options and what they do, and give you a sense of what’s involved in using them.

This post covers the New Relic Java Agent, and you can find more information in the Java Agent Custom Instrumentation Overview, which addresses the technical approaches for customization from Annotation to XML to the UI Instrumentation Editor. You can see the source code for my examples in this GitHub repository: https://github.com/kenahrens/spring-­travel. We plan to address other New Relic Agents in upcoming blog posts.

There are lots of ways to customize your agent in New Relic APM and New Relic Insights, but it’s not always easy to figure out which approach is right for your particular needs. Let’s take a quick run-through of the various options and what they do, and give you a sense of what’s involved in using them.

This post covers the New Relic Java Agent, and you can find more information in the Java Agent Custom Instrumentation Overview, which addresses the technical approaches for customization from Annotation to XML to the UI Instrumentation Editor. You can see the source code for my examples in this GitHub repository: https://github.com/kenahrens/spring-­travel. We plan to address other New Relic Agents in upcoming blog posts.

Custom transaction naming

New Relic Agents have out-of-the-box rules for how transactions are named in the UI. Unfortunately, sometimes these rules don’t work for your environment, so the Agent API lets you easily modify the Transaction Name to suit your needs.

Be aware that the specific API call varies by language, and you need to place the code in a place where it is called on every Transaction. See below for an example of the Java code:

import com.newrelic.api.agent.NewRelic;

...

public class JpaBookingService implements BookingService {

...

    public List findHotels(SearchCriteria criteria) {

        NewRelic.setTransactionName("Web", "Find Hotels");

        ...

    }

...

}

(See the New Relic documentation on Naming Web Transactions for details about how the Java Agent determines the name for your transaction: https://docs.newrelic.com/docs/agents/java-­agent/instrumentation/naming­-web­-transactions.)

Custom tracers

New Relic Agents include out-of-the-box support for many technology frameworks. Sometimes, however, the framework you use may not be supported, or you may be using a proprietary framework created for internal use at your company.

In those cases, you can create Custom Tracers to add visibility to a framework that New Relic is currently not monitoring. This lets you monitor the performance down to an individual method in your code. Note that the specific API call (or use of XML) varies by language. Additional visibility will show up inside Transaction Traces.

Here’s an example breakdown of what goes into making a Custom Tracer. In this snippet from our GitHub repository, the “blue bubble” shows that time is spent somewhere in HotelsMvcController.list(). We added additional instrumentation using an XML extension. To work, this file should be placed in NEWRELIC_HOME/extensions.

<?xml version="1.0" encoding="UTF-8"?>

<extension xmlns="https://newrelic.com/docs/java/xsd/v1.0"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="newrelic-extension extension.xsd "

    name="extension-example"

    version="1.0" enabled="true">

    <instrumentation>

        <pointcut transactionStartPoint="true"

            excludeFromTransactionTrace="false"

            ignoreTransaction="false">

            <className>org.springframework.samples.travel.services.JpaBookingService</className>

            <method>

                <name>slowThisDown</name>

            </method>

        </pointcut>

    </instrumentation>

</extension>

(For more information, see our Java Instrumentation by XML documentation: https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml.)

Custom attributes

New Relic Agents collect standard attributes (also called parameters) for every Transaction. But you may have special attributes unique to your application that you want to collect as well. These custom attributes show up in Transaction Traces as well as Insights Events.

The Agent API makes it easy to add Custom Attributes. In Java, for example, simply place this code from our GitHub repository where it is called on every Transaction:

import com.newrelic.api.agent.NewRelic;

...

public class JpaBookingService implements BookingService {

...

    public List findHotels(SearchCriteria criteria) {

        ...

        String pattern = getSearchPattern(criteria);

        log.debug("search pattern: " + pattern);

        NewRelic.addCustomParameter("searchCriteria",pattern );

        ...

    }

...

}

(For more information, see Insights Custom Attributes in the New Relic documentation: https://docs.newrelic.com/docs/insights/new-relic-insights/decorating-events/insights-custom-attributes.)

Custom events

Custom Events are used when you want to record several pieces of metadata that all belong together as part of a “rich event,” typically one that occurs on an irregular basis. For example, you might want to record an event whenever a booking is made and include data such as Revenue, Hotel Name, Hotel City, and so on.

Through the Agent API, these Custom Events can be added as a new Event Type in Insights.

To add a Custom Event, you would create a map showing the relevant Key / Value pairs, and then publish the event using the API. Here’s an example in Java:

HashMap bookingMap = new HashMap();

bookingMap.put("BookingNumberOfNights",booking.getNights() );

bookingMap.put("BookingRevenue",

    Integer.valueOf(booking.getTotal().intValue()) );

bookingMap.put("BookingRate",

    Integer.valueOf(booking.getHotel().getPrice().intValue() ) );

bookingMap.put("BookingHotelName",

    booking.getHotel().getName() +

    " - " + booking.getHotel().getCity() +

    ", " + booking.getHotel().getState() );

...

bookingMap.put("BookingAgent",booking.getUser().getName() );

NewRelic.getAgent().getInsights().recordCustomEvent("Booking Event", bookingMap);

(For more information, see Inserting Custom Events Via New Relic APM Agents: https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/inserting-custom-events-new-relic-apm-agents.)

Custom metrics

Out of the box, New Relic supports standard non-transactional metrics. But Custom Metrics can be used to record special metrics—including most arbitrary numeric values, such as the revenue value of a completed booking on the Spring Travel application shown below. Custom Metrics can be displayed in Custom Dashboards, or used in Alert Policies. Basically, Custom Metrics can be used for anything numeric that you want to monitor and graph.

To use Custom Metrics, simply add a call to send the numeric metric with a name like Custom/Metric Name. Here’s an example in Java:

import com.newrelic.api.agent.NewRelic;

...

public class JpaBookingService implements BookingService {

...

    public void persistBooking(Booking booking) {

        ...

        NewRelic.recordMetric("Custom/Booking Revenue",

            Integer.valueOf(booking.getTotal().intValue()) );

        ...

    }

...

}

(For more information on why you use Custom Metrics within APM, see Custom Metrics in the New Relic documentation: https://docs.newrelic.com/docs/data­-analysis/metrics/custom­-metrics

Other languages

The post addressed the New Relic Java Agent, but the process is similar for all languages supported by New Relic. We plan to address other New Relic Agents in upcoming blog posts.