---
title: Ruby agent and Heroku
source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/installation/ruby-agent-heroku
---

[Heroku](https://devcenter.heroku.com/articles/newrelic) 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](https://docs.newrelic.com/docs/apm/new-relic-apm) and [browser monitoring](https://docs.newrelic.com/docs/browser/new-relic-browser) 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 [#installing]

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](https://elements.heroku.com/addons/newrelic#pricing), select a subscription plan.
2.  From **Select an app**, select your New Relic app.
3.  Give your application a [descriptive name](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/name-your-application) with this Heroku toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_APP_NAME='Your Application Name'
    ```
4.  Add the New Relic gem to your `Gemfile`. The New Relic Ruby agent's gem is available from [rubygems.org](https://rubygems.org/) as `newrelic_rpm`.

    If your app uses Bundler, add this gem to the Gemfile:

    ```ruby
    gem 'newrelic_rpm'
    ```
5.  Restart your dyno.
6.  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](https://elements.heroku.com/addons/newrelic#pricing):

    ```bash
    heroku addons:create newrelic:$planlevel
    ```
2.  Give your application a [descriptive name](https://docs.newrelic.com/docs/apm/new-relic-apm/installation-configuration/name-your-application) with this toolbelt command:

    ```bash
    heroku config:set NEW_RELIC_APP_NAME='Your Application Name'
    ```
3.  Add the New Relic gem to your `Gemfile`. The New Relic Ruby agent's gem is available from [rubygems.org](https://rubygems.org/) as `newrelic_rpm`.

    If your app uses Bundler, add this gem to the `Gemfile`:

    ```ruby
    gem 'newrelic_rpm'
    ```
4.  Restart your dyno.
5.  Generate some traffic to your app.

**Non-Rails applications**

If you're using Ruby agent for New Relic 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:

````ruby
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](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page).

## Troubleshooting your installation [#troubleshooting]

Within a few minutes of installing and configuring New Relic, data should start appearing in your app's [APM summary page](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/apm-overview-page). If no data appears, follow the [Ruby agent troubleshooting procedures](https://docs.newrelic.com/docs/agents/ruby-agent/troubleshooting/no-data-appears-ruby).

## Upgrade from an existing New Relic installation [#upgrading]

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

```bash
heroku config:set NEW_RELIC_APP_NAME='Your Application Name'
```

## Configure the Ruby agent on Heroku [#configuring]

You can configure New Relic in your `newrelic.yml` file, or you can use [environment variables](https://docs.newrelic.com/docs/agents/ruby-agent/installation-configuration/ruby-agent-configuration) 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`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#custom_insights_events-max_samples_stored) setting to 500:

```bash
heroku config:set NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_SAMPLES_STORED=500
```

## Hostnames on Heroku [#hostnames]

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 [#dyno-hostnames]

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`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#heroku) configuration setting to apply the same aggregation to these other dyno types.

## Logging for Heroku [#logging]

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
    heroku config
    ```
2.  To reset the environment variable if necessary, run:

    ```bash
    heroku config:set NEW_RELIC_LOG="stdout"
    ```
3.  Open your `newrelic.yml` file in an editor.
4.  Change the [`log_level`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#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
    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`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#log_level) to the previous setting. Save the file.