Install the Java agent

Our Java agent auto-instruments your code so you can start monitoring applications. We show you here how to complete a basic Java agent installation.

1. Before you install

Check the following:

2. Get the agent

Download newrelic-java.zip using curl or the New Relic UI:

Download using curl

Complete the following:

  1. Start a command-line session.
  2. Change to a temporary directory where you can download the zip file.
  3. Execute this curl command:
    curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip
  4. Unzip newrelic-java.zip
Download from the New Relic UI

Complete the following:

  1. Log in to New Relic.

  2. From the account dropdown in the New Relic UI, select Account settings.

  3. In the right sidebar under Most recent, select the Java agent, and save the newrelic-java.zip to a temporary directory.

  4. Unzip newrelic-java.zip.

3. Configure the agent

Here's how to do a basic setup with agent configuration settings in newrelic.yml.

For an advanced installation, you can pass settings with environment variables, Java system properties, or server-side configuration. To understand the precedence of these configuration settings, see Java agent configuration: Config file.

The Java agent requires the license_key and app_name settings at startup. All the other settings are optional, and you can review them in Java agent configuration: Config file.

Go to the unzipped installation file, and inside the newrelic subdirectory, edit newrelic.yml:

  1. Find the line with license_key.
  2. Replace '<%= license_key %>' with your license. For example:

    license_key: 456n20n1367ov2s174v51nvn789d21s67v26NRAL
  3. Find the line with app_name.
  4. Replace My Application with a name that helps you identify the application. For example:
    app_name: Tax Calculator

    If you need tips about how to name your application, see Name your application.

  5. Add optional settings that you want, such as agent logging and distributed tracing (or add them later).
  6. Save and close newrelic.yml.

4. Install the agent

The Java agent installation involves copying all the unzipped New Relic files into the directory structure of your application server/container. For example, you can create a /opt/newrelic directory, but if you want to put the files elsewhere, make sure of the following:

  • The .jar files in the directory cannot be on the classpath.
  • The .jar files cannot be in directories specified in java.endorsed.dirs.

To install the Java agent:

  1. In your application server/container directory structure, create a directory for New Relic files (for example, /opt/newrelic).
  2. Copy all the New Relic files from your unzipped newrelic directory into your new directory.
  3. Make sure that your application server/container includes this option when it starts Java (for tips on how to do this with your tool or framework, see JVM arguments):
    -javaagent:/full/path/to/newrelic.jar
  4. Start or restart your application server/container.

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

5. Post-installation tasks

If you are using newrelic.yml to make configuration settings, consider the following:

  • We recommend you change the default newrelic.yml file permissions to read/write only for the owner of the application server process.
  • As you would with other important files, be sure newrelic.yml is part of your backup routine.

What's next?

Here are some additional topics to consider:

For more help

Recommendations for learning more: