Install the New Relic Ruby agent

Installing the New Relic Ruby agent enables you to monitor the performance of your application and obtain deep visibility into your Ruby app.

To install the agent, use our launcher or follow the instructions below.

Install the gem

If you are using the agent in a Docker container, install the agent within each container.

  1. The Ruby agent's gem is available from as newrelic_rpm. For applications using Bundler, add this gem to the Gemfile:

    gem 'newrelic_rpm'
  2. To use Infinite Tracing, the Infinite Tracing gem is also available from as newrelic-infinite_tracing. For applications using Bundler, additionally include the Infinite Tracing gem in the Gemfile:

    gem 'newrelic-infinite_tracing'
  3. The next step varies depending on if you are using Rails or Sinatra:

    Ruby installation Comments
    If using Rails or Sinatra
    • Rails: If you're using Rails 3 or higher, or Rails 2.3 in the recommended configuration, Rails will automatically call Bundler.require and cause newrelic_rpm to be required during startup of your application.
    • Sinatra: If you're using Sinatra or another framework, you must either manually call require 'newrelic_rpm', or call Bundler.require.
    If not using Rails or Sinatra

    In order to use automatic Browser application monitoring and Cross application tracing in a Rack application that does not use Sinatra or Rails, you must manually include additional Rack middlewares provided by the agent. Place the New Relic gem as low in the list as possible, allowing the frameworks above it to be instrumented when the gem initializes.

Install the configuration file

After installing the agent, you will need to install the newrelic.yml file, also known as the configuration file and name your app:

  1. Sign in to New Relic.
  2. From the account dropdown, select Account settings.
  3. On the Account settings page, look for the Download a clean configuration file section and click the newrelic.yml file.
  4. Copy the newrelic.yml file into the config sub-directory of your application.
  5. Change the default application name to a meaningful name.

Alternatively, you can generate a newrelic.yml file manually with the following command:

newrelic install --license_key="YOUR_KEY" "My application"

You may also use the --force option with this command if you need to overwrite an existing newrelic.yml.

Update the agent

See Upgrade Ruby agent versions.

Install agent outside production environments

Typically you will install the Ruby agent in your production environment. If you want to try out the Ruby agent in a development or localhost environment, verify in the relevant environment: block of the newrelic.yml file that the monitor_mode config value has been set to true.

For example, to deploy New Relic in your development environment and still be able to view your app's performance metrics: In the development: block, set the monitor_mode config value to true.

Uninstall the Ruby agent gem

To uninstall the Ruby agent using Bundler, remove gem 'newrelic_rpm' from your Gemfile. If you are not using Bundler, remove all references to newrelic_rpm from your environment.rb file.

Install on older versions of Rails

If you're installing the Ruby agent on Rails 2.x, and aren't using Bundler, follow these procedures.

Ruby installation Comments
Rails 2.1 - 2.3 without Bundler
  1. Install the gem using gem install newrelic_rpm.
  2. Edit environment.rb, and add to the initializer block:

    config.gem "newrelic_rpm"
  3. If enabling Infinite Tracing, add the following to the next line in the environment.rb file:
    config.gem "newrelic-infinite_tracing"
Rails earlier than 2.1

New Relic does not officially support Rails versions prior to 2.1. However, if you want to use New Relic for Rails versions 2.0.*, edit environment.rb and add this statement after the initializer: block:

require "newrelic_rpm"

Infinite Tracing

If enabling Infinite Tracing, add the following to the next line in the environment.rb file:

require "newrelic/infinite_tracing"

For more help

Additional documentation resources include:

  • Ruby agent configuration (general configuration settings, proxy, transaction tracer, error collection, and updates)
  • New Relic for Ruby (overview of compatibility and requirements, installation, configuration, troubleshooting, known issues, advanced features, and beta releases)
  • Updating deprecated Ruby agents (Ruby agent versions that New Relic no longer supports, how to verify the version your app uses, and how to ensure you have the most up-to-date version)

If you need more help, check out these support and learning resources: