New Relic Ruby Agent
New Relic is a performance management system, developed by New Relic, Inc (http://www.newrelic.com). 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 Gem or a Rails plugin, 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 newrelic.com where you can monitor them in real time.
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.
- Ruby 1.8.7, REE, 1.9.x, 2.0.x, 2.1.x, 2.2.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
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 support.newrelic.com.
You can also monitor non-web applications. Refer to the "Other Environments" section under "Getting Started".
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.
Add the Ruby Agent to your project's Gemfile.
To monitor your applications in production, create an account at http://newrelic.com/ . 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. You can copy the
newrelic.yml file into your app config
directory OR can generate the file manually with command:
newrelic install --license_key="YOUR_KEY" "My application"
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 configuration from the web
You can install the agent as a Gem:
Add the following line to your Gemfile:
For Rails 2.x without Bundler:
environment.rb and add to the initalizer block:
To use the Ruby Agent with a Sinatra app, add
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
the middleware stack. See the
config.ru sample below.
You can use the Ruby Agent to monitor any Ruby application. Add
to your startup sequence and then manually start the agent using
For information about instrumenting pure Rack applications, see our Rack middlewares documentation.
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 extends_newrelic_rpm project.
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
/newrelic in your web application. For instance if
you are running mongrel or thin on port 3000, enter the following into
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
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
config.ru 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
require 'new_relic/rack/developer_mode' use NewRelic::Rack::DeveloperMode
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 http://rpm.newrelic.com.
NOTE: You must have a valid account and license key to view this data online. Refer to instructions in Getting Started.
The Ruby Agent supports recording deployments in New Relic via a command line tool or Capistrano recipes. For more information on these features see our deployment documentation for more information.
Also available is community support on IRC: we generally use #newrelic on irc.freenode.net
Find a bug? Contact us via support.newrelic.com, or e-mail support @ newrelic.com.
Thank you, and may your application scale to infinity plus one.
Lew Cirne, Founder and CEO
New Relic, Inc.