Install Java agent using Maven

This document explains how to install the Java agent using Maven. For information on manually installing the Java agent, see Install the Java agent and Java agent configuration: Config file.

Install agent package using Maven

1. Install the New Relic Java agent, using either of these options:

   Install complete 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.

   • newrelic.yml (agent configuration file)

   • newrelic.jar (Java agent jar)

   • newrelic-api.jar (Java agent API jar)

   • README

     To do this:

   1. Configure your pom.xml to download newrelic-java.zip. For example:

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

      Copy

      Replace JAVA_AGENT_VERSION with the latest Java agent version.

   2. Unzip newrelic-java.zip by configuring maven-dependency-plugin in your pom.xml. For example:

      <!-- 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>

      Copy

      This will unzip all the files into the newly created newrelic/ within project.build.directory:

      Zip example

      Here is an example pom.xml that downloads and extracts newrelic-java.zip.

      <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>JAVA_AGENT_VERSION</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>

      Copy

   Install individual 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 your pom.xml to download either newrelic.jar or newrelic-api.jar. Here's an example for downloading newrelic.jar:

      <dependency>
        <groupId>com.newrelic.agent.java</groupId>
        <artifactId>newrelic-agent</artifactId>
        <version>JAVA_AGENT_VERSION</version>
        <scope>provided</scope>
      </dependency>

      Copy

      Here's an example for downloading newrelic-api.jar:

      <dependency>
        <groupId>com.newrelic.agent.java</groupId>
        <artifactId>newrelic-api</artifactId>
        <version>JAVA_AGENT_VERSION</version>
        <scope>compile</scope>
      </dependency>

      Copy

      Replace JAVA_AGENT_VERSION with the latest Java agent version.

   2. Locate the newrelic.yml file you received when creating your New Relic account, or download one for the version of the agent that you are using.

      Individual components example

      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>

      Copy

2. Place newrelic.yml in the same folder as newrelic.jar, unless you specify otherwise in the JVM arg -Dnewrelic.config.file.

3. Configure the newrelic.yml file (or JVM system properties) with your license_key and app_name.

4. Pass -javaagent:/path/to/newrelic.jar to the JVM running your application server.

5. Optional: If using the New Relic Java agent API, make the API jar available at compile time by adding it to your application class path.

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