Install the Java agent

This document details how to download and install the Java agent. Before installing the agent, review the Java agent compatibility and requirements. To learn more about what New Relic APM for Java does, see Introduction to New Relic for Java.

Install overview

The install instructions in this document are for a standard Java agent installation. However, some setups have specific install documentation that you should read first:

Install the agent from New Relic UI

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. In the right sidebar, download the agent for your platform.

The downloaded 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, etc. New Relic recommends you 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 searches for newrelic.yml in the directory that contains newrelic.jar. New Relic writes the agent log to a sub-directory in the same location, named logs. For more information, see Startup configuration.

Install agent with cURL

To download the New Relic APM Java agent with cURL:

  1. To get the most recent version, run:


    To see all agent versions, go to the agent download page. Note: not all versions are supported.

  2. Add your New Relic license key to the template newrelic.yml file, located in the folder containing newrelic.jar. For more on this, see Startup configuration.

Install the agent

To install the Java agent:

  1. In your app server's root directory, create a new directory named newrelic.
  2. Unpack the agent zip file you downloaded into the newrelic directory.

  3. In newrelic.yml, set the app_name setting to a meaningful name. For more methods of naming your application, see Name your Java application.
  4. Back up the newrelic.yml configuration file.

  5. Pass this switch to the JVM, including any additional requirements for your framework:

  6. If you use these tools or frameworks, see these documents for additional steps:

  7. Start or restart your app server.

Generate some traffic for your app, then wait a few minutes for data to appear in the APM Overview page. If nothing appears, follow the troubleshooting procedures.

What's next?

After you install the agent on your Java app, here are some suggested next steps:

For more help

Recommendations for learning more: