Install the Java agent on app servers and JVM frameworks

This page covers the standard installation path for the New Relic Java agent on any supported app server or JVM-based framework. Follow these steps to download the agent, configure it, and verify that data is flowing to New Relic.

Compatibility and requirements

Supported

Java 8, 11, 17, 21, 24, 25, and 26 (Java 7 supported on agent v6.5.4 and earlier only)
JVM-based languages: Java, Scala, Kotlin, and Clojure
App servers and frameworks: Tomcat, Spring Boot, JBoss/WildFly, Glassfish, Jetty, WebLogic, WebSphere, Grails, ColdFusion, Solr, Play, Resin, Tanuki Wrapper, and Geronimo — see compatibility and requirements for supported version ranges
Any JVM process that accepts a -javaagent argument

Not supported

Running alongside other APM agents — the Java agent cannot guarantee correct behavior when another APM agent is active in the same JVM

You need

A New Relic account and
A JVM with SHA-2 (256-bit) SSL support
Permission to edit your app server's startup scripts or JVM configuration
Permission to create a directory to hold the agent files

Install

Download the Java agent

Download newrelic-java.zip using one of these methods:

bash

$curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip
$unzip newrelic-java.zip

Invoke-WebRequest -Uri https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip -OutFile newrelic-java.zip
Expand-Archive -Path newrelic-java.zip -DestinationPath .

Download newrelic-java.zip from the Java agent release notes page.

After unzipping, the newrelic/ directory contains the agent jar (newrelic.jar) and configuration file (newrelic.yml) that you'll configure in the next steps.

Place the agent files

Create a permanent directory and move the agent files into it:

bash

