Compatibility and requirements for the Java agent

New Relic's Java agent includes built-in instrumentation of the most popular parts of the Java ecosystem, including app servers, frameworks, databases, and message queuing systems. For frameworks and libraries that are not instrumented out of the box, you can extend the agent with Java custom instrumentation.

Requirements to install the agent

Before you install the Java agent, ensure your system meets these requirements:

JVM

Fully supported:

  • IBM JVM versions 7 and 8 for Linux
  • OpenJDK JVM versions 7 to 12 for Linux, Windows, and OS X
  • Oracle Hotspot JVM versions 7 to 12 for Linux, Solaris, Windows, and OS X
  • Amazon Coretto JVM versions 8 for Linux, Windows, and OS X
  • Azul Zulu JVM versions 8 to 12 for Linux, Windows, and OS X

Supported only with Java agent 4.3.x [ZIP | 2.8 MB] legacy agent:

  • Apple Hotspot JVM version 6 for OS X
  • IBM JVM version 6
  • Oracle Hotspot JVM version 6.0 for Linux, Solaris, Windows, OS X

Supported only with Java agent 2.21.x [ZIP | 2.8 MB] legacy agent:

  • Oracle Hotspot JVM version 5.0 for Linux, Solaris, Windows, OS X (Java SE 5.0)
  • Oracle JRockit up to and including 1.6.0_50
Security requirements

As a standard security measure for data collection, your app server must support SHA-2 (256-bit). SHA-1 is not supported.

Automatically instrumented frameworks and libraries

After you install the Java agent, it automatically instruments many popular frameworks and libraries. With automatic instrumentation, the agent collects rich data out of the box, and data will show up in your New Relic dashboards within minutes of installation. Even if your library is not automatically instrumented, you can still collect data with custom instrumentation and the Java agent API.

The agent automatically instruments these frameworks and libraries:

App/Web servers

The agent automatically instruments the following app/web servers. To install the Java agent on supported app/web servers, see Install the Java agent.

  • ColdFusion 10
  • Glassfish 3.0 to 5.x
  • JBoss 6.1.0 to AS 7.x
  • JBoss EAP 6.x to 7.x
  • Jetty 7.5.4 to 9.x
  • Mule ESB 3.4 to 3.8.x
  • Netty 3.4 to 4.x
  • Resin 3.1.9 to 4.0.x
  • Spray-can 1.3.1 or higher
  • Tomcat 7 to 9.x
  • TomEE 1.5 or higher
  • WebLogic 12.1.2.1 to 12.2.x
  • WebSphere 8.5.x to 9.x
  • WebSphere Liberty Profile 8.5.5.3 to 18.x
  • WildFly 8 to 10.x
  • WildFly 11 to 15.x
Frameworks and libraries

The agent automatically instruments the following frameworks. To install the Java agent on supported frameworks, see Install the Java agent.

  • Akka 2.0 to 2.5 async tracking
  • Amazon S3 (Simple Storage Service)
  • CXF
  • Grails 1.3.7 to 2.3.x
  • Hibernate 3.x to 4.x
  • Hystrix 1.0.2 to 1.5.x
  • JAX-RS 1.0 to 2.0
  • JCache API
  • Jersey 1.x to 2.x
  • JSF (Java Server Faces)
  • Play 1.2.4
  • Play 2.0.3 to 2.7.x
  • Quartz Job Scheduler 1.8.3 to 2.2.x
  • Spray 1.3.x
  • Spring 3.x to 4.x
  • Spring 5.x including WebFlux and WebClient
  • Spring Boot 1.4.x or higher
  • Struts 2
  • Thrift 0.8.0 or higher
  • Vert.x 3.3.0 to 3.6.x
HTTP and messaging

