This is the official provider for the Ruby ecosystem - it also has built-in support for Rails.

Ruby is a great, flexible language that allows you to write powerful applications, whether for the web with a framework or elsewhere.

Raygun allows your app to automatically send real time error and crash reports, and place them on a dashboard, allowing you to easily diagnose and fix the issue.

Raygun4Ruby Features

This provider has first-class support for:

1. Ruby 2.0 or greater
2. Rails 3+

It also includes a Resque failure backend, for notifying Raygun if its queue falls over.

Step 1 - Installation

Ruby Gems simplify the process of managing and utilizing third-party libraries in your Ruby projects. To add raygun4ruby to your project, follow these steps:

Bundle Install

1. Add the following line to your application's Gemfile:

gem 'raygun4ruby'

2. Execute the following command in your terminal:

bundle install

This will download and install raygun4ruby gem, as well as resolve and install dependencies.

Manual Install

Instead of adding it to your project's Gemfile, you can install raygun4ruby manually with the following command:

gem install raygun4ruby

Step 2 - Configuration

In Rails, execute the following command in your terminal:

rails g raygun:install paste_your_api_key_here

You can find your API key in the Raygun app under Application Settings.

Step 3 - Testing Your Raygun Integration

Test your Raygun setup by running the following command in your terminal:

rake raygun:test

If successful, you should see an "ItWorksException" appear in the Raygun app.

By default the Rails integration is set to only report Exceptions in Production.

To change this behaviour, set config.enable_reporting to something else in config/initializers/raygun.rb.

For more information on how to customise this provider, please see our feature overview for this provider.

Rails 2

Raygun4Ruby doesn't currently support Rails 2.
If you'd like Rails 2 support, let us know in our forums.

Sinatra

To enable exception tracking in Sinatra, just add configure Raygun and use the Rack middleware in your app:

require 'raygun4ruby'
Raygun.setup do |config|
  config.api_key = "paste_your_api_key_here"
end
use Raygun::Middleware::RackExceptionInterceptor

Feature Overview

Manual exception tracking

With vanilla Ruby, it's easy as:

require 'rubygems'
require 'raygun4ruby'

Raygun.setup do |config|
  config.api_key = "YOUR_RAYGUN_API_KEY"
  config.filter_parameters = [ :password, :card_number, :cvv ] # don't forget to filter out sensitive parameters
  config.enable_reporting = true # to send errors, false to not log
end

begin
  # your lovely code here
rescue Exception => e
  Raygun.track_exception(e)
end

You can also pass a Hash as the second parameter to track_exception. It should look like a Rack Env Hash

Custom User Data

Custom data can be added to track_exception by passing a custom_data key in the second parameter hash.

begin
  # more lovely code
rescue Exception => e
  Raygun.track_exception(e, custom_data: {my: 'custom data', goes: 'here'})
end

This data is filtered by default using the options set in Rails.application.config.filter_parameters. To setup additional keys please see the section below titled Sensitive POST data filtering.

Ignoring Some Errors

You can ignore certain types of Exception using the ignore option in the setup block, like so:

Raygun.setup do |config|
  config.api_key = "MY_SWEET_API_KEY"
  config.ignore  << ['MyApp::AnExceptionIDontCareAbout']
end

The following exceptions are igonored by default:

ActiveRecord::RecordNotFound
ActionController::RoutingError
ActionController::InvalidAuthenticityToken
ActionDispatch::ParamsParser::ParseError
CGI::Session::CookieStore::TamperedWithCookie
ActionController::UnknownAction
AbstractController::ActionNotFound
Mongoid::Errors::DocumentNotFound

You can see this here and unignore them if needed by doing the following:

Raygun.setup do |config|
  config.api_key = "MY_SWEET_API_KEY"
  config.ignore.delete('ActionController::InvalidAuthenticityToken')
end

Using a Proxy

You can pass proxy settings using the proxy_settings config option.

Raygun.setup do |config|
  config.api_key = "MY_SWEET_API_KEY"
  config.proxy_settings = { host: "localhost", port: 8888 }
end

Sensitive POST data filtering

The provider can automatically remove data you don't want transmitted, such as passwords or credit card info. This defaults to Rails.application.config.filter_parameters, but you can specify additional keys like this:

Raygun.setup do |config|
  config.api_key = "YOUR_RAYGUN_API_KEY"
  config.filter_parameters = [ :password, :card_number, :cvv ]
end

This filtering also applies to information submitted through the custom user data mentioned previously.

Customizing Parameter Filtering

If you'd like to customize how parameters are filtered, you can pass a Proc to filter_parameters. Raygun4Ruby will yield the params hash to the block, and the return value will be sent along with your error.

Raygun.setup do |config|
  config.api_key = "YOUR_RAYGUN_API_KEY"
  config.filter_parameters do |params|
    params.slice("only", "a", "few", "keys") # note that Hash#slice is in ActiveSupport
  end
end

Affected User Tracking

Raygun can now track how many users have been affected by an error.

By default, Raygun looks for a method called current_user on your controller, and calls either email, username or id on the object returned by that method.

You can customize those method names in your configuration block:

Raygun.setup do |config|
  config.api_key = "MY_SWEET_API_KEY"
  config.affected_user_method = :my_current_user # `current_user` by default
  config.affected_user_identifier_methods << :login # `[ :email, :username, :id ]` by default - will use the first that works
end

If you're using Rails, most authentication systems will have this method set and you should be good to go.

The count of unique affected users will appear on the error group in the Raygun app. If your user has an email method, and that email has a Gravatar associated, you will also see your user's avatar.

If you wish to keep it anonymous, you could set this identifier to something like SecureRandom.uuid and store that in a cookie, like so:

class ApplicationController < ActionController::Base
  def raygun_user
    cookies.permanent[:raygun_user_identifier] ||= SecureRandom.uuid
  end
end

(Remember to set affected_user_method to :raygun_user in your config block...)

The string properties on a User have a maximum length of 255 characters. Users who have fields that exceed this amount will not be processed.

Version tracking

Raygun can attach the version of your application to its error reports. In your Raygun.setup block, set version to the current version of your app.

Raygun.setup do |config|
  config.version = "1.0.0.4" # you could also pull this from ENV or however you want to set it.
end

Tags

Raygun allows you to tag error reports with any number of tags. In your Raygun.setup block, set tags to an array of strings to have those set on any error reports sent by the gem.

Raygun.setup do |config|
  config.tags = ['heroku']
end

Alternatively, it can be set to a proc, which gets passed the exception and environment hash. This proc must return an array of strings.

Raygun.setup do |config|
  config.api_key = "YOUR_RAYGUN_API_KEY"
  config.tags do |e, env|
    [env["SERVER_NAME"]]
  end
end

Tags can be added to track_exception by passing a tags key in the second parameter hash.

begin
  # more lovely code
rescue Exception => e
  Raygun.track_exception(e, tags: ['my', 'tags', 'go here'])
end

Resque Error Tracking

Raygun4Ruby also includes a Resque failure backend. You should include it inside your Resque initializer (usually something like config/initializers/load_resque.rb)

require 'resque/failure/multiple'
require 'resque/failure/raygun'
require 'resque/failure/redis'

Resque::Failure::Multiple.classes = [Resque::Failure::Redis, Resque::Failure::Raygun]
Resque::Failure.backend = Resque::Failure::Multiple

Sidekiq Error Tracking

Raygun4Ruby can track errors from Sidekiq (2.x or 3+). All you need to do is add the line:

  require 'raygun/sidekiq'

Either in your Raygun initializer or wherever else takes your fancy :)