New Relic Application Performance Monitoring (APM) is an on-demand performance management solution for web applications. New Relic APM offers seamless integration with the Heroku platform enabling immediate and automatic access to APM’s comprehensive capabilities for monitoring, troubleshooting and tuning web applications.

Standard Add-on Installation

To install the add-on, run

$ heroku addons:add newrelic:standard

Upgrading from an Existing New Relic Installation

If you already have New Relic installed, simply install the add-on as above, and you’re done.

Adding the add-on will automatically point you to the integrated Heroku/New Relic account. This means you will only see data from after you installed the add-on.

You’re welcome to keep or remove the plugin and configuration from your code repository. If you remove it, we will automatically keep you up-to-date with the latest version.

What the Add-on Does

The APM add-on will automatically creates a private account on APM, and configures access for Heroku’s servers.

Bamboo

The add-on will then install the latest New Relic plugin if you don’t already have it installed. This is the same as you running the command:

$  script/plugin install git://github.com/newrelic/rpm.git

We then autoconfigure your config/newrelic.yml file with the proper access keys.

Cedar

Ruby

The add-on will not install the plugin or create the configuration file; you need to complete these steps manually. This change allows user flexibility in customizing the New Relic settings for your application.

1. Add this gem to your Gemfile:

    gem 'newrelic_rpm'

   After adding the gem, remember to bundle install and commit your changes to Gemfile and Gemfile.lock.

2. If you are using Unicorn, follow these instructions to configure Unicorn to work with New Relic.

3. Download this file and save it at config/newrelic.yml, or copy and paste the contents from the text below. You can modify this file further if you wish to tweak your New Relic configuration.

    ---
    <%= ENV["RACK_ENV"] %>:
      error_collector:
        capture_source: true
        enabled: true
        ignore_errors: ActionController::RoutingError
      apdex_t: 0.5
      ssl: false
      monitor_mode: true
      license_key: <%= ENV["NEW_RELIC_LICENSE_KEY"] %>
      developer_mode: false
      app_name: <%= ENV["NEW_RELIC_APP_NAME"] %>
      transaction_tracer:
        record_sql: obfuscated
        enabled: true
        stack_trace_threshold: 0.5
        transaction_threshold: apdex_f
      capture_params: false
      log_level: info

Using New Relic from a Rack App

When using New Relic with a non-Rails app, you need to manually install the plugin into your code repo. 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'
end

Next, specify your application environment:

heroku config:add RACK_ENV=production

Finally check it all in and push it up to heroku:

$ git commit -m "Added New Relic Plugin"
$ git push heroku master

See the source to our docs app for an example of a Sinatra app using New Relic.

Java

Download and Unzip New Relic

You can find the zip file here. It contains the New Relic agent jar, default config file, and API jar.

Unzip it into the root of your project. This will create a directory called “newrelic” in your application and add the necessary files into it.

Push these changes to your application before continuing:

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

Enable the Java Agent

Add the following flag to your JAVA_OPTS config var on Heroku: -javaagent:newrelic/newrelic.jar

You can get the current value of your config var with:

::: term
$ heroku config
...
JAVA_OPTS             => -Xmx384m -Xss512k -XX:+UseCompressedOops
...

Copy the value and then add the java agent flag to it:

$ heroku config:add JAVA_OPTS='-Xmx384m -Xss512k -XX:+UseCompressedOops -javaagent:newrelic/newrelic.jar'
Adding config vars:
  JAVA_OPTS => -Xmx384m -Xss512...lic/newrelic.jar

Customizing the Configuration

New Relic allows you customize certain settings by editing your configuration file. Since Heroku automatically writes this out, you can’t directly edit the file. By setting certain configuration variables, you can change how the configuration file is generated.

Currently we support setting a custom apdex score, enabling parameter capture, and customizing the error collector.

$ heroku config:add NEW_RELIC_APDEX=0.4
$ heroku config:add NEW_RELIC_CAPTURE_PARAMS=TRUE
$ heroku config:add NEW_RELIC_ERROR_COLLECTOR_ENABLED=false
$ heroku config:add NEW_RELIC_ERROR_COLLECTOR_CAPTURE_SOURCE=false
$ heroku config:add NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERRORS=ActionController::RoutingError

Supported Languages and Frameworks

APM is available for Ruby, Java, and Python apps. If you’re using Ruby it will work with any Rack app, including Rails & Sinatra