Skip to content
This repository

New Relic RPM Ruby Agent

branch: master
Octocat-spinner-32 bin Scarier warning on nrdebug December 02, 2013
Octocat-spinner-32 cert push fresh root certs because the old ones suddenly did not work June 03, 2011
Octocat-spinner-32 config RUBY-945 Run Unit Tests in Standalone Mode November 14, 2012
Octocat-spinner-32 lib RUBY-1279 Clean up loading of Cli::Command subclasses March 11, 2014
Octocat-spinner-32 recipes Add license header to source files February 22, 2013
Octocat-spinner-32 test Test require fix March 11, 2014
Octocat-spinner-32 ui RUBY-1267 RubyProf based on transaction February 03, 2014
Octocat-spinner-32 vendor RUBY-1171 Retain old return value for DependencyDetection.defer August 06, 2013
Octocat-spinner-32 .gitignore Ignore yard generated directory October 11, 2013
Octocat-spinner-32 .project Aptana .project file change May 18, 2011
Octocat-spinner-32 .travis.yml Add Ruby 2.1.0 to .travis.yml December 30, 2013
Octocat-spinner-32 .yardopts Add Transaction and MetricFrame to the public API October 11, 2013
Octocat-spinner-32 CHANGELOG Test require fix March 11, 2014
Octocat-spinner-32 Clean up multiverse rake tasks and docs December 20, 2012
Octocat-spinner-32 Gemfile Removing debugging wrongly added to Gemfile January 20, 2014
Octocat-spinner-32 Guardfile
Octocat-spinner-32 LICENSE Update copyright notice for the new year January 28, 2014
Octocat-spinner-32 Point customers to if they experience issues. January 16, 2014
Octocat-spinner-32 Rakefile Use Pry instead of IRB since already depend on it February 06, 2014
Octocat-spinner-32 RUBY-874: kill all whitespace July 01, 2013
Octocat-spinner-32 gem-public_cert.pem Updating signing cert February 13, 2014
Octocat-spinner-32 init.rb Point customers to if they experience issues. January 16, 2014
Octocat-spinner-32 install.rb RUBY-1176: Rename to clarify Command namespace August 15, 2013
Octocat-spinner-32 newrelic.yml Change comment to indicate development reports to NR October 08, 2013
Octocat-spinner-32 newrelic_rpm.gemspec added Chris Pine to authors February 28, 2014

New Relic Ruby Agent

New Relic is a performance management system, developed by New Relic, Inc ( It provides you with deep information about the performance of your Rails or Ruby application as it runs in production. The New Relic Ruby Agent is dual-purposed as a either a Rails plugin or a Gem, hosted on github.

The New Relic Ruby Agent runs in one of two modes:

Production Mode Low overhead instrumentation that captures detailed information on your application running in production and transmits them to where you can monitor them in real time.

Developer Mode A Rack middleware that maps /newrelic to an application for showing detailed performance metrics on a page by page basis. Installed automatically in Rails applications.

Supported Environments

  • Ruby 1.8.7, REE, 1.9.x, 2.0.x
  • JRuby 1.6 and 1.7
  • Rubinius 2.x (Experimental support only)
  • Rails 2.1 or later for Production Mode
  • Rails 2.3 or later for Developer Mode
  • Sinatra
  • Rack

An up to date list of Ruby versions and frameworks for the latest agent can be found on our docs site.

Any Rack based framework should work but may not be tested. Install the Ruby Agent as a gem and add the Developer Mode middleware if desired. Report any problems by visiting

You can also monitor non-web applications. Refer to the "Other Environments" section under "Getting Started".

Contributing Code

We welcome code contributions (in the form of pull requests) from our user community. Before submitting a pull request please review GUIDELINES_FOR_CONTRIBUTING.

Following these helps us efficiently review and incorporate your contribution and avoid breaking your code with future changes to the agent.

Getting Started

Install the Ruby Agent as a gem.

gem install newrelic_rpm

Or add it to your project's Gemfile.

gem 'newrelic_rpm'

To monitor your applications in production, create an account at . There you can sign up for a free Lite account or one of our paid subscriptions.

Once you receive the welcome e-mail with a license key and newrelic.yml file, copy the newrelic.yml file into your app config directory.

The initial configuration is done in the newrelic.yml file. This file is by default read from the config directory of the application root and is subsequently searched for in the application root directory, and then in a ~/.newrelic directory. Once you're up and running you can enable Server Side Config and manage your newrelic configuation from the web UI.

Rails Installation

You can install the agent as a Gem:

For Bundler:

Add the following line to your Gemfile:

gem 'newrelic_rpm'

For Rails 2.x without Bundler:

edit environment.rb and add to the initalizer block:

config.gem "newrelic_rpm"

Sinatra Installation

To use the Ruby Agent with a Sinatra app, add

require 'newrelic_rpm'

in your Sinatra app, below the Sinatra require directive.

Then make sure you set RACK_ENV to the environment corresponding to the configuration definitions in the newrelic.yml file; e.g., development, staging, production, etc.

To use Developer Mode in Sinatra, add NewRelic::Rack::DeveloperMode to the middleware stack. See the sample below.

Other Environments

You can use the Ruby Agent to monitor any Ruby application. Add

require 'newrelic_rpm'

to your startup sequence and then manually start the agent using


To instrument Rack based applications, refer to the docs in NewRelic::Agent::Instrumentation::Rack.

Refer to the New Relic's Docs for details on how to monitor other web frameworks, background jobs, and daemons.

The Ruby Agent provides an API that allows custom instrumentation of additional frameworks. You can find a list of community created intrumentation plugins (e.g. newrelic-redis) in the RPM Contrib README.

Developer Mode

When running the Developer Mode, the Ruby Agent will track the performance of every HTTP request serviced by your application, and store in memory this information for the last 100 HTTP transactions.

To view this performance information, including detailed SQL statement analysis, open /newrelic in your web application. For instance if you are running mongrel or thin on port 3000, enter the following into your browser:


Developer Mode is only initialized if the developer_mode setting in the newrelic.yml file is set to true. By default, it is turned off in all environments but development.

Developer Mode in Rails

Developer Mode is available automatically in Rails Applications based on Rails 2.3 and later. No additional configuration is required. When your application starts and developer_mode is enabled, the Ruby Agent injects a middleware into your Rails middleware stack.

For earlier versions of Rails that support Rack, you can use a as below.

Developer Mode in Rack Applications

Developer Mode is available for any Rack based application such as Sinatra by installing the NewRelic::Rack::DeveloperMode middleware. This middleware passes all requests that do not start with /newrelic.

Here's an example entry for Developer Mode in a file:

require 'new_relic/rack/developer_mode'
use NewRelic::Rack::DeveloperMode

Production Mode

When your application runs in the production environment, the New Relic agent runs in production mode. It connects to the New Relic service and sends deep performance data to the UI for your analysis. To view this data, log in to

NOTE: You must have a valid account and license key to view this data online. Refer to instructions in Getting Started.


You can find more detailed documentation on our website, and specifically in the Ruby category.

If you can't find what you're looking for there, reach out to us on our support site and we'll be happy to help you.

Also available is community support on IRC: we generally use #newrelic on

Find a bug? Contact us via, or e-mail support @

Thank you, and may your application scale to infinity plus one.

Lew Cirne, Founder and CEO

New Relic, Inc.

Something went wrong with that request. Please try again.