Usage

To use Raven Ruby all you need is your DSN. Like most Sentry libraries it will honor the SENTRY_DSN environment variable. You can find it on the project settings page under API Keys. You can either export it as environment variable or manually configure it with Raven.configure:

Raven.configure do |config|
  config.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0'
end

If you only want to send events to Sentry in certain environments, you should set config.environments too:

Raven.configure do |config|
  config.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0'
  config.environments = ['staging', 'production']
end

Reporting Failures

If you use Rails, Rake, Rack etc, you’re already done - no more configuration required! Check Integrations for more details on other gems Sentry integrates with automatically.

Otherwise, Raven supports two methods of capturing exceptions:

Raven.capture do
  # capture any exceptions which happen during execution of this block
  1 / 0
end

begin
  1 / 0
rescue ZeroDivisionError => exception
  Raven.capture_exception(exception)
end

Reporting Messages

If you want to report a message rather than an exception you can use the capture_message method:

Raven.capture_message("Something went very wrong")

Referencing Events

The client exposes a last_event_id accessor allowing you to easily reference the last captured event. This is useful, for example, if you wanted to show the user a reference on your error page:

# somewhere deep in the stack
Raven.capture do
  1 / 0
end

Now you can easily expose this to your error handler:

class ErrorsController < ApplicationController
  def internal_server_error
    render(:status => 500, :sentry_event_id => Raven.last_event_id)
  end
end

Optional Attributes

With calls to capture_exception or capture_message additional data can be supplied:

Raven.capture_message("...", :attr => 'value')

extra

Additional context for this event. Must be a mapping. Children can be any native JSON type.

{
  :extra => {'key' => 'value'}
}

backtrace

Stack trace to attach to this event. Must be an array of strings; usually caller (the current stack trace).

{
  :backtrace => caller # (or any other array of strings representing a backtrace)
}

Note: capture_exception will take the backtrace from the exception, by default, if available.

fingerprint

The fingerprint for grouping this event.

{
  :fingerprint => ['{{ default }}', 'other value']
}

level

The level of the event. Defaults to error.

{
  :level => 'warning'
}

Sentry is aware of the following levels:

• debug (the least serious)
• info
• warning
• error
• fatal (the most serious)

logger

The logger name for the event.

{
  :logger => 'default'
}

tags

Tags to index with this event. Must be a mapping of strings.

{
  :tags => {'key' => 'value'}
}

user

The acting user.

{
  :user => {
    'id' => 42,
    'email' => 'clever-girl'
  }
}

Many Instances

It is possible to have many different instances and configurations of the Raven client running at once. See the delegation pattern in base.rb for more information about how the Raven module delegates calls to the “main” instance.

Raven.capture # capture, sent to the main instance

# You can create as many instances as you like. Provide a context and config.
instance = Raven::Instance.new(Raven::Context.new, Raven::Configuration.new)

Currently, all integrations use the “main” instance.