The agent automatically instruments the following HTTP clients and messaging services. For instructions, see Install the Java agent.

  • Akka HTTP 1.x to 2.5.x
  • Akka HTTP 10.0 to 10.1.x
  • Akka HTTP Client 10.0 to 10.1.x
  • AsyncHttpClient 1.0.2 to 2.5.x
  • HttpAsyncClient 4.1 or higher
  • HttpClient 3.0.1 to 4.x
  • java.net (HttpURLConnection)
  • JMS 1.1 and Spring-JMS
  • Kafka Clients 0.10.0.0 or higher (for metric and event data)
  • Kafka Clients 0.11.0.0 or higher (for distributed tracing, metric, and event data)
  • OkHttp 3.0 to 3.12.x
  • RabbitMQ 2.7 to 5.0.x (AMQP and JMS)
  • Spray-client 1.3.x
Datastores

New Relic currently supports MySQL and PostgreSQL to capture explain plans for slow database queries.

  • Amazon DynamoDB 1.11.106 or higher
  • DataStax Cassandra 2.1.2 to 3.2.0 (If you use high security, see slow_query_whitelist.)
  • DB2 9.1 to 10.x
  • Derby 10.6.1.0 to 10.x
  • Generic JDBC (any JDBC compliant driver)
  • H2 1.0.x to 1.4.x
  • HSQL 1.7.2.2 to 2.x
  • INet Oracle Driver (Oranxo) 3.06, 3.14
  • INet MERLIA 7.0.3, 8.04.03, and 8.06
  • Jedis Redis driver 1.4 to 2.10.x
  • jTDS 1.2 to 1.3.x
  • MariaDB 1.1.7 or higher
  • Microsoft SQL Server 2.0 to 4.2
  • Mongo 2.12.0 to 2.13.3, 3.1 to 3.3
  • MongoDB Java driver 2.12.0 to 3.4.x
  • MySQL mysql-connector-java-5.1.4 to 8.0.x
  • Oracle ojdbc14, ojdbc5, ojdbc6, ojdbc7
  • Postgres postgressql-8.x or higher
  • Spymemcached 2.11.0 to 2.12.x
  • Sybase (jConnect) JDBC 3 driver
Instance-level database information

New Relic collects instance details for a variety of databases and database drivers. The ability to view specific instances and the types of database information in New Relic APM depends on your New Relic agent version.

New Relic's Java agent versions 3.33.0 or higher support the following:

  • Any compatible JDBC driver
  • Amazon DynamoDB 1.11.106 or higher
  • DataStax Cassandra driver 2.1.2, 3.0 to 3.1
  • Jedis Redis driver 1.4 to 2.10.x
  • Mongo 2.12.0 to 2.13.3, 3.1 to 3.3
  • Spymemcached 2.11.0 to 2.12.x

Exception: Instance-level information is not reported for calls to the getBulk() API method.

The Java agent reports the database name and database server/identifier attributes on slow query traces and transaction traces for these database drivers. To request instance-level information from additional datastores, get support at support.newrelic.com.

Hosting services
You can install the Java agent on a variety of hosting services, including ones not listed below. Here are detailed installation guides for particular hosting services:
Asynchronous instrumentation

For supported frameworks, the Java agent usually instruments async work automatically. However, you can use the Java agent API to extend this instrumentation.

Other instrumented features
  • EJB Session Beans 3.0 or higher
  • JMX
  • JSP (Java Server Pages) 2.0 to 2.2
  • Scala 2.9.3 to 2.12.x

Connect the agent to other New Relic products

The Java agent integrates with other New Relic products to give you end-to-end visibility:

Product Integration
New Relic Browser The Java agent automatically injects the Browser JavaScript agent when you enable auto-instrumentation. After enabling Browser injection, you can view Browser data in the APM Overview page and quickly switch between the APM and Browser data for a particular app. For configuration options and manual instrumentation, see New Relic Browser and the Java agent.
New Relic Infrastructure When you install the Infrastructure and APM agents on the same host, they automatically detect one another. You can then view a list of hosts in the APM UI, and filter your Infrastructure hosts by APM app in the Infrastructure UI. For more information, see New Relic APM data in Infrastructure.
New Relic Insights The Java agent sends default events and attributes to Insights for NRQL queries. You can also record custom events for advanced analysis.
New Relic Synthetics Synthetic transaction traces connect requests from Synthetics monitors to the underlying APM transaction.

For more help

Additional documentation resources include:

Recommendations for learning more: