This add-on is operated by New Relic
Monitor, troubleshoot, and tune production web applications.
New Relic APM
Last updated 02 September 2015
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.
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
The minimum New Relic agent version for Java is 3.17.0 or higher.
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
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.
<dependency> <groupId>com.newrelic.agent.java</groupId> <artifactId>newrelic-agent</artifactId> <version>X.X.X</version> <scope>provided</scope> </dependency>
Customize the build section so it always names the
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-dependency-plugin</artifactId> <version>2.6</version> <executions> <execution> <id>copy-new-relic</id> <phase>package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <includeGroupIds>com.newrelic.agent.java</includeGroupIds> <includeArtifactIds>newrelic-agent</includeArtifactIds> <stripVersion>true</stripVersion> </configuration> </execution> </executions> </plugin> </plugins> </build>
Create a New Relic configuration file
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
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:
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:
Make sure the newrelic.yml file is at the root level of your project.
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 (or for more information, see New Relic’s Scala installation for Java documentation and Play installation for Java documentation as appropriate):
"com.newrelic.agent.java" % "newrelic-api" % 3.x.x"
Add the following line to your application’s project/build.sbt file:
libraryDependencies ++=Seq("com.newrelic.agent.java" % "newrelic-agent" % "3.x.x")
Make sure JAVA_OPTS is specified on execute line of the Procfile.
Push your changes to Heroku.
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.
Tip: If you have problems with your $JAVA_OPTS file, try adding the following options to the web entry in your procfile:
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. If you use environment variables, you still need newrelic.js in your root directory, or new relic will fail hard.
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:
- Download newrelic.ini_.heroku
- Rename the file from newrelic.ini_.heroku to newrelic.ini.
- Deploy the configuration file to your app’s root folder, commit the changes, and push your changes to Heroku.
Tell Heroku to use your customized config file with this toolbelt command:
heroku config:set NEW_RELIC_CONFIG_FILE=newrelic.ini
Python installation and configuration
To install the Python package for the New Relic agent, create or edit the
requirements.txt file, adding the line
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/manage.py run_gunicorn -b "0.0.0.0:$PORT" -w 3
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:
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
$ 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.
- Add the Ruby agent gem to your Gemfile, bundle and commit your changes.
- Copy newrelic.yml to config/newrelic.yml.
- Set your application name using a heroku environment variable.
1. Add the New Relic gem to your Gemfile:
Add this line to your Gemfile
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.
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
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 https://gist.githubusercontent.com/rwdaigle/2253296/raw/newrelic.yml > config/newrelic.yml
3. Set your application name
Set the name of your application as it will appear on the New Relic dashboard.
$ heroku config:set NEW_RELIC_APP_NAME="YOUR APP NAME GOES HERE"
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' end
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
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.