Include the Java agent with a JVM argument

This document describes how to pass the -javaagent argument to the JVM for your framework. This installation step ensures the agent is included in your app. For all app servers, ensure you pass the full path to the newrelic.jar file.

This document is simply a reference for how to pass the argument. For detailed installation procedures, see Java agent installation.

ColdFusion

To pass the -javaagent argument on ColdFusion:

Start your ColdFusion server and navigate to your 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 the -javaagent argument:
```
-javaagent:/full/path/to/newrelic.jar
```
Select Submit Changes, then restart your ColdFusion server.

Geronimo

To pass the -javaagent argument on Geronimo, refer to the New Relic agent jar in the JAVA_OPTS environment variable when running the startup command:

bash

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

Glassfish

To pass the -javaagent argument on Glassfish:

From the Glassfish console, select Application Server > JVM Settings > JVM options.
On the JVM options page, select Add JVM option.
Add an entry for the -javaagent argument:
```
-javaagent:/full/path/to/newrelic.jar
```
Save and restart Glassfish.

If Glassfish does not start, the -javaagent argument might not have been set correctly. You can change the server JVM arguments by editing the domain.xml file.

Important

A bug in Glassfish 2.1 prevents classes on the bootstrap class loader (the New Relic agent) from using the Java logging API. This appears to be fixed in 2.1.1 or higher releases.

Grails

To pass the -javaagent argument on Grails:

JBoss

To pass the -javaagent argument on JBoss:

Use domain mode for JBoss versions 6.x EAP and 7.0 AS or above:

Edit the JVM properties for your server group, located in:
```
domain/configuration/domain.xml
```
Modify the properties to include the -javaagent argument:
```
<server-group name="main-server-group" profile="full">
  <jvm name="default">
    <jvm-options>
      <option value="-javaagent:/full/path/to/newrelic.jar"/>
    </jvm-options>
  </jvm>
  ...
</server-group>
```
Caution
A JBoss bug in 7.0.2.Final and 7.1.0.Alpha1 does not allow JVM options to be set in domain.xml. If you encounter this problem, upgrade your JBoss application server.

Use standalone mode for other platforms and versions:

Platform	Directions
Unix or macOS with 6.x EAP or 7.0.x AS and above	At the bottom of `bin/standalone.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/newrelic.jar"`
Windows with 6.x EAP or 7.0.x AS or higher	In `bin/standalone.bat`, before the line: `set JBOSS_ENDORSED_DIRS=%JBOSS_HOME%\lib\endorsed` Add: `set "JAVA_OPTS=-javaagent:C:/full/path/to/newrelic.jar %JAVA_OPTS%"`
Unix or macOS with 6.x or earlier	At the bottom of `bin/run.conf`, add this: `JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/newrelic.jar"`
Windows with 6.x or earlier	In `bin/run.bat`, before the line: `set JBOSS_CLASSPATH=%RUN_CLASSPATH%` Add: `set "JAVA_OPTS=-javaagent:C:/full/path/to/newrelic.jar %JAVA_OPTS%"`

Jetty

To pass the -javaagent argument on Jetty:

Play

To pass the -javaagent argument on Play:

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

Append the -javaagent argument when starting your Play app:

bash

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

Begin with an unzipped distribution containing the start script:
bash
```
$play clean dist && unzip target/directory/universal/*.zip
```
Append the -J-javaagent argument when starting your Play app:
bash
```
$cd unzipped/folder; ./bin/scriptname -J-javaagent:/full/path/to/newrelic.jar
```
Tip
To enable page load timing, see Manual instrumentation with Play 2.2.

Begin with an unzipped distribution containing the start script:
bash
```
$activator clean dist && unzip target/directory/universal/*.zip
```

Append the -J-javaagent argument when starting your Play app:

bash

$cd unzipped/folder; ./bin/scriptname -J-javaagent:/full/path/to/newrelic.jar

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

Resin

Java 8

Option 1: Add the javaagent argument via the jvmargs property in server's resin.properties file:
```
jvm_args  : -javaagent:/full/path/to/newrelic.jar
```
Option 2: Specify the -javaagent argument by adding it to the <jvm-args> section in your conf/resin.conf or conf/resin.xml file:
```
<jvm-arg>-javaagent:/full/path/to/newrelic.jar</jvm-arg>
```

Java 9 or higher

The module system introduced in Java 9 can lead to the exception NoClassDefFoundError: java/sql/SQLException if the -javaagent property is added to the conf/resin.conf or conf/resin.xml files. If you're using Java 9 or higher make sure that the -javaagent property is not included in those files.

Resin can be run on Java 9 or higher, with the Java agent using one of the following options:

Option 1: Add the javaagent argument via the jvmargs property in server's resin.properties file:
```
jvm_args  : -javaagent:/full/path/to/newrelic.jar
```
The Resin server can then be run with ./bin/resin.sh start.
Option 2: Run resin jar with the -javaagent property on the command line:
bash
```
$java -javaagent:/path/to/newrelic.jar -jar lib/resin.jar start
```

Important

The agent will not work with Resin on Windows when using Java 9 or higher.

Solr

To pass the -javaagent argument on Solr:

Spring Boot

To pass the -javaagent argument on Spring Boot, add it to the command line in which you start your app. Make sure to add it before the -jar argument:

