Ruby agent and Heroku

Heroku is a Platform as a Service (PaaS) solution for hosting web applications in various agent languages, including Ruby. With New Relic, you can extend Heroku with metrics from New Relic APM, Browser, and Insights. This document describes special considerations for using Heroku as a hosting service with New Relic's Ruby agent.

Install the New Relic agent add-on

After deploying your Ruby app on Heroku, install the New Relic agent:

Via the Heroku website

To install the New Relic add-on through the Heroku website, you must be logged in to Heroku:

  1. From Heroku's Add-on page for New Relic, select a subscription plan.
  2. From Select an app, select your New Relic app.
  3. Give your application a descriptive name with this Heroku toolbelt command:
    heroku config:set NEW_RELIC_APP_NAME='Your Application Name'
  4. Restart your dyno.
  5. Generate some traffic to your app.
Via Heroku toolbelt

To install the New Relic add-on with the Heroku toolbelt:

  1. Run the following toolbelt command, where $planlevel is the appropriate subscription plan:
    heroku addons:create newrelic:$planlevel
  2. Give your application a descriptive name with this toolbelt command:
    heroku config:set NEW_RELIC_APP_NAME='Your Application Name'
  3. Restart your dyno.
  4. Generate some traffic to your app.
Non-Rails applications

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

 configure :production do
 require 'newrelic_rpm'

Installing 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 app server performance collected after the add-on is installed. Within a few minutes, data should start appearing in your APM Overview page.

Troubleshooting your installation

Within a few minutes of installing and configuring New Relic, data should start appearing in your app's New Relic APM Overview page. If no data appears, follow the Ruby agent troubleshooting procedures.

Upgrade from an existing New Relic installation

If New Relic is already installed, reinstall the add-on using the Heroku toolbelt command.

heroku config:set NEW_RELIC_APP_NAME='Your Application Name'

Configure the Ruby agent on Heroku

You can configure New Relic in your newrelic.yml file, or you can use environment variables to take precedence over the values in your config file. Use heroku config:set to modify the agent's settings for your Heroku appication.

For example, to set the analytics_events.max_samples_stored setting to 500:


Hostnames on Heroku

Knowing which data came from which host allows you to filter the metrics displayed in the UI to a specific host. On Heroku, hostnames within dynos are dynamically generated and not generally meaningful to you as an application developer.

Starting in version 3.9.5, the Ruby agent reports the Heroku dyno name as the hostname (for example, web.1). This allows you to view your data scoped to a particular dyno name. You can disable this behavior by setting the heroku.use_dyno_names setting to false. The agent will then use a single aggregated placeholder name called Dynamic Hostname.

Dyno hostname aggregation

Some dynos have names that are dynamically generated, and these may take on many unique values over time. Examples include scheduler dynos created by the Scheduler add-on, and run dynos created by invoking heroku run on the command line. In order to keep the number of unique hostnames reasonable, the Ruby agent will automatically aggregate data from scheduler and run dynos into hostnames called scheduler.* and run.*.

If you have other dyno types that are dynamically created, use the heroku.dyno_name_prefixes_to_shorten configuration setting to apply the same aggregation to these other dyno types.

Logging for Heroku

On Heroku, the Ruby agent logs to standard output, mixing agent logs with your normal application logs. Log entries generated by the Ruby agent include a [NewRelic] tag as a prefix.

To retrieve logs on Heroku:

  1. Verify that your NEW_RELIC_LOG environment variable is set to stdout with this Heroku toolbelt command:

    heroku config
  2. To reset the environment variable if necessary, run:

    heroku config:set NEW_RELIC_LOG="stdout"
  3. Open your newrelic.yml file in an editor.
  4. Change the log_level to debug and save the file. Be sure you do not modify the indentation.

  5. Restart your web app.
  6. Generate some traffic to your app and run it for about five minutes.
  7. Run the following Heroku toolbelt command to view logs only from the New Relic agent:

    heroku logs -n 1500 | grep -i relic
  8. If sending your log file to New Relic Support, attach the log file to your support ticket, along with newrelic.yml, your Gemfile, and Gemfile.lock.
  9. Edit newrelic.yml again, and change the log_level to the previous setting. Save the file.

For more help

Additional documentation resources include:

Recommendations for learning more: