Maven installation for Java

There are two methods for using New Relic through Maven:

  • Download and unzip the newrelic-java.zip file containing all Java agent components.
  • Download individual Java agent components.

For more information on working with the Java agent, see the manual Java agent installation directions.

Method 1: Download and unzip all Java agent components

This section explains how to configure Maven to download and unzip the newrelic-java.zip file containing all 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
1: Configure pom.xml to add the newrelic-java.zip dependency

To pull down the Java agent zip file, add the following to your pom.xml in the <dependencies> section. Replace JavaAgentVersion with the version of the Java agent that you wish to use (i.e. 3.x.x).

<!-- https://mvnrepository.com/artifact/com.newrelic.agent.java/newrelic-java -->
<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. Replace JavaAgentVersion with the version of the Java agent that you specified to download in the previous step. 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.0.0</version>
  <executions>
    <execution>
      <id>unpack-zip</id>
      <phase>prepare-package</phase>
      <goals>
        <goal>unpack-dependencies</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>com.newrelic.agent.java</groupId>
            <artifactId>newrelic-java</artifactId>
            <version>JavaAgentVersion</version>
            <type>zip</type>
            <overWrite>true</overWrite>
            <outputDirectory>${project.build.directory}</outputDirectory>
            <destFileName>newrelic</destFileName>
          </artifactItem>
        </artifactItems>
        <outputDirectory>${project.build.directory}</outputDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>
3. Configure the agent

After downloading and unpacking the Java agent files you will still need to configure the newrelic.yml file (or JVM system properties) with your license_key and app_name as well as pass -javaagent:/path/to/newrelic.jar to the JVM running your application server. See Install the Java agent.

If you use the New Relic Java agent API, you need to make the API jar available at compile time by adding it to your application class path.

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

To pull down the newrelic.jar, add this to your maven pom.xml. Replace JavaAgentVersion with your 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

To pull down the newrelic-api.jar, add this to your maven pom.xml. Replace JavaAgentVersion with your 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 still need to configure the newrelic.yml file (or JVM system properties) with your license_key and app_name as well as pass -javaagent:/path/to/newrelic.jar to the JVM running your application server. See Install the Java agent.

If you use the New Relic Java agent API, you need to make the API jar available at compile time by adding it to your application class path.

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>
      
      <!-- https://mvnrepository.com/artifact/com.newrelic.agent.java/newrelic-java -->
      <dependency>
        <groupId>com.newrelic.agent.java</groupId>
        <artifactId>newrelic-java</artifactId>
        <version>3.38.0</version>
        <scope>provided</scope>
        <type>zip</type>
      </dependency>   

    </dependencies>
  </dependencies>

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

      <!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-war-plugin -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.1.0</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.0.0</version>
        <executions>
          <execution>
            <id>unpack-zip</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>com.newrelic.agent.java</groupId>
                  <artifactId>newrelic-java</artifactId>
                  <version>3.38.0</version>
                  <type>zip</type>
                  <overWrite>true</overWrite>
                  <outputDirectory>${project.build.directory}</outputDirectory>
                  <destFileName>newrelic</destFileName>
                </artifactItem>
              </artifactItems>
              <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.38.0</version>
      <scope>provided</scope>
    </dependency>
    
    <!-- The newrelic-api.jar dependency. -->
    <dependency>
      <groupId>com.newrelic.agent.java</groupId>
      <artifactId>newrelic-api</artifactId>
      <version>3.38.0</version>
      <scope>compile</scope>
  </dependency>

</project>

For more help

Additional documentation resources include:

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.