Java agent manual installation

New Relic includes a Java self-installer for Tomcat, Jetty, JBoss, and Glassfish. Other platforms may still require manual editing of the start scripts.

Download the files

To download the Java agent:

  1. Log in to New Relic.

  2. From the account dropdown in the New Relic UI, select Account settings.

  3. Download the agent for your platform.

The .zip file includes two required files for installation:

  • newrelic.jar: This contains the agent class files.
  • newrelic.yml: This contains configuration information for the New Relic agent, including your license key, application name, SSL settings, etc. Recommendation: Change the default newrelic.yml file permissions to be read/write only for the owner of the app server process.

On server startup, the agent will search for the newrelic.yml file in the directory containing the newrelic.jar file. New Relic writes the agent log to a sub-directory in the same location, named logs.

screen manual java download.png
From the (account dropdown) in the New Relic UI, select Account settings.

Install the Java agent

To manually install the Java agent:

  1. Review the Java agent compatibility and requirements.
  2. In your app server's root directory, create a new directory named newrelic.
  3. Unpack the downloaded file into the newrelic directory.

  4. In newrelic.yml, set the app_name setting to a meaningful name.
  5. Back up the newrelic.yml configuration file before proceeding.

  6. Follow the installation instructions for your platform, and start or re-start your app server with the -javaagent:/path/to/newrelic.jar argument passed to the JVM.

  7. Log in to the New Relic APM site to see your app's performance information.

Wait a few minutes for the application data to appear in the APM Overview page.

Platform-specific install notes

Follow the installation instructions for your platform.

See ColdFusion installation.

For Apache Geronimo, refer to the New Relic agent jar in the JAVA_OPTS environment variable when running the startup command:

  -javaagent:/full/path/to/newrelic.jar" && geronimo run
See Glassfish installation.
See Grails installation.
See JBoss installation.

The Jetty startup script ( can be configured using the JAVA_OPTIONS environment variable:


The -javaagent switch should reference the full path to the newrelic.jar file.

If the exec is used in the start.ini file instead of a file, add the New Relic agent path to the start.ini config file:

Play 1.x
See Play installation.
Play 2.x or higher
See Play 2 installation.

For Resin installation, add the -javaagent to the jvm-args section in your resin.conf or resin.xml (Resin 4.x):


For a standalone Solr instance, add the -javaagent before the start.jar:

java -javaagent:/full/path/to/newrelic.jar -jar start.jar

For a standalone Solr instance (5.x.x and above), add the -javaagent property to bin/

SOLR_OPTS="$SOLR_OPTS -javaagent:/full/path/to/newrelic.jar"

When running Solr in an application server, follow the instructions of that application server to add the javaagent flag. Also ensure that JMX is enabled for the application server. If you have problems seeing data in the New Relic APM UI's SOLR page, refer to the troubleshooting procedures.

Tanuki Wrapper

When using the Tanuki wrapper, add an option such as to the file wrapper..conf where ## is an unused number in this file.

If 50 is the highest used variable of this type currently in use (meaning, you might use the following example:

On Linux systems, no quotation marks are required when setting this value. This behavior may vary on other operating systems.


The Tomcat startup script ( can be configured to use the New Relic agent using the JAVA_OPTS environment variable:


Make sure the -javaagent switch references the full path to the newrelic.jar file.

In addition:

See WebLogic installation.

See WebSphere installation.

For WebSphere Community Edition, refer to the New Relic agent jar in the JAVA_OPTS environment variable when running the startup command:

  -javaagent:/full/path/to/newrelic.jar" && startup
WebSphere Liberty Profile
See WebSphere Liberty Profile Installation.
See WildFly installation.
Other application servers
The New Relic Java agent should work on any application server if you pass the -javaagent:/path/to/newrelic.jar switch to the JVM before the application jar.

For more help

Additional documentation resources include:

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at