RPM allows you to send information about Ruby application deployments via capistrano or the command line. This information is presented in a number of ways. If you have a Lite or Bronze subscription, you will see deployment lines show up on all time series graphs. When hovering over these lines, information about who deployed is shown. For Silver subscribers, a deployment summary page is shown, listing all deployments along with information about each. For Gold subscribers, the details of a deployment can be drilled into.

Installation

1. Download the latest version of the RPM agent.
   
2. Set the app_name in your newrelic.yml file. This will assign instances in the given environment the label given by app_name when browsing your data in the RPM UI. The deployment upload script will use that id to associate an app with the deployment.
   

Capistrano Configuration

The facility for uploading deployments is only available when using Capistrano 2.0 or later.

Check your Capfile for the following line, and add if necessary, just above the load deploy.rb line. Later versions of Capistrano include this line in their default Capfile:

Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }

Add the hook to your deploy.rb to upload the deployment:

# We need to run this after our collector mongrels are up and running
# This goes out even if the deploy fails, sadly 
after "deploy:update", "newrelic:notice_deployment"

Additional Configuration for newrelic_rpm gem

If you installed RPM as a gem, add this to the top of your deploy.rb file:

require 'new_relic/recipes'

That's it! The next time you run cap deploy, RPM will be notified of the deployment, and all timeseries graphs will show the deployment event. Silver and Gold customers will also get drill-down deployment analysis.

Custom Capistrano Configuration

You can customize some of the information sent with the deployment info. The following three capistrano variables are checked and if defined, will override the defaults:

• newrelic_desc a descriptive text that appears with the deployment. Default is empty.

• newrelic_changelog the changelog which is determined by running the svn/git log command from the local working directory where the capistrano command was issued.

• newrelic_appname the app where the deployment will appear. By default this comes from the definition in the newrelic.yml file for the given rails_env.

• newrelic_revision the revision recorded for the deployment. If using subversion, you might also want to include the tag or branch name in addition to the revision.

You can override any of these on the command line like this:

cap production deploy -Snewrelic_desc="Deploying the the beta of Krakatau release"

Or you can define the override in your deploy.rb. This example will prompt for content that will appear in the "Change Log" tab of the deployment:

set(:newrelic_changelog) do
    Capistrano::CLI.ui.ask "Enter a summary of changes: "
end

Here's how we change the subversion revision identifier to include our tag:

set(:newrelic_revision) do
  tagname = repository =~ /\/([^\/]*)$/ && $1
  revnumber = source.query_revision(source.head()) { |cmd| `#{cmd}` }
  "#{tagname} (#{revnumber})"
end

Uploading Deployment Information with the Command Script

If you aren't using Capistrano, you can still send deployment information to RPM. The script is packaged in with the agent.

ruby vendor/plugins/newrelic_rpm/bin/newrelic_cmd deployments [options]

If you installed the agent as a gem, you can invoke the script directly:

newrelic_cmd deployments

The script takes several options, all of which are optional.

deployments [OPTIONS] [description] OPTIONS:
    -a, --appname=DIR                        Set the application name.
                                             Default is app_name setting in newrelic.yml
    -e, --environment=name                   Override the (RAILS|MERB|RUBY)_ENV setting
    -u, --user=USER                          Specify the user deploying.
    -r, --revision=REV                       Specify the revision being deployed
    -c, --changes                            Read in a change log from the standard input
    -h                                       Print this help

Where description is a short text.

When using -c, you can pipe the changelog into the script.