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 using APM and browser monitoring metrics. This page describes special considerations for using Heroku as a hosting service with the Ruby agent for New Relic.

Install the New Relic agent add-on

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

configure :production do
 require 'newrelic_rpm'
 end

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 summary page.

Troubleshooting your installation

Within a few minutes of installing and configuring New Relic, data should start appearing in your app's APM summary 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 application.

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

$
heroku config:set NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_SAMPLES_STORED=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:

   bash

   Copy

   $
   heroku config

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

   bash

   Copy

   $
   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:

   bash

   Copy

   $
   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.