Install Java agent using Maven

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

  • Use Maven to download and unzip the newrelic-java.zip file, which contains all New Relic Java agent components.
  • Use Maven 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 Maven 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 pom.xml to add the newrelic-java.zip dependency

Pull down the Java agent zip file.

The standard way to do this is to add the following to your pom.xml file in the <dependencies> section. Replace JavaAgentVersion with the latest Java agent version.

<dependency>
  <groupId>com.newrelic.agent.java</groupId>
  <artifactId>newrelic-java</artifactId>
  <version>JavaAgentVersion</version>
  <scope>provided</scope>
  <type>zip</type>
</dependency> 
2: Configure pom.xml to unzip the newrelic-java.zip dependency

Configure the maven-dependency-plugin in your pom.xml to unzip the newrelic-java.zip file.

Below is one common way this can be done. The newrelic/ directory will be created in the project.build.directory (aka target/ directory as per Maven) and will contain the unzipped Java agent files.

     <!-- Unzip New Relic Java agent into target/ -->
     <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.1.1</version>
        <executions>
          <execution>
            <id>unpack-newrelic</id>
            <phase>package</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeGroupIds>com.newrelic.agent.java</includeGroupIds>
              <includeArtifactIds>newrelic-java</includeArtifactIds>
              <!-- you can optionally exclude files -->
              <!-- <excludes>**/newrelic.yml</excludes> -->
              <overWriteReleases>false</overWriteReleases>
              <overWriteSnapshots>false</overWriteSnapshots>
              <overWriteIfNewer>true</overWriteIfNewer>
              <outputDirectory>${project.build.directory}</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
3. Configure the agent

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 Maven to download individual components of the Java agent, specifically the newrelic.jar and the newrelic-api.jar.

1. Configure pom.xml 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 Maven's pom.xml. You would replace JavaAgentVersion with the latest Java agent version.

<dependency>
  <groupId>com.newrelic.agent.java</groupId>
  <artifactId>newrelic-agent</artifactId>
  <version>JavaAgentVersion</version>
  <scope>provided</scope>
</dependency>
2. Optional: Configure pom.xml 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 maven pom.xml. You would replace JavaAgentVersion with the latest Java agent version:

<dependency>
  <groupId>com.newrelic.agent.java</groupId>
  <artifactId>newrelic-api</artifactId>
  <version>JavaAgentVersion</version>
  <scope>compile</scope>
</dependency>
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 pom.xml for zip and individual components

Example of pom.xml configuration for newrelic-java.zip deployment

Here is an example pom.xml for working with the zip file.

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.application</groupId>
  <artifactId>my-example-app</artifactId>
  <packaging>war</packaging>
  <version>1.0</version>
  <name>My Example Application</name>
  <url>http://example.com</url>

  <dependencies>
      <dependency>
        <groupId>com.newrelic.agent.java</groupId>
        <artifactId>newrelic-java</artifactId>
        <version>3.47.1</version>
        <scope>provided</scope>
        <type>zip</type>
      </dependency>   
  </dependencies>

  <!-- boilerplate code so Maven can generate a .war archive without requiring a web.xml file -->
  <build>
    <finalName>my-example-app</finalName>
    <plugins>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.2.2</version>
        <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
      </plugin>

      <!-- Unzip New Relic Java agent into project.build.directory -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.1.1</version>
        <executions>
          <execution>
            <id>unpack-newrelic</id>
            <phase>package</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeGroupIds>com.newrelic.agent.java</includeGroupIds>
              <includeArtifactIds>newrelic-java</includeArtifactIds>
              <overWriteReleases>false</overWriteReleases>
              <overWriteSnapshots>false</overWriteSnapshots>
              <overWriteIfNewer>true</overWriteIfNewer>
              <outputDirectory>${project.build.directory}</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
Example of pom.xml configuration for deployment of individual components

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

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.application</groupId>
  <artifactId>my-example-app</artifactId>
  <packaging>war</packaging>
  <version>1.0</version>
  <name>My Example Application</name>
  <url>http://example.com</url>

  <dependencies>

    <!-- The newrelic.jar dependency. -->
    <dependency>
      <groupId>com.newrelic.agent.java</groupId>
      <artifactId>newrelic-agent</artifactId>
      <version>3.47.1</version>
      <scope>provided</scope>
    </dependency>
    
    <!-- The newrelic-api.jar dependency. -->
    <dependency>
      <groupId>com.newrelic.agent.java</groupId>
      <artifactId>newrelic-api</artifactId>
      <version>3.47.1</version>
      <scope>compile</scope>
  </dependency>

</project>

For more help

Recommendations for learning more:

Recommendations for learning more: