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 New Relic menu bar, select (account) > 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 New Relic menu bar, select Account settings from the menu bar under your account name.

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.

Coldfusion
See ColdFusion installation.
Geronimo

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

export JAVA_OPTS="$JAVA_OPTS 
  -javaagent:/full/path/to/newrelic.jar" && geronimo run
Glassfish
See Glassfish installation.
Grails
See Grails installation.
JBoss
See JBoss installation.
Jetty

The Jetty startup script (jetty.sh) can be configured using the JAVA_OPTIONS environment variable:

export JAVA_OPTIONS="${JAVA_OPTIONS}
  -javaagent:/full/path/to/newrelic.jar"

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 Jetty.sh file, add the New Relic agent path to the start.ini config file:

javaagent:/usr/local/newrelic-3.15.0/newrelic/newrelic.jar
Play 1.x
See Play installation.
Play 2.x or higher
See Play 2 installation.
Resin

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

<jvm-arg>-javaagent:/full/path/to/newrelic.jar</jvm-arg>
Solr

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

java -javaagent:/full/path/to/newrelic.jar -jar start.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 wrapper.java.additional.## 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 wrapper.java.additional.50), you might use the following example:

wrapper.java.additional.51=-javaagent:/full/path/to/newrelic.jar

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

Tomcat

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

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

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

In addition:

WebLogic
See WebLogic installation.
Websphere

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:

export JAVA_OPTS="$JAVA_OPTS
  -javaagent:/full/path/to/newrelic.jar" && startup
WebSphere Liberty Profile
See WebSphere Liberty Profile Installation.
Wildfly
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 support.newrelic.com.