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

This notifier runs inside your app's request path, so it is built to fail quietly and bounded rather than to hold a thread hostage:

• Celerbrake.notify never blocks. The background queue is bounded; when it is full the notice is dropped, counted (ThreadPool#dropped_count) and logged at most once every 10 seconds.
• Every HTTP call is bounded. With config.timeout unset the notifier uses open 2s / read 5s / write 5s. Setting config.timeout overrides all three.
• A 429 always backs off — for a bounded time. The delay comes from Retry-After (delta-seconds or HTTP-date), then the legacy X-RateLimit-Delay, then a 60s default (Response::DEFAULT_RATE_LIMIT_DELAY).

A 429 can come from anything on the path — a proxy, a WAF, a CDN, a misconfigured load balancer — not just from Celerbrake, so the notifier does not let a response header decide how long your app stops reporting:

15 minutes is the ceiling because Celerbrake rate limits per minute, so any legitimate relief window is minute-scale — while a bogus value can cost you at most a quarter hour of reporting, never a shift.

Suppression is tracked per sender and per endpoint (errors, performance and deploys use separate senders), so a 429 minted for one destination cannot silence the others. While suppressed, the notifier logs one line per 10 seconds and exposes the state, so an operator — or an agent asking "why did this app go quiet?" — can tell that reporting is paused and until when:

sender.rate_limited?      #=> true
sender.rate_limit_reset   #=> 2026-07-26 18:04:11 UTC (when sends resume)
sender.rate_limited_drops #=> 412 (payloads dropped since startup)

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.