Extension and additional instrumentation modules

The Java agent is a fully-featured library that automatically collects data from many popular servers, frameworks, libraries, and datastores (for a full list, see Compatibility and requirements). It also has a significant feature set. However, there are always additional requests for functionality and instrumentation of new libraries. The Java agent provides extension modules for this purpose.

Extension modules fall into three general categories:

If your library isn't covered by the automatic instrumentation or by an instrumentation module, you can still collect data with custom instrumentation.

If you have feedback, questions, or problems with this instrumentation, create a post in New Relic's Explorers Hub, and tag your post with java_incubator.

Install extension modules

We recommend updating to the latest Java agent version before installing an extension module. To install an extension module:

  1. Download the appropriate .jar file from module lists below.
  2. Locate the directory that contains your newrelic.jar and newrelic.yml files. In that directory, create a sub-directory named extensions (if there is not already one there).
  3. Copy the .jar extension module you downloaded into the extensions directory.
  4. For Feature extension modules, update your newrelic.yml with feature-specific configuration.
  5. Restart your server.
  6. Send some traffic to the server or host that will exercise the feature or instrumentation.

Java agent extension modules are subject to the New Relic Java agent licenses, which are included in each module jar's LICENSE file.

Feature extension modules

Extension modules are additional libraries that add commonly-requested functionality.

To use the an extension module, download it and put it in the Extensions Directory.

Download link Download the module

The Class Histogram extension runs jmap periodically and generates ClassHistogramRowEvent and ClassHistogramStatsEvent data that you can query and chart. Querying this data can be useful when troubleshooting memory leaks as you can see the values over time.

You configure the Class Histogram extension the same way you configure the Java agent: using environment variables, system properties, or newrelic.yml. Here are available properties, with defaults:

  extensions:
    class_histogram:
      enabled: true   # true is the default if the extension is present
      classes_per_histogram: 50  # 50 is the default, and memory leak issues are usually in the highest 50 classes by bytes
      jmap_path: /your/jdk/bin   # The folder where the jmap binary lives. The default is $JAVA_HOME/bin.
      delay_between_calls_seconds: 60    # Length of the delay between executions to avoid frequent pauses
Download link Download the module

The Java Flight Recorder (JFR) reporter extension uses the JFR Event Streaming API and reports a continuous stream of JFR events as dimensional metrics. These metrics are used in the Real-time Java Profiling dashboard in New Relic One, and you can also query that data to create your own charts. This forms a great foundation on which to build JVM monitoring and observability tools. See Real-time Java profiling with JFR metrics to learn more about the reporter's functionality.

You configure the Java Flight Recorder Reporter extension the same way you configure the Java Agent, using environment variables, system properties, or newrelic.yml. The available properties, with defaults, are below. See Java Agent Configuration for more information about configuring this extension.

Incubator instrumentation modules

Incubator modules are experimental instrumentation, which we may build into the agent's automatic instrumentation in the future.

These are the incubator modules that are currently available:

Download link Download the module

This instrumentation module intercepts the following:

org.apache.camel.component.http.CamelServlet.resolve

To name the transaction so that web transactions have a finer grained name than the Camel servlet name, it uses this:

org.apache.camel.component.http.HttpConsumer.getPath()

To view the bytecode, use this terminal command:

javap -verbose -cp camel-2.12-FILENAME.jar org.apache.camel.component.http.CamelServlet
Download link Download the module
Java agent version 3.12.0 or higher

This instrumentation module samples C3P0 connection pools and reports busy and idle counts in metrics that start with this:

Custom/Database Connection/C3P0/METRIC_NAME

You can view the metrics with the metric explorer.

Download link Download the module

This instrumentation module integrates with the MetricRegistry and begins sampling the registered metrics every minute. Reported metrics are prefixed with this:

Custom/CodaHale/Metrics2/METRIC_NAME

You can view the metrics with the metric explorer.

Download link Download the module

This instrumentation module integrates with the MetricRegistry and begins sampling the registered metrics every minute. Reported metrics are prefixed with this:

Custom/CodaHale/Metrics3/METRIC_NAME

You can view the metrics with the metric explorer.

Download link Download the module
Java agent version 3.12.0 or higher

This instrumentation module samples HikariCP database connection pools and reports busy and idle counts in metrics that start with this:

Custom/Database Connection/HikariCP/METRIC_NAME

You can view the metrics with the metric explorer.

Download link Download the module
Java agent version 3.12.0 or higher

This instrumentation module samples HikariCP database connection pools and reports busy and idle counts in metrics that start with this:

