Java agent and Heroku

Heroku is a Platform as a Service (PaaS) solution for hosting web applications in various agent languages, including Java. With New Relic, you can extend Heroku with metrics from New Relic APM, Browser, and Insights.

Contents

Requirements

Before you install New Relic on your Java app, ensure your app meets these requirements:

• You have deployed your Java app to Heroku, following the Heroku instructions at least through the Deploy the app step.
• You have installed Java 8.
• You have installed Maven 3 or higher.
• You have New Relic Java agent version 3.17.0 or higher.

Then, enable the add-on and configure your Heroku environment for New Relic.

Enable the New Relic agent add-on

After completing the requirements, enable the New Relic add-on:

1. Log in to your Heroku account.
2. From the New Relic APM Add-On Page, select a subscription plan.
3. Select Install New Relic APM, then select your target app from the dropdown.
4. Continue with the procedures to configure your Heroku environment for New Relic.

Installing the add-on automatically creates a New Relic account and configures access for Heroku servers.

Configure your Heroku environment for New Relic

After you complete the requirements and enable the New Relic add-on, configure your Heroku environment for New Relic:

1. Edit your Procfile, located in your app's root folder, to point to the agent jar. Replace the contents of the file:

   web: java -javaagent:/app/newrelic/newrelic.jar -cp target/classes:target/dependency/* Main

   OR

   Provide the path to newrelic.jar with the JAVA_OPTS environment variable.

2. Customize your app's configuration as appropriate for your platform.

   Maven configuration

   For Maven, follow these steps to customize your app's configuration.

   1. Give your app a meaningful name with this Heroku toolbelt command:

      heroku config:set NEW_RELIC_APP_NAME="APP_NAME"

   2. In your pom.xml, add the newrelic-agent dependency, substituting X.Y.Z with the latest Java agent version. Recommended: To ensure proper formatting is applied and contents do not contain sensitive information, format the syntax using http://codebeautify.org/xmlviewer.

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

   3. In the <build> element of pom.xml, customize the build so it downloads the agent, substituting X.Y.Z with the latest agent version:

      <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-dependency-plugin</artifactId>
         <version>2.6</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>X.Y.Z</version>
                   <type>zip</type>
                   <overWrite>true</overWrite>
                   <outputDirectory>target</outputDirectory>
                   <destFileName>newrelic</destFileName>
                 </artifactItem>
               </artifactItems>
               <outputDirectory>./</outputDirectory>
             </configuration>
          </execution>
         </executions>
      </plugin>

   4. After adding the New Relic dependencies to the Procfile and pom.xml, perform the following command:

      $ mvn clean install

   Manual configuration

   If you are not using Maven, follow these steps to customize your app's configuration.

   1. Log in to dashboard.heroku.com. Select your app, then select Add-ons > New Relic APM.
   2. From the New Relic UI's account dropdown, select Account settings.
   3. In the Update your New Relic agent section, download the Java SE 8 release.
   4. Unzip the file you downloaded into your app root.
   5. Edit newrelic.yml, and customize the app_name setting with a descriptive app name.

   6. Add the newrelic directory and files to your project with this command:

      git add .

   7. Enable the agent by adding -javaagent:newrelic/newrelic.jar to JAVA_OPTS.

   8. Push the changes to your app:

      git commit -m 'add newrelic'
      git push heroku master

3. Push the changes to the dyno with this Heroku toolbelt command:

   git add .
   git commit -m 'Edited Procfile and pom.xml'  
   git push heroku master

4. Open your app in your browser with this Heroku toolbelt command:

   heroku open

5. Generate some traffic to your app.
6. Wait a few minutes, then check your app's performance: In Heroku, select your app, then select the New Relic add-on.

If no data appears or if you have problems, follow the troubleshooting tips.

Troubleshoot your installation

Here are some tips to troubleshoot your Heroku add-on installation with the New Relic Java app:

• If you don't see the New Relic add-on after you generate traffic: In Heroku, select Find More Add Ons, and add the New Relic APM add-on.
• If no data appears after waiting a few minutes, follow the troubleshooting procedures for Heroku (Java).

For more help

Additional documentation resources include:

• Heroku and New Relic (additional topics for Heroku users)
• Heroku Dev Center (information on the Heroku site on installing New Relic)