Heroku: Install the New Relic add-on

Heroku is a Platform as a Service (PaaS) solution for hosting web applications in various agent languages. With New Relic, you can extend Heroku with metrics from New Relic APM, Browser, and Insights. The New Relic add-on supports Java, Node.js, PHP, Python, and Ruby.

Install the New Relic add-on

To set up the New Relic add-on, see Heroku's documentation, including available plan levels and Toolbelt procedures. If you have problems, use the Heroku support channels.

Configure the agent

After you install the New Relic add-on for Heroku, follow the configuration procedures for your New Relic APM agent.


The minimum agent version for Java is 3.17.1 or higher. To install and configure New Relic's Java agent for your add-on, see New Relic's Java agent and Heroku documentation.


To install and configure New Relic's Node.js agent for your add-on, see:

  • New Relic's Node.js and Heroku documentation
  • Blog post (2013) with a "real world" example of installing the New Relic Node.js agent for a Heroku app

To install and configure New Relic's PHP agent for your add-on, see New Relic's PHP agent and Heroku documentation.


To install and configure New Relic's Python agent for your add-on, see New Relic's Python agent and Heroku documentation.


To install and configure New Relic's Ruby agent for your add-on, see New Relic's Ruby agent and Heroku documentation.

If you are using New Relic's Ruby agent with a non-Rails application, Heroku users need to install the plugin in your repository manually. For example, in a Sinatra app, add the newrelic gem to your Gemfile, and then add the following code to your app:

 configure :production do
 require 'newrelic_rpm'

Manage your Heroku add-on accounts

Every time you install the New Relic add-on for Heroku, New Relic will automatically create a new account, complete with a unique license key, account URL, and account ID. These three types of information are important for managing each of your Heroku add-on accounts.

License key

The license key identifies the account where your application reports. To check the license key your app is using:

  1. From a command line, run:

    heroku config | grep -i relic
  2. Look for the value of NEW_RELIC_LICENSE_KEY.

This license key environment variable will override any other license key that you hard-code into your New Relic config file.

Account URL

If you install the New Relic add-on multiple times and need to verify the URL your Heroku app uses for reporting to New Relic, look in your agent logs for a line indicating reporting to following by a URL using this format:

Account ID

You cannot change your add-on's account ID directly. If you need to change the New Relic account your Heroku app uses for reporting to New Relic, change the current license key environment variable in its config file so that it points to the license key of the New Relic account you want to use:

heroku config:set NEW_RELIC_LICENSE_KEY=changed_account_license_key

Log on to New Relic

Heroku customers may have two different types of accounts with New Relic:

  • Add-on accounts: New Relic accounts that customers installed on their Heroku application by using Heroku's New Relic add-on
  • "Regular" accounts: Other New Relic accounts that customers did not install by using Heroku's add-on

Add-on accounts provide extra features through New Relic's partnership with Heroku. They are installed and managed differently than regular New Relic accounts created without the add-on. Different procedures apply, depending on which type of account you want to sign into.

This add-on does not include a Browser Pro subscription, which is required to use the Pro or Pro+SPA agents. These features will require a separate subscription.

In accordance with the terms of New Relic's partnership with Heroku, customers who install New Relic via the Heroku add-on can only access their New Relic add-on accounts by signing in through Heroku. For this reason, if you have both add-on accounts and regular New Relic accounts, you cannot switch directly between them.

Sign in to New Relic add-on account through Heroku

To sign in to your New Relic add-on accounts:

  1. Sign in through Heroku's login page at https://id.heroku.com/login.
  2. Select the application that has the New Relic add-on installed.
  3. Select New Relic from your list of add-ons.

If you sign in through Heroku, you will not see any of your regular New Relic accounts when you select (account dropdown) > Switch account.

Sign in to regular New Relic accounts

To sign into or switch between your regular New Relic accounts:

  1. Sign in to New Relic's login page at https://rpm.newrelic.com/login.
  2. To switch from one regular New Relic account to another: Go to rpm.newrelic.com > (account dropdown) > Switch account > (select an account).

If you sign in directly through New Relic, you will not see any of your New Relic add-on accounts from Heroku when you select (account dropdown) > Switch account.

Set up deployment notifications

The Heroku add-on automatically sends deployment notifications to New Relic for one application per account. If you add multiple applications to your add-on account, you must use the New Relic REST API to manually send deployment notifications for your additional applications.

You cannot use a post-deploy hook, because the New Relic REST API call requires a header, and Heroku's post-deploy hook does not allow headers. However, you can write a script that generates this API call whenever you deploy on Heroku. For instructions on recording deployments via the REST API, see Recording deployments.

View Instances page in New Relic APM

New Relic APM's Instances page provides further insight into your monitored processes on Heroku. Use this page to monitor your app's average memory usage per instance, the number of instances running, and the number of instance restarts over the selected time frame.

An instance is a process monitored by New Relic. The number of instances running does not always equal the number of dynos, as many dynos will run multiple processes. The agent reports the number of instances as an average once each minute, which can sometimes result in fractional values.

Instance metrics are available only to New Relic accounts created through Heroku's New Relic add-on. If your New Relic account is not associated with Heroku add-ons, your apps will not receive instance metrics, even if your New Relic account monitors apps running on Heroku.

To view the Instances page: Go to rpm.newrelic.com/apm > (select a Heroku app) > Monitoring > Instances. The Instances page for Heroku add-on apps shows the number of processes currently monitored by New Relic. Use the Instances running chart to optimize your instances.

  • The Average memory usage per instance chart measures average memory usage across all your instances over the selected time frame.
  • The Load calculation records the count of agents reporting and the percentage of wallclock time spent handling requests as an average of the reporting agents. For a short period of time after a dyno restarts, both the old and new dynos are running. This can temporarily distort the Load metric until the old dyno shuts down.
  • The Instance restarts chart measures the number of your instances that were restarted during the selected time frame.

For questions related to how New Relic is recording and reporting your data, get support at support.newrelic.com.

For more help

Recommendations for learning more: