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:

1. Start your ColdFusion server and navigate to your ColdFusion admin console.
2. From the left menu, select SERVER SETTINGS > Java and JVM.
3. If using the agent API: Specify the path to newrelic-api.jar in the ColdFusion Class Path field.

4. In the JVM Arguments field, add the -javaagent argument:

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

5. 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:

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

Glassfish

To pass the -javaagent argument on Glassfish:

1. From the Glassfish console, select Application Server > JVM Settings > JVM Options.

2. On the JVM Options page, select Add JVM Option.

3. Add an entry for the -javaagent argument:

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

4. 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.

Grails

To pass the -javaagent argument on Grails:

Pass with run-app

1. Begin with an unzipped version of Grails.

2. Run this command:

   grails -noreloading -javaagent:/full/path/to/newrelic.jar run-app

Pass with run-war

1. In your Grails app, open this file with your text editor:

   grails-app/conf/BuildConfig.groovy

2. Add or edit the JVM arguments line:

   grails.tomcat.jvmArgs = ["-javaagent:/full/path/to/newrelic.jar"]

JBoss

To pass the -javaagent argument on JBoss:

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

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

1. Edit the JVM properties for your server group, located in:

   domain/configuration/domain.xml

2. 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>

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.

Set with standalone mode (other versions)

Use standalone mode for other platforms and versions:

Platform	Directions
Unix / 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 / 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:

If you set exec in jetty.sh

Edit the JAVA_OPTIONS in your jetty.sh script:

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

If you set exec in start.ini

Add the agent path to your start.ini config file:

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

Play

To pass the -javaagent argument on Play:

Play 1.2.4

Append the -javaagent argument when running your Play application:

play run your_app_name -javaagent:/full/path/to/newrelic.jar

Play 2.0

1. Begin with an unzipped distribution containing the start script:

   play clean dist && unzip dist/*.zip

2. Append the -javaagent argument when starting your Play app:

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

Play 2.2

1. Begin with an unzipped distribution containing the start script:

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

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

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

To enable page load timing, see Manual instrumentation with Play 2.2.

Play 2.3, 2.4, and 2.5

1. Begin with an unzipped distribution containing the start script:

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

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

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

3. 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

To pass the -javaagent argument on Resin, add it to the <jvm-args> section in your resin.conf or resin.xml file:

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

Solr

To pass the -javaagent argument on Solr:

Standalone Solr 5.x or higher

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

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

Standalone Solr 4.x or lower

Add the -javaagent before the start.jar:

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

App server Solr

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 don't see data in the APM UI's Solr page, follow the troubleshooting procedures for Solr data.

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:

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

Tomcat

To pass the -javaagent argument on Tomcat:

With catalina.sh

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

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

With catalina.bat

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

With Windows

1. Select Start > Apache Tomcat X.Y.Z. > Configure Tomcat > Java.

2. 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

3. Select Apply, then restart Tomcat.

With Apache Commons daemon

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:

Administration servers on Linux or macOS

1. Edit your startWebLogic.sh file, located in the domain's bin directory.

2. Near the beginning of the file, add:

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

Administration servers on Windows

1. Edit your startWebLogic.bat file, located in the domain's bin directory.

2. Near the beginning of the file, add:

   set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:"C:\full\path\to\newrelic.jar"

Managed server instances

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:

1. From the administration console, navigate to Environments > Servers > (select a server) > Server Start > Arguments.

2. From Arguments, add:

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

3. Save the page, then restart your server instance.

WebSphere

To pass the -javaagent argument on WebSphere:

1. From the admin console, select Servers > Application servers > (select a server) > Configuration > Service Infrastructure > Java and Process Management.
2. Select Process Definition > Additional Properties, then select Java Virtual Machine.

3. In the Generic JVM arguments field, add the -javaagent argument for your newrelic.jar file:

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

4. Select Apply, then select Save.
5. 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:

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

WebSphere Liberty Profile

To pass the -javaagent argument on WebSphere Liberty Profile:

1. Edit ${server.config.dir}/jvm.options.

2. Add the -javaagent argument to point to your newrelic.jar file:

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

3. Restart your server.

Wildfly

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

Set with domain mode

1. Edit the JVM properties for your server group, located in:

   domain/configuration/domain.xml

2. 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>

Set with standalone mode

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

For more help