Custom/Database Connection/HikariCP/METRIC_NAME

You can view the metrics with the metric explorer.

Download link Download the module
Java agent version 5.8.0 or higher
This instrumentation package instruments the Lettuce 4.x Redis driver. It enables calls to Redis to show up as datastore calls.

Download link Download the module
Java agent version 5.8.0 or higher

This instrumentation package instruments the Lettuce 5.x Redis driver. It enables calls to Redis to show up as datastore calls.

Download link Download the module
Java agent version 3.29 or higher

This instrumentation module adds support for async linking of Ratpack's execution primitives. It also monitors handler execution. You must name the transactions manually by using the Java agent API.

Download link Download the module

This instrumentation captures Ratpack's HTTP client requests and responses.

Archived instrumentation modules

Archived modules are instrumentation for libraries that are no longer maintained by the original company or author. Because the target library isn't being updated, our support for archived modules has designated end dates.

These are the archived modules that are currently available:

Download link Download the module
Java agent version 3.22.1 or higher
Support ends on December 2019

This module provides link instrumentation between actors that send and receive messages. It also traces messages broadcast by or forwarded to actors. In order to avoid over-instrumentation, this instrumentation does not start transactions. If you would like a given actor call to mark the beginning of a transaction, use the @Trace(dispatcher=true) annotation, or some other form of custom instrumentation.

Download link Download the module
Java agent version 3.22.1 or higher
Support ends on December 2019

This module provides link instrumentation between actors that send and receive messages. It also traces messages broadcast by or forwarded to actors. In order to avoid over-instrumentation, this instrumentation does not start transactions. If you would like a given actor call to mark the beginning of a transaction, use the @Trace(dispatcher=true) annotation, or some other form of custom instrumentation.

Download link Download the module
Java agent version 3.24.1 or higher
Support ends on December 2019

This module creates transactions from Akka HTTP calls. It also instruments hand-offs between Akka actors, and calls from Akka to other databases and services.

For calling systems, this instrumentation collects cross application traces. If you're using a supported Akka version, you can view activity from your Akka HTTP apps from transactions all the way through your actor systems.

Download link Download the module
Java agent version 3.24.1 or higher
Support ends on December 2019

This module creates transactions from Akka HTTP calls. It also instruments hand-offs between Akka actors, and calls from Akka to other databases and services.

For calling systems, this instrumentation collects cross application traces. If you're using a supported Akka version, you can view activity from your Akka HTTP apps from transactions all the way through your actor systems.

Download link Download the module
Java agent version 3.24.1 or higher
Support ends on December 2019

This module creates transactions from Akka HTTP calls. It also instruments hand-offs between Akka actors, and calls from Akka to other databases and services.

For calling systems, this instrumentation collects cross application traces. You can use this instrumentation together with our built previously released support for Akka, to view activity from your Akka HTTP apps from transactions all the way through to your actor systems.

Download link Download the module
Java agent version 3.23.0 or higher
Support ends on December 2019

This module provides timing information related to each Hystrix command. The agent will link chained Hystrix commands into one transaction.

Download link Download the module
Java agent version 3.23.0 or higher
Support ends on December 2019

This module provides timing information related to each Hystrix command. The agent will link chained Hystrix commands into one transaction.

Download link Download the module
Java agent version 3.23.0 or higher
Support ends on December 2019

This module provides timing information related to each Hystrix command. The agent will link chained Hystrix commands into one transaction.

Download link Download the module
Java agent version 3.24.1 or higher
Support ends on December 2019

This module creates and names transactions based on your Play controller classes.

Download link Download the module
Java agent version 3.24.1 or higher
Support ends on December 2019

This module creates and names transactions based on your Play controller classes.

Download link Download the module
Java agent version 3.24.1 or higher
Support ends on December 2019

This module creates and names transactions based on your Play controller classes.

Download link Download the module
Java agent version 3.34.0 or higher
Support ends on December 2019

This module instruments database calls to Solr servers, and collects detailed information about the Solr server itself. It also provides the database server and database name for the queries displayed in transaction traces and slow query traces.

Download link Download the module
Java agent version 3.34.0 or higher
Support ends on December 2019

This module instruments database calls to Solr servers, and collects detailed information about the Solr server itself. It also provides the database server and database name for the queries displayed in transaction traces and slow query traces.

Download link Download the module
Java agent version 3.34.0 or higher
Support ends on December 2019

This module instruments database calls to Solr servers, and collects detailed information about the Solr server itself. It also provides the database server and database name for the queries displayed in transaction traces and slow query traces.

For more help

Recommendations for learning more: