Celerbrake Ruby

Celerbrake Ruby is a lightweight, dependency-light Ruby notifier for Celerbrake — a self-hosted error- and exception-tracking service. It captures Ruby exceptions and ships them to a Celerbrake instance, where they are grouped, de-duplicated, and rendered with full backtraces, occurrence timelines, and request context.

This gem is the plain-Ruby core. If you run Rails, Sinatra, or any other Rack-compliant framework, use the higher-level celerbrake gem instead — it depends on this one and wires up automatic, unhandled-exception reporting plus integrations with ActiveJob, Sidekiq, Resque, Delayed Job, and more.

Heritage. Celerbrake Ruby began life as a fork of airbrake-ruby (v6.2.1) and stays wire-compatible with the Airbrake v3 create-notice API. The substantive difference is that the default reporting host is https://api.celerbrake.com instead of a third-party service, so you control the whole pipeline. We are grateful to Airbrake Technologies, Inc. for the original, MIT-licensed work — see LICENSE.md.

gem 'celerbrake-ruby'

gem install celerbrake-ruby

• Asynchronous (and synchronous) exception reporting with a background worker pool and bounded queue
• Automatic backtrace parsing, code-hunk extraction, and root-directory trimming
• A flexible filter chain for adding context, ignoring notices, or redacting sensitive data before it leaves your process
• Built-in redaction of common secret-shaped keys (password, secret, *_token, authorization, ...)
• Minimal dependencies; suitable for plain Ruby scripts, daemons, and gems

Before sending notices, configure the notifier with the project id and project key issued by your Celerbrake instance (created at /admin/projects on the server).

require 'celerbrake-ruby'

Celerbrake.configure do |c|
  c.project_id  = 123
  c.project_key = 'fa0123456789abcdef0123456789abcd'

  # Defaults to https://api.celerbrake.com. Point this at your own instance.
  c.host = 'https://errors.example.com'

  # Report only from these environments.
  c.environment         = ENV['RACK_ENV']
  c.ignore_environments = %w[development test]
end

begin
  raise 'Oops!'
rescue => exception
  Celerbrake.notify(exception)
end

Celerbrake.notify is asynchronous and returns a promise. Use Celerbrake.notify_sync when you need to block until the notice is delivered (e.g. in a one-off script or a Rake task):

Celerbrake.notify_sync(StandardError.new('hello from a script'))

Celerbrake.notify(exception) do |notice|
  notice[:context][:user] = { id: 42, email: 'user@example.com' }
  notice[:params][:document_id] = document.id
end

Filters run on every notice and can mutate it, add context, or ignore it entirely:

# Ignore a class of errors.
Celerbrake.add_filter do |notice|
  notice.ignore! if notice[:errors].any? { |e| e[:type] == 'PageNotFound' }
end

# Redact a custom sensitive key.
Celerbrake.blocklist_keys << /credit_card/i

Celerbrake Ruby supports Ruby 2.5+ (matching its upstream baseline). CI targets current stable Ruby releases.

Bug reports and pull requests are welcome. Run the test suite with:

bundle install
bundle exec rspec
bundle exec rubocop

Celerbrake Ruby is released under the MIT License. It is a derivative work of airbrake-ruby, also MIT-licensed; the original copyright is preserved in LICENSE.md.