Update the Java agent

To take full advantage of New Relic's latest features, enhancements, and important security patches, we recommend you update your Java agent to the latest version. For additional information about specific agent updates, refer to the Java agent release notes.

These update procedures describe how to replace some of the current contents of your agent root directory, which contains the New Relic Java agent (newrelic.jar), with newly downloaded contents from the New Relic UI.

Update to latest version

To identify which version of the Java agent you're currently using, run java -jar newrelic.jar -v. Your Java agent version will be printed to your console.

Then, to update to the latest Java agent version:

  1. Back up the entire Java agent root directory to another location. Rename that directory to NewRelic_Agent#.#.#, where #.#.# is the agent version number.
  2. Go to rpm.newrelic.com/apm > (account dropdown) > Account settings.
  3. Download the agent for your platform.
  4. Unzip the new agent download file, then copy newrelic-api.jar and newrelic.jar into the original Java agent root directory.
  5. Diff your current newrelic.yml with the newly downloaded newrelic.yml from the zip, and update customized differences as needed.
  6. Restart your Java dispatcher.

If you experience issues after the Java agent update, restore from the backed-up New Relic agent directory.

Update agent config differences

If differences between the two versions are unrelated to your app's customizations, align the newrelic.yml you use moving forward with the latest updates to the default newrelic.yml from New Relic.

For example, if you diff the default newrelic.yml files for Java agent versions 3.29.0 and 3.30.0, the results printed to the console will be:

➜ diff newrelic_3.29.0.yml newrelic_3.30.0.yml
254a255,265
> # Classes loaded by classloaders in this list will not be instrumented.
> # This is a useful optimization for runtimes which use classloaders to
> # load dynamic classes which the agent would not instrument.
> classloader_excludes:
> groovy.lang.GroovyClassLoader$InnerLoader,
> org.codehaus.groovy.runtime.callsite.CallSiteClassLoader,
> com.collaxa.cube.engine.deployment.BPELClassLoader,
> org.springframework.data.convert.ClassGeneratingEntityInstantiator$ObjectInstantiatorClassGenerator,
> org.mvel2.optimizers.impl.asm.ASMAccessorOptimizer$ContextClassLoader,
> gw.internal.gosu.compiler.SingleServingGosuClassLoader,
> 

These lines were added to the default newrelic.yml in Java agent version 3.30.0. If you want to run Java agent version 3.30.0 or higher, ensure you include these lines in your newrelic.yml.

Java agent versions not supported

End of life notification: As of January 26, 2015, New Relic will no longer accept data from Java agent versions earlier than 3.6.0, except version 2.21.7.

These agent versions use an out-of-date protocol when communicating with New Relic's data collection services. In addition, many of these versions contain a potential security issue where they may incorrectly send sensitive data to the New Relic collector.

Update unsupported agent versions

If you are updating from an older agent version, including major version jumps, review the following list for changes in functionality.

Migration Comments
5.0.0

Release notes: Java agent 5.0.0

Self installer:

The New Relic Java agent's self-installer has been removed in order to provide a more consistent user experience. To install the Java agent, add the full path to the newrelic.jar to the -javaagent flag in your JVM options. For more information, see the documentation on installing the agent on specific application servers, including Docker, Maven, or Gradle.

Deprecated instrumentation:

The following instrumentation modules have been moved out of the default Java agent. They are now provided as a separate download. To continue using these modules, just add them to the agent's extensions directory in your New Relic folder or wherever your extensions directory is configured. Deprecated modules include:

  • Akka 2.0
  • Akka 2.1
  • Akka-http 1.0
  • Akka-http 2.0 - 2.4.1
  • Akka-http 2.4.2 - 2.4.4
  • Hystrix 1.2
  • Hystrix 1.3
  • Play 1: Instrumentation for Play-1.x is not available as an extension.
  • Play 2.0
  • Play 2.1
  • Play 2.2
  • Solr 3.1 - 3.4
  • Solr 3.5
  • Solr 3.6
4.12.0

Release notes: Java agent 4.12.0

Deprecated APIs:

The custom transport channel API is now deprecated in favor of the distributed tracing API.

The skipTransactionTrace attribute on the @Trace annotation is now deprecated. Instead, use the excludeFromTransactionTrace attribute.

Deprecated instrumentation:

JetS3t: Removed built-in instrumentation for JetS3t. The agent will continue to report external calls made with the JetS3t client.

4.4.0

Release notes: Java agent 4.4.0

Java 6 support removed:

You must use 4.3 or earlier.

EU data center:

Minimum version required for use in EU datacenter.

Removed the SSL configuration option:

SSL is now always used in communication with New Relic servers. The newrelic.yml ssl configuration and -Dnewrelic.config.ssl system property are no longer used. Setting either value to anything other than true will result in logging a warning.

Legacy agent 2.21.7

Release notes: Java agent 2.21.7

Java SE 5.0:

This is a bugfix release for the legacy Java SE 5.0 version of the agent. Unless you are a Java SE5 user, use the latest version of the New Relic Java agent. This affects:

  • Oracle Hotspot JVM version 5.0 for Linux, Solaris, Windows, OS X
  • Oracle JRockit up to and including 1.6.0_50

For more help

Recommendations for learning more: