New Relic APM

This add-on is operated by New Relic

Monitor, troubleshoot, and tune production web applications.

New Relic APM

Last Updated: 07 May 2015

debugging java monitoring new relic performance

Table of Contents

New Relic for Web Apps is an add-on for on-demand web application performance management. New Relic offers seamless integration with the Heroku platform, enabling immediate and automatic access to New Relic’s comprehensive capabilities for monitoring, troubleshooting and tuning web applications.

Adding the New Relic add-on for Web Apps to an application provides insight into:

  • Customer satisfaction, via real-time end user experience monitoring
  • Health and availability of your entire application, via application monitoring
  • Web server resource data for Windows and Linux, via server monitoring

Supported languages and frameworks

The New Relic add-on is available for:

If you’re using Ruby, the add-on will work with any Rack app, including Rails and Sinatra.

Add-on installation

To install the add-on, run the following command with the appropriate plan level:

$ heroku addons:create newrelic:stark

The example uses Stark. The other plan levels are: Wayne, Hawke, Drake, Murdock, Parker, West, Kent, Banner, and Marko. For details, see the New Relic add-on plans page.

Installing the add-on will automatically point you to the integrated Heroku/New Relic account. The add-on automatically creates a private New Relic account, and configures access for Heroku servers. New Relic will begin monitoring application performance, end user experience, and server performance collected after the add-on is installed.

Upgrading from an existing New Relic installation

If New Relic for Web Apps is already installed, simply install the add-on using the steps above to upgrade.

Java installation and configuration

Non-Maven Java apps
Download the latest Java agent .zip and unzip it into the root of your project.
This will create a directory called newrelic with the necessary files. Add it to your project with $ git add newrelic.
Enable it by adding -javaagent:newrelic/newrelic.jar to your JAVA_OPTS.

Add the New Relic agent as a Maven dependency

If your Java application is using Maven, you can add New Relic as a managed dependency. In your pom.xml, add the newrelic-agent dependency as shown below but replace X.X.X with the latest version. You can find the latest Java agent version here.


Customize the build section so it always names the newrelic-agent.jar consistently.


Create a New Relic configuration file

Create a newrelic.yml file next to your pom.xml. Use the template as a starting point. This should be checked into your repo. If you want to put it elsewhere, the location can be changed with a System Property or the NEWRELIC_HOME environment variable.

$ git add newrelic.yml

Push these changes to your application:

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


Adding the New Relic Add-on will set the following config vars on your app:


These will override corresponding values from newrelic.yml.

Enable the Java agent

Add the following flag to your JAVA_OPTS config var on Heroku:


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

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

Copy the value, add the Java agent flag and app name :

Make sure to enter your own app name in this example.

$ heroku config:set JAVA_OPTS='-Xmx384m -Xss512k -XX:+UseCompressedOops -javaagent:target/dependency/newrelic-agent.jar' NEW_RELIC_APP_NAME="YOUR APP NAME GOES HERE"
Adding config vars:
    JAVA_OPTS => -Xmx384m -Xss512.../newrelic-agent.jar

Add the New Relic agent as a Scala+SBT/Play 2 dependency

To use the New Relic API class or annotations:

  1. Make sure the newrelic.yml file is at the root level of your project.

  2. Add the New Relic agent as a Scala/Play dependency

    Add this line (replacing x.x with the correct version) to the appDependencies method in your application’s project/Build.scala file:

    "" % "newrelic-agent" % "2.x.x"

    This also includes the API, so the newrelic-api dependency is optional.

  3. Make sure JAVA_OPTS is specified on execute line of the Procfile.

  4. Push your changes to Heroku.

  5. Update your JAVA_OPTS config.

    When setting the Java agent flag, you will need specify the version number. Your heroku config command should look similar to this:

    $ heroku config:set JAVA_OPTS="-XX:MaxPermSize=128m -Xmx334m -Xss512k -XX:+UseCompressedOops -Dnewrelic.bootstrap_classpath=true -javaagent:target/staged/newrelic-agent-2.X.X.jar"

As above, you can get the current value of your config var by running heroku config with no arguments.

Node.js installation and configuration

This describes special considerations for using Heroku as a hosting service with New Relic’s Node.js agent.

Installing the Node.js agent

To ensure that the newrelic package is properly included in your package.json file when you push to Heroku, you should install the package on your local system using the following command:

  npm install newrelic --save

For more information, see installing Node.js on Heroku.

Configuring the Node.js agent

All of the configuration variables in newrelic.js have counterparts that can be set as environment variables. You can freely mix and match variables in the configuration file.

Note: Environment variables override your configuration file’s variables. For more information, see Configuring Node.js with environment variables.

Here is an example of using the command line to set environment variables.

  $ heroku config:set NEW_RELIC_LICENSE_KEY=<your license key>
  $ heroku config:set NEW_RELIC_APP_NAME=<your production app name>
  $ heroku config:set NEW_RELIC_APDEX=<0.010>

To confirm your settings from the command line:

  $ heroku config

PHP installation and configuration

You can install the New Relic PHP add-on for Heroku via the Heroku Add-ons Directory or via Heroku toolbelt:

heroku addons:create newrelic:$planlevel

Your application name defaults to PHP Application on Heroku. To change this name, set the following Heroku environment variable:

heroku config:set NEW_RELIC_APP_NAME='Your Application Name'

