Install Java agent using Gradle

There are two primary methods for using New Relic APM with a Gradle application:

  • Use Gradle to download and unzip the newrelic-java.zip file, which contains all New Relic Java agent components.
  • Use Gradle to install individual New Relic Java agent components.

These methods are described in more detail below.

For general information about how to download and install the Java agent, see Install the agent.

Method 1: Download complete Java agent package

This section explains how to configure Gradle to download and unzip the newrelic-java.zip file, which contains all New Relic Java agent components. The newrelic-java.zip contains all files needed to run the Java agent, including:

  • newrelic.yml (agent configuration file)
  • newrelic.jar (Java agent jar)
  • newrelic-api.jar (Java agent API jar)
  • README

You can place the yml file wherever you want, as long as you specify it in the JVM arg:

-Dnewrelic.config.file

If you do not want to specify it, then you must place the ymlfile in the same folder as the agent jar.

1: Configure build.gradle to add the newrelic-java.zip dependency

Pull down the Java agent zip file.

An example of how to do this is to add the following two parts to your build.gradle file.

plugins {
    id "de.undercouch.download" version "3.4.3"
}

This is the plugin we will be using to download the agent. Next add a task to download the zip file. Below is an example task that does that.

task downloadNewrelic(type: Download) {
    mkdir 'newrelic'
    src 'https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip'
    dest file('newrelic')
}

2: Configure build.gradle to unzip the newrelic-java.zip dependency

Create a task to unzip the zip file. Below is an example task that does that.

task unzipNewrelic(type: Copy) {
    from zipTree(file('newrelic/newrelic-java.zip'))
    into rootDir
}
3. Configure the agent

To download and unzip the agent files using the tasks above, run the following two commands from the root directory of your project.

./gradlew downloadNewrelic
./gradlew unzipNewrelic

This will download the newrelic-java.zip file into a newrelic/ directory and then unzip it in the same directory.

After downloading and unpacking the Java agent files, you will need to:

  1. Configure the newrelic.yml file (or JVM system properties) with your license_key and app_name.
  2. Pass -javaagent:/path/to/newrelic.jar to the JVM running your application server.
  3. If using the New Relic Java agent API, make the API jar available at compile time by adding it to your application class path.

For more information, see the install and configuration documentation.

Method 2: Download individual Java agent components

This section explains how to configure Gradle to download individual components of the Java agent, specifically the newrelic.jar and the newrelic-api.jar.

1. Configure build.gradle to add the New Relic Java agent jar

Pull down the newrelic.jar.

A standard way to do this is to add the following to your Gradle's build.gradle file. You would replace JavaAgentVersion with the latest Java agent version.

dependencies {
    compile group: 'com.newrelic.agent.java', name: 'newrelic-agent', version: 'JavaAgentVersion'
}
2. Optional: Configure build.gradle to add the New Relic API jar

Pull down the newrelic-api.jar.

A standard way to do this is to add the following to your Gradle's build.gradle file. You would replace JavaAgentVersion with the latest Java agent version:

dependencies {
    compile group: 'com.newrelic.agent.java', name: 'newrelic-api', version: 'JavaAgentVersion'
}
3. Configure the agent

You will need the newrelic.yml that you receive when you create a New Relic account or one that is downloaded for the version of the agent that you are using.

After downloading and unpacking the Java agent files you will need to:

  1. Configure the newrelic.yml file (or JVM system properties) with your license_key and app_name.
  2. Pass -javaagent:/path/to/newrelic.jar to the JVM running your application server.
  3. If using the New Relic Java agent API, make the API jar available at compile time by adding it to your application class path.

For more information, see the install and configuration documentation.

Examples of build.gradle for zip and individual components

Example of build.gradle configuration for newrelic-java.zip deployment

Here is an example build.gradle file for working with the zip file.

plugins {
    id 'java'
    id "de.undercouch.download" version "3.4.3"
}

group 'example_group'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

task downloadNewrelic(type: Download) {
    mkdir 'newrelic'
    src 'https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip'
    dest file('newrelic')
}

task unzipNewrelic(type: Copy) {
    from zipTree(file('newrelic/newrelic-java.zip'))
    into rootDir
}
Example of build.gradle configuration for deployment of individual components

Here is an example build.gradle for working with the individual components (Java agent and API jars).

plugins {
    id 'java'
}

group 'example_group'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    compile group: 'com.newrelic.agent.java', name: 'newrelic-agent', version: '4.11.0'
    compile group: 'com.newrelic.agent.java', name: 'newrelic-api', version: '4.11.0'
}

For more help

Recommendations for learning more:

Recommendations for learning more: