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:

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

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

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

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

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

Now you can easily expose this to your error handler:

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

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

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

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

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

Copied
{
  :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.

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

level
The level of the event. Defaults to error.

Copied
{
  :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.

Copied
{
  :logger => 'default'
}

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

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

user
The acting user.

Copied
{
  :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.

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

You can edit this page on GitHub.