README.rdoc

New Relic Ruby Agent

New Relic is a performance management system, developed by New Relic, Inc
(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 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 newrelic.com 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, 1.9.1, or 1.9.2, including REE

JRuby 1.4 or higher

Rails 2.0 or later for Production Mode

Rails 2.3 or later for Developer Mode

Sinatra

Rack

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 to support@newrelic.com.

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

Getting Started

Install the Ruby Agent as a gem. If you are using Rails you can install
the gem as a plug-in–details below.

gem install newrelic_rpm

To monitor your applications in production, create an account at 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, copy the newrelic.yml file into your
app config directory.

All agent 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

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"

Merb Installation

To monitor a merb app install the newrelic_rpm gem and add

dependency 'newrelic_rpm'

to your init.rb file.

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; i.e., development,
staging, production, etc.

To use Developer Mode in Sinatra, add NewRelic::Rack::DeveloperMode to the
middleware stack. See the config.ru 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

NewRelic::Agent.manual_start

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

Refer to the docs in New Relic for details on how to monitor other web
frameworks, background jobs, and daemons.

Also, see if your environment is already supported by the rpm_contrib gem.

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:

http://localhost:3000/newrelic

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
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.

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 rpm.newrelic.com.

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

Support

Reach out to us–and to fellow users–at support.newrelic.com. There
you'll find documentation, FAQs, and forums where you can submit
suggestions and discuss New Relic with staff and other users.

Also available is community support on IRC: we generally use #newrelic on
irc.freenode.net