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 our monitoring solutions, like APM and browser monitoring. 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 our Java agent and Heroku documentation.


To install and configure our 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 our Node.js agent for a Heroku app

To install and configure our PHP agent for your add-on, see our PHP agent and Heroku documentation.


To install and configure our Python agent for your add-on, see our Python agent and Heroku documentation.


To install and configure our Ruby agent for your add-on, see our Ruby agent and Heroku documentation.

If you are using our 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 with Heroku's add-on

Regular accounts provide a wider range of features than do add-on accounts, and are installed and managed differently. Different procedures apply, depending on which type of account you want to sign into.

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 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 newrelic.com/login.
  2. To switch from one regular New Relic account to another: Go to: account dropdown > Switch account, and 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.

For more help

If you need more help, check out these support and learning resources: