Installing the New Relic Ruby agent enables you to monitor the performance of your application and obtain deep visibility into your Ruby app.
To get started, watch this video tutorial to learn how to install and configure the Ruby agent in your project, confirm that the agent is reporting data about your app to New Relic, and do some basic troubleshooting. View more videos and tutorials at learn.newrelic.com.
Install the gem
The New Relic Ruby agent's gem is available from rubygems.org as
newrelic_rpm. For applications using Bundler, add this gem to the Gemfile:
Here are some additional installation tips.
|If using Rails or Sinatra||
|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:
- Log in to New Relic at rpm.newrelic.com.
- From the account dropdown in the New Relic UI, select Account settings.
- From the Account settings page, download a new newrelic.yml file.
- Copy the newrelic.yml file into the config sub-directory of your application.
- Change the default application name to a meaningful name.
Update the agent
To update the agent:
Using Bundler: Run this command:
bundle update newrelic_rpm
Not using Bundler: Run this command:
gem update newrelic_rpm
If you are updating from a 3.x agent to a 4.x agent, see Upgrade Ruby agent versions for detailed information about classes and methods that have been removed.
Install agent 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
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.
|Rails 2.1 - 2.3 without Bundler||
|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
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)