bash

$java -javaagent:/full/path/to/newrelic.jar -jar app.jar

Tanuki Wrapper

To pass the -javaagent argument on Tanuki Wrapper, add a wrapper option wrapper.conf. In the line below, substitute XXX for an unused number in this file:

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

Tip

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

Tomcat

To pass the -javaagent argument on Tomcat:

Create a CATALINA_BASE/bin/setenv.sh script if one doesn't already exist. Configure your setenv.sh script to use the New Relic agent using the CATALINA_OPTS environment variable:

bash

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

Create a CATALINA_BASE/bin/setenv.bat script if one doesn't already exist. Configure your setenv.bat script to use the New Relic agent using the CATALINA_OPTS environment variable:

SET "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:/full/path/to/newrelic.jar"

Tip

We recommend that you do not set any variables in this script. Instead put them into a script setenv.sh in CATALINA_BASE/bin to keep your customizations separate.

Configure your catalina.sh file to use the New Relic agent using the JAVA_OPTS environment variable:

bash

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

Tip

We recommend that you do not set any variables in this script. Instead put them into a script setenv.bat in CATALINA_BASE/bin to keep your customizations separate.

If you use catalina.bat to launch Tomcat, set the JAVA_OPTS variable near the top of the file:

SET JAVA_OPTS=%JAVA_OPTS% -javaagent:/full/path/to/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:/full/path/to/newrelic.jar
```
Select Apply, then restart Tomcat.

The version of Apache Commons Daemon (jsvc) included with Tomcat 6 does not support the -javaagent argument used by New Relic. However, a build of the jsvc daemon from the trunk source will support the -javaagent argument via the -X prefix. See the Apache bug tracking the issue.

There is a fix in the Apache Commons source repository. For more information:

See the Apache source repository documentation.
Go directly to the SVN source repository.

WebLogic

To pass the -javaagent argument on WebLogic:

For administration server instances, follow the Linux/macOS or Windows instructions. You cannot use the administration console to install administration server instances.

For managed server instances, use the admin console:

From the administration console, navigate to Environments > Servers > (select a server) > Server Start > Arguments.
From Arguments, add:
```
-javaagent:/full/path/to/newrelic.jar
```
Save the page, then restart your server instance.

WebSphere

To pass the -javaagent argument on WebSphere:

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 the -javaagent argument for your newrelic.jar file:
```
-javaagent:/full/path/to/newrelic.jar
```
Select Apply, then select Save.
Restart your server.

For more information, see the documentation about collecting WebSphere PMI metrics.

WebSphere Community

To pass the -javaagent argument on WebSphere Community Edition, refer to the New Relic agent jar in the JAVA_OPTS environment variable when running the startup command:

bash

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

WebSphere Liberty Profile

To pass the -javaagent argument on WebSphere Liberty Profile:

Edit ${server.config.dir}/jvm.options.
Add the -javaagent argument to point to your newrelic.jar file:
```
-javaagent:/full/path/to/newrelic.jar
```
Restart your server.

Wildfly

To pass the -javaagent argument on Wildfly (if using Wildfly 11 or higher, see additional install instructions):

Edit the JVM properties for your server group, located in:
```
domain/configuration/domain.xml
```

Modify the properties to include the -javaagent argument:

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

Platform	Directions
Unix or macOS	At the bottom of `bin/standalone.conf`, add: `JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/newrelic.jar"`
Windows	In `bin/standalone.bat`, find this line: `rem Setup JBoss specific properties` Then add: `set "JAVA_OPTS=-javaagent:C:/full/path/to/newrelic.jar %JAVA_OPTS%"`

Platform

Directions

Unix or macOS

At the bottom of bin/standalone.conf, add:

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

Windows

In bin/standalone.bat, find this line:

rem Setup JBoss specific properties

Then add:

set "JAVA_OPTS=-javaagent:C:/full/path/to/newrelic.jar %JAVA_OPTS%"

Other application servers

The New Relic Java agent works on any supported app server. If your app server is not listed in this document, follow standard procedures for your app server to pass this argument to the JVM before the app jar:

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

Include the Java agent with a JVM argument

ColdFusion .css-21sua1{background:none;border:none;width:0;padding:0;}

Geronimo

Glassfish

Important

Grails

Pass with run-war

JBoss

Set with domain mode (6.x EAP and 7.0 AS)

Set with standalone mode (other versions)

Jetty

If you set exec in jetty.sh

If you set exec in start.ini

Play

Play 1.2.4

Play 2.0

Play 2.2

Play 2.3, 2.4, and 2.5

Resin

Important

Solr

Standalone Solr 5.x or higher

Standalone Solr 4.x or lower

App server Solr

Spring Boot

Tanuki Wrapper

Tip

Tomcat

With setenv.sh

With setenv.bat

With catalina.sh (NOT RECOMMENDED)

With catalina.bat (NOT RECOMMENDED)

With Windows

With Apache Commons daemon

WebLogic

Administration servers on Linux or macOS

Administration servers on Windows

Managed server instances

WebSphere

WebSphere Community

WebSphere Liberty Profile

Wildfly

Set with domain mode

Set with standalone mode

Other application servers

ColdFusion

If you set exec in `jetty.sh`

If you set exec in `start.ini`