Installing the gem
The New Relic Ruby agent's gem is available from rubygems.org as
For applications using Bundler, just add the gem to the Gemfile:
If you're using Rails 3 or above, 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. If you're using Sinatra or another framework, you'll need to either manually call
require 'newrelic_rpm', or call
Note: In order to use automatic Browser Application Monitoring and Cross Application Tracing in a Rack application that does not use Sinatra or Rails, manually include additional middlewares provided by the agent. See Rack Middlewares.
Tip: Place the New Relic gem as low in the list as possible, allowing the frameworks above it to be instrumented when the gem initializes.
Installing the configuration file
After installing the agent:
- Copy the newrelic.yml file into the config sub-directory of your application.
- Change the default application name to a meaningful name.
You can download a fresh newrelic.yml that includes your license key from the Account settings when logged in to rpm.newrelic.com.
Updating the agent
If you're using Bundler, run
bundle update newrelic_rpm. Otherwise, run
gem update newrelic_rpm.
Installing outside production environments
Typically you will install the New Relic 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
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. For more information about using New Relic's Ruby agent outside production environments, see Developer mode.
Uninstalling 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.
Installing on older versions of Rails
If you're installing the Ruby agent on Rails 2.x, and aren't using Bundler, use the instructions below.
Rails 2.1 - 2.3 without Bundler
- Install the gem using
gem install newrelic_rpm.
- Edit environment.rb, and add to the initializer block:
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:
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)