Recording deployments with the Ruby agent

New Relic allows you to send information about application deployments via the REST API or a Capistrano recipe (versions 2.x and 3.x) distributed with the Ruby agent. You can then view deployments in the New Relic UI. By default all deployment information is recorded in your production environment. You can also customize the rails_env variable for other environments, such as staging.

Access to this feature depends on your subscription level.

Assigning an application name

To assign an application name:

  1. Download the latest version of the Ruby Agent.
  2. Set the app_name in your newrelic.yml file to a meaningful name.

This will assign instances in the given environment the label given by app_name when browsing your data in the New Relic user interface. The deployment upload script will use that label to associate an app with the deployment.

Recording with the command line

If you installed the Ruby agent as a gem, you can record deployments directly via the newrelic executable:

newrelic deployments

newrelic takes several options, all of which are optional. The description is short text.

deployments [OPTIONS] [description] 
   -a, --appname=name           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

Note: When using the -c option, you can pipe the changelog into the script. If not piping when using the -c option, select control-D to signify the EOF (end of file).

Recording with Capistrano 3.x

The New Relic Ruby agent contains a Capistrano recipe that can record app deployments. After assigning your app name, edit your Capistrano files to communicate with the agent:

  1. At the top of your Capfile, add the following line:

    require 'new_relic/recipes'
  2. In your deploy.rb file, include:

    after "deploy:updated", "newrelic:notice_deployment"

Recording with Capistrano 2.x

You can also record Capistrano 2.x deployments with the New Relic agent:

  1. First, you must tell Capistrano to load New Relic's recipes:

    If agent was installed with New Relic gem

    Add this at the top of your deploy.rb file:

    require 'new_relic/recipes'
    If agent was installed as Rails plugin

    In your Capfile, add the following line above load deploy.rb (if it's not already there):

    Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
  2. Next, add the following hooks to your deploy.rb file:

    # Notify New Relic of deployments.
    # This goes out even if the deploy fails, sadly.
    after "deploy",            "newrelic:notice_deployment"
    after "deploy:migrations", "newrelic:notice_deployment"
    after "deploy:cold",       "newrelic:notice_deployment"

The next time you run cap deploy, the agent notifies New Relic of the deployment, and all time series graphs will show the deployment event.

Customizing your Capistrano configuration

You can customize some deployment information via Capistrano variables. If defined, these will override the defaults. These apply to both Capistrano 2 and 3.

Capistrano variable Description

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

Note: If you set this value via the command line, you can only specify one application name. If you set this value in newrelic.yml, only the first application name will be used.

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_desc A descriptive text that appears with the deployment. Default is empty.
newrelic_license_key The New Relic license key to use. By default this comes from the definition in the newrelic.yml file for the given rails_env. Note that this is not the same as your REST API key.
newrelic_revision The revision recorded for the deployment. If you are using Subversion, you might also want to include the tag or branch name in addition to the revision.
newrelic_user The user to associate with the deployment

In any version of Capistrano you can override these settings in your deploy.rb:

set :newrelic_user, "username"

In Capistrano 2.x you can override these on the command line like this:

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

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: "

Deploying to staging

By default, the newrelic_rpm gem comes with Capistrano tasks to record all deployments in your production environment. If you have a separate staging application, you can change the rails_env variable setting so that staging deployments are recorded in the staging app instead of the production app.

To identify deployments to your staging environment, use Capistrano or the command line.

If you're using Capistrano multistage, add this line to config/deploy/staging.rb:

set :rails_env, "staging"

Otherwise, for Capistrano 2.x add this information from the command line:

cap -s rails_env=staging deployment_task_name

For more help

Additional documentation resources include:

Join the discussion about Ruby in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at