$mkdir -p /opt/newrelic
$mv newrelic/* /opt/newrelic/

We recommend /opt/newrelic on Linux/macOS or C:\opt\newrelic on Windows. Make sure newrelic.jar is not on your application classpath or in any directory listed in java.endorsed.dirs.

Pass the `-javaagent` argument

Add the -javaagent flag to your app server's JVM startup configuration, pointing to the full path of newrelic.jar. The method differs per server — expand the one that matches your environment:

Choose the method for your Tomcat setup:

Create CATALINA_BASE/bin/setenv.sh if it doesn't exist, then add:

bash

$export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/newrelic/newrelic.jar"

Create CATALINA_BASE/bin/setenv.bat if it doesn't exist, then add:

SET "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:C:\opt\newrelic\newrelic.jar"

Select Start > Apache Tomcat X.Y.Z > Configure Tomcat > Java.
In the Java Options text box, enter the argument. Use forward slashes / for the path separator. For Tomcat 6, add a line break after the -javaagent argument.
```
-javaagent:/opt/newrelic/newrelic.jar
```
Select Apply, then restart Tomcat.

The version of Apache Commons Daemon (jsvc) bundled with Tomcat 6 does not support the -javaagent argument. A build from the trunk source supports it via the -X prefix. See the Apache bug report and Apache Commons source repository.

Edit domain/configuration/domain.xml and add the -javaagent option to your server group's JVM options:

<server-group name="main-server-group" profile="full">
    <jvm name="default">
        <jvm-options>
            <option value="-javaagent:/opt/newrelic/newrelic.jar"/>
        </jvm-options>
    </jvm>
</server-group>

Cuidado

A JBoss bug in 7.0.2.Final and 7.1.0.Alpha1 prevents JVM options from being set in domain.xml. Upgrade your JBoss app server if you encounter this.

Platform	Instructions
Unix/macOS — JBoss 6.x EAP or 7.0.x AS+	At the bottom of `bin/standalone.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar"`
Windows — JBoss 6.x EAP or 7.0.x AS+	In `bin/standalone.bat`, before `set JBOSS_ENDORSED_DIRS`, add: `set "JAVA_OPTS=-javaagent:C:\opt\newrelic\newrelic.jar %JAVA_OPTS%"`
Unix/macOS — JBoss 6.x or earlier	At the bottom of `bin/run.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar"`
Windows — JBoss 6.x or earlier	In `bin/run.bat`, before `set JBOSS_CLASSPATH`, add: `set "JAVA_OPTS=-javaagent:C:\opt\newrelic\newrelic.jar %JAVA_OPTS%"`

Dica

WildFly 11 or higher requires additional install steps.

Edit domain/configuration/domain.xml and add the -javaagent option to your server group's JVM options:

<server-group name="main-server-group" profile="full">
    <jvm name="default">
        <jvm-options>
            <option value="-javaagent:/opt/newrelic/newrelic.jar"/>
        </jvm-options>
    </jvm>
</server-group>

Platform	Instructions
Unix/macOS	At the bottom of `bin/standalone.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar"`
Windows	In `bin/standalone.bat`, after `rem Setup JBoss specific properties`, add: `set "JAVA_OPTS=-javaagent:C:\opt\newrelic\newrelic.jar %JAVA_OPTS%"`

From the Glassfish admin console, select Application Server > JVM Settings > JVM Options.
Select Add JVM Option and add:
```
-javaagent:/opt/newrelic/newrelic.jar
```
Save and restart Glassfish.
If Glassfish doesn't start, the -javaagent path may be incorrect. You can also set JVM arguments by editing domain.xml directly.
Importante
A bug in Glassfish 2.1 prevents classes on the bootstrap class loader from using the Java logging API. This is fixed in 2.1.1 and higher.

Edit JAVA_OPTIONS in your jetty.sh script:

bash

$export JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/opt/newrelic/newrelic.jar"

Add to your start.ini config file:

-javaagent:/opt/newrelic/newrelic.jar

Edit startWebLogic.sh in the domain's bin/ directory.

Near the beginning of the file, add:

bash

$export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/opt/newrelic/newrelic.jar"

Edit startWebLogic.bat in the domain's bin/ directory.

Near the beginning of the file, add:

set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:"C:\opt\newrelic\newrelic.jar"

For administration server instances, use the Linux/macOS or Windows instructions above — you cannot configure administration server instances through the admin console.

For managed server instances, use the admin console:

Navigate to Environments > Servers > (select a server) > Server Start > Arguments.
Add:
```
-javaagent:/opt/newrelic/newrelic.jar
```
Save and restart the server instance.

From the admin console, select Servers > Application servers > (select a server) > Configuration > Service Infrastructure > Java and Process Management.
Select Process Definition > Additional Properties, then select Java Virtual Machine.
In the Generic JVM arguments field, add:
```
-javaagent:/opt/newrelic/newrelic.jar
```
Select Apply, then Save.
Restart your server.
For more information, see collecting WebSphere PMI metrics.

Add the agent to JAVA_OPTS when running the startup command:

bash

$export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/newrelic/newrelic.jar" && startup

Edit ${server.config.dir}/jvm.options.
Add:
```
-javaagent:/opt/newrelic/newrelic.jar
```
Restart your server.

bash

$grails -noreloading -javaagent:/opt/newrelic/newrelic.jar run-app

In grails-app/conf/BuildConfig.groovy, add or edit:

grails.tomcat.jvmArgs = ["-javaagent:/opt/newrelic/newrelic.jar"]

Start your ColdFusion server and open the ColdFusion admin console.
From the left menu, select SERVER SETTINGS > Java and JVM.
If using the agent API, specify the path to newrelic-api.jar in the ColdFusion Class Path field.
In the JVM Arguments field, add:
```
-javaagent:/opt/newrelic/newrelic.jar
```
Select Submit Changes, then restart ColdFusion.

Add the -javaagent property to bin/solr.in.sh:

bash

$SOLR_OPTS="$SOLR_OPTS -javaagent:/opt/newrelic/newrelic.jar"

Add the -javaagent before start.jar:

bash

$java -javaagent:/opt/newrelic/newrelic.jar -jar start.jar

When running Solr inside an application server, follow the instructions for that app server (see the other entries in this list). Also ensure JMX is enabled. If Solr data doesn't appear in APM, see troubleshooting procedures for Solr data.

bash

$play run your_app_name -javaagent:/opt/newrelic/newrelic.jar

Start with an unzipped distribution containing the start script:
bash
```
$play clean dist && unzip dist/*.zip
```

Start with the -javaagent argument:

bash

$cd unzipped/folder; chmod a+x start; ./start -javaagent:/opt/newrelic/newrelic.jar

Start with an unzipped distribution:

bash

$play clean dist && unzip target/directory/universal/*.zip

Use the -J-javaagent prefix:

bash

$cd unzipped/folder; ./bin/scriptname -J-javaagent:/opt/newrelic/newrelic.jar

Start with an unzipped distribution:

bash

$activator clean dist && unzip target/directory/universal/*.zip

Use the -J-javaagent prefix:

bash

$cd unzipped/folder; ./bin/scriptname -J-javaagent:/opt/newrelic/newrelic.jar

If you use Typesafe Activator with Play 2.4, also add to build.sbt:
```
javaOptions ++= Seq("-javaagent:/opt/newrelic/newrelic.jar")
```

Add to the <jvm-args> section in conf/resin.conf or conf/resin.xml:

<jvm-arg>-javaagent:/opt/newrelic/newrelic.jar</jvm-arg>

The Java 9 module system can cause NoClassDefFoundError: java/sql/SQLException if -javaagent is added to conf/resin.conf or conf/resin.xml. Use one of these alternatives instead:

Option 1 — Command line:

bash

$java -javaagent:/opt/newrelic/newrelic.jar -jar lib/resin.jar start

Option 2 — Edit bin/resin.sh, modifying:

bash

$exec $JAVA_EXE -javaagent:/opt/newrelic/newrelic.jar -jar lib/resin.jar $@

Then start Resin with ./bin/resin.sh start.

In wrapper.conf, add a new wrapper.java.additional option. Replace XXX with an unused number in the file:

wrapper.java.additional.XXX=-javaagent:/opt/newrelic/newrelic.jar

Dica

On Linux, no quotation marks are needed around the path. This may vary on other operating systems.

Configure

Edit newrelic/newrelic.yml and set these two required values:

license_key: 'YOUR_LICENSE_KEY'
app_name: 'My Application'

The agent reads newrelic.yml from the same directory as newrelic.jar at startup. You can also override any setting using Java system properties (e.g. -Dnewrelic.config.license_key=YOUR_KEY) or environment variables.

When using the config file, restrict permissions to read/write for the owner of the application server process only:

bash

$chmod 600 /opt/newrelic/newrelic.yml

See Java agent configuration for all available options.

Verify your install

Restart your application server. Send at least two requests, then wait 2–3 minutes and your app appears in APM & services.

If no data appears after five minutes, see No data appears (Java).

Install the Java agent on app servers and JVM frameworks

Compatibility and requirements

Supported

Not supported

You need

Install

Download the Java agent

Place the agent files

Pass the `-javaagent` argument

Tomcat

Spring Boot

JBoss / WildFly

Cuidado

WildFly (standalone)

Dica

Glassfish

Importante

Jetty

WebLogic

WebSphere

Grails

ColdFusion

Solr

Play Framework

Resin

Tanuki Wrapper (Java Service Wrapper)

Dica

Geronimo

Configure

Verify your install

Install the Java agent on app servers and JVM frameworks

Compatibility and requirements .css-21sua1{background:none;border:none;width:0;padding:0;}

Supported

Not supported

You need

Install

Download the Java agent

Place the agent files

Pass the -javaagent argument

Spring Boot

JBoss / WildFly

WildFly (standalone)

Glassfish

Jetty

WebLogic

WebSphere

Grails

ColdFusion

Solr

Play Framework

Resin

Tanuki Wrapper (Java Service Wrapper)

Geronimo

Configure

Verify your install

Related articles

Compatibility and requirements

Pass the `-javaagent` argument