To further customize your installation:

  1. Download newrelic.ini_.heroku
  2. Rename the file from newrelic.ini_.heroku to newrelic.ini.
  3. Deploy the configuration file to your app’s root folder, commit the changes, and push your changes to Heroku.
  4. Tell Heroku to use your customized config file with this toolbelt command:

    heroku config:set NEW_RELIC_CONFIG_FILE=newrelic.ini

For more information about configuring New Relic on Heroku, see PHP agent and Heroku and PHP agent settings.

Python installation and configuration

To install the Python package for the New Relic agent, create or edit the requirements.txt file, adding the line newrelic.

Deploying your app will now install the New Relic agent.


Modify the web entry in your Procfile to start with newrelic-admin run-program. The following example runs Django with a run_gunicorn management command:

web: newrelic-admin run-program python hellodjango/ run_gunicorn -b "$PORT" -w 3

See the New Relic full Python installation instructions for more detail, or the New Relic Python troubleshooting tips for further information.

Updating the Python agent

Heroku will cache packages and will not detect when a newer version of the Python agent is available. To force an upgrade to a newer version, explicitly list the version against the package name in the ‘requirements.txt’ file and push your application. Use this syntax: newrelic==A.B.C.D

Replace A.B.C.D with the version of the New Relic Python agent. When you change the version string to a newer version pip will perform the update.

Overriding the application name

Previously, Heroku would set NEW_RELIC_APP_NAME when the New Relic add-on was setup to be the unique application name Heroku created for your site. This is no longer done for new deployments.

Application data from the Python agent will be reported to New Relic against the application name ‘Python Application’. The display name for this can be changed in the New Relic UI, however, it is recommended that it be changed to a unique unchanging value from the agent side.

Doing this is a requirement if you intend running multiple distinct sites under the one Heroku account and wish to have the data reported separately.

The application name can be overriden by using the Heroku toolbelt command:

$ heroku config:set NEW_RELIC_APP_NAME='Web Site (Production)'

Once done, you can verify that the configuartion has been updated by running the following, which will report the value assigned to NEW_RELIC_APP_NAME.

$ heroku run env | grep NEW_RELIC

Ruby installation and configuration

To start seeing data from your application after installing the New Relic add-on you need to install and configure the Ruby agent gem.

  1. Add the Ruby agent gem to your Gemfile, bundle and commit your changes.
  2. Copy newrelic.yml to config/newrelic.yml.
  3. Set your application name using a heroku environment variable.

1. Add the New Relic gem to your Gemfile:
Add this line to your Gemfile

gem 'newrelic_rpm'

Make sure this line is outside any groups in your Gemfile (e.g. development or test). After adding the gem, bundle install and commit your changes to Gemfile and Gemfile.lock.

If you are using Unicorn you will need the preload_app true directive in your unicorn.rb.

When starting Unicorn you must manually specify the path to your configuration file in order for it to take effect. To do this, pass the -c <path> option to the unicorn invocation you use to start your server. This will be in your Procfile.

2. Copy newrelic.yml into your application
Download newrelic.yml and save it at config/newrelic.yml, or run this curl command from the root of your application.

$ curl > config/newrelic.yml

3. Set your application name
Set the name of your application as it will appear on the New Relic dashboard.


Using New Relic from a Rack app

If you are using New Relic with a standard Rails app, you do not need to follow the steps in this section.

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, then add the following code to your app:

configure :production do
  require 'newrelic_rpm'

Next, specify your application environment:

$ heroku config:set RACK_ENV=production

Finally, commit and push to Heroku:

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

Bamboo configuration

We do not install the New Relic plugin if we detect “newrelic_rpm” gem in your Gemfile.

Heroku will automatically configure your Ruby app with the latest New Relic plugin on your next git push. This is the same as running:

$  script/plugin install git://

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

Customizing the Bamboo configuration

New Relic allows you customize certain settings by editing your configuration file. Heroku automatically writes this out, so 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:set NEW_RELIC_APDEX=0.4
$ heroku config:set NEW_RELIC_ERROR_COLLECTOR_ENABLED=false
$ heroku config:set NEW_RELIC_ERROR_COLLECTOR_IGNORE_ERRORS=ActionController::RoutingError

View your performance data

You must enter New Relic through Heroku interface, otherwise it will not report correctly.

Click on the New Relic icon in your list of Add-ons. You will be redirected via SSO to your account on the New Relic site.

  1. From your dashboard, select the app for which you have installed the New Relic add-on.
  2. Select New Relic from your list of add-ons.
  3. See the New Relic documentation site for more information on working with New Relic.

Interpreting New Relic request queuing

For Ruby and Python apps, the New Relic dashboard shows an app server response time component labeled “Request Queuing”. “Request Queuing” is the time elapsed from a router receiving a request to a Rails controller action or Python app code initiating processing of the request. During this time, the request goes through the following stages:

  1. Processing in the router
  2. Traveling over the network to a dyno
  3. Queuing in the TCP socket backlog on the dyno
  4. Processing by the web server (eg. Unicorn, Gunicorn, mod_wsgi)
  5. Processing by Rack middleware configured for the app

All of the above count towards “Request Queuing” when New Relic displays where time was spent processing a request. Time spent in Django middleware is not included in the request queue time but is captured as ‘Python Time’ in the overview graph. For more details on how to interpret the request queuing metric, check out the New Relic Request Queuing documentation.