---
title: Java agent and Heroku
source: https://docs.newrelic.com/docs/apm/agents/java-agent/heroku/java-agent-heroku
---

[Heroku](https://devcenter.heroku.com/articles/newrelic) 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 [APM](https://docs.newrelic.com/docs/apm/new-relic-apm) or [browser monitoring](https://docs.newrelic.com/docs/browser/new-relic-browser).

> #### 💡 TIP
>
> If you use Scala, see [Java agent Scala procedures for Heroku](https://docs.newrelic.com/docs/agents/java-agent/heroku/java-agent-scala-heroku).

## Compatibility and requirements [#requirements]

-   Java 7 or higher
-   [Maven 3](http://maven.apache.org/download.cgi) or higher (if you are using Maven)
-   Latest New Relic [Java agent version](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes)

## 1. Enable the New Relic agent add-on in Heroku [#enable]

After you ensure that you [meet the requirements](#requirements), enable the New Relic agent add-on in Heroku.

> #### ⚠️ CAUTION
>
> You must [deploy your Java app to Heroku](https://devcenter.heroku.com/articles/getting-started-with-java#introduction), following the Heroku instructions at least through the [Deploy the app](https://devcenter.heroku.com/articles/getting-started-with-java#deploy-the-app) step, before you can enable the New Relic agent add-on.

1.  Log in to your Heroku account.
2.  From the [APM Add-On Page](https://elements.heroku.com/addons/newrelic#pricing), select a subscription plan.
3.  Select **Install APM**, and then select your target app from the dropdown.

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

## 2. Provide the path to the jar file [#provide-path]

After you [enable the New Relic agent add-on](#enable), pass the `javaagent` flag to the `java` process and provide the path to the jar file by editing your `Procfile`.

**Deploy to Heroku**

If you deploy to Heroku, the location of the jar file for both Maven and manual configuration is in the app's root folder in a directory called `newrelic`.

Example:

````
web: java -javaagent:/app/newrelic/newrelic.jar -jar target/HELLOWORLD.jar
```

````

**Deploy locally**

If you deploy locally, your jar file might be in a different directory. If it is, replace `PATH/TO/NEWRELIC.JAR` with the path to the jar file in your local directory.

Example:

````
web: java -javaagent:PATH/TO/NEWRELIC.JAR -jar target/HELLOWORLD.jar
```

````

## 3. Configure your Heroku environment for New Relic [#configure-heroku-environment]

After you [provide the path to the jar file](#provide-path), configure your Heroku environment for New Relic, depending on your platform:

**Maven configuration**

1.  Give your app a [meaningful name](https://docs.newrelic.com/docs/agents/manage-apm-agents/app-naming/name-your-application) with this Heroku toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_APP_NAME="APP_NAME"
    ```
2.  Add your license key:

    ```bash
    heroku config:set NEW_RELIC_LICENSE_KEY="LICENSE_KEY"
    ```
3.  In your `pom.xml`, add the `newrelic-agent` dependency, substituting `X.Y.Z` with the [latest Java agent version](https://docs.newrelic.com/docs/agents/java-agent/getting-started/java-release-notes). Recommended: To ensure proper formatting is applied and contents do not contain sensitive information, format the syntax using <http://codebeautify.org/xmlviewer>.

    ```xml
    <dependency> 

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

    </dependency>
    ```
4.  In the `<build>` element of `pom.xml`, customize the build so it downloads the agent:

    ```xml
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.0.2</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.basedir}</outputDirectory>
                  <destFileName>newrelic</destFileName>
              </configuration>
            </execution>
        </executions>
    </plugin>
    ```

**Manual configuration**

1.  Log in to [dashboard.heroku.com](https://dashboard.heroku.com).
2.  Select your app.
3.  Select **Add-ons > APM**.
4.  [Get the New Relic Java agent.](https://docs.newrelic.com/docs/agents/java-agent/installation/install-java-agent/#download-agent)
5.  Unzip the file into your app root.
6.  Edit `newrelic.yml` to customize the [`app_name`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-app_name) setting with a [descriptive app name](https://docs.newrelic.com/docs/agents/manage-apm-agents/app-naming/name-your-application).
7.  Also in `newrelic.yml`, add your [license key](https://docs.newrelic.com/docs/accounts/install-new-relic/account-setup/license-key) to the [`license_key`](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-license_key) setting.

## 4. Push your changes and open the app [#push-changes]

After you [configure your Heroku environment for New Relic](#configure-heroku-environment), push your changes and open the app to monitor it with New Relic.

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

    ```bash
    git add .
    git commit -m 'YOUR COMMIT MESSAGE'
    git push heroku master
    ```
2.  Open your app in your browser with this Heroku toolbelt command:

    ```bash
    heroku open
    ```
3.  Generate some traffic to your app and wait a few minutes.
4.  Check your app's performance in Heroku by selecting your app and then selecting the New Relic add-on.

If no data appears or if you have problems, follow the [troubleshooting](#troubleshooting) tips.

## Troubleshoot [#troubleshooting]

Here are some tips to help you troubleshoot:

-   If you don't see the New Relic add-on after you generate traffic, go to Heroku, select **Find More Add Ons**, and add the APM add-on.
-   If no data appears after waiting a few minutes, follow the [troubleshooting procedures for Heroku (Java)](https://docs.newrelic.com/docs/agents/java-agent/heroku/no-data-appears-heroku-java).