Ruby SDK

Or add gem 'bugstack' to your Gemfile and run bundle install.

# config/initializers/bugstack.rb
require 'bugstack'

Bugstack.configure do |config|
  config.api_key = ENV['BUGSTACK_API_KEY']
end

# That's it! bugstack automatically captures
# unhandled exceptions in your Rails app.

The bugstack Ruby SDK installs itself into Rails' error-reporting subsystem as soon as Bugstack.init runs in an initializer. It subscribes to Rails.error and captures exceptions raised inside controller actions, background jobs, Action Mailer deliveries, and Turbo/Hotwire stream handlers. Each report carries the full backtrace, the controller/action pair, request parameters (with PII-filtered fields removed), and the current Current.user.id if your app exposes one.

Reports are delivered over a background thread using Concurrent::Promises so reporting never blocks the response cycle. A bounded in-memory queue means memory stays flat even under sustained error bursts.

Rails 7+ uses the unified error-reporter API, so installation is a single line in config/initializers/bugstack.rb. For Rails 6 and earlier, the SDK falls back to a rescue_from hook installed on ApplicationController. Sidekiq is captured via Sidekiq.configure_server and the death_handlers extension — retried jobs maintain fingerprint continuity so you see retry counts rather than duplicate incidents.

ActiveJob backends (Delayed Job, Good Job, Resque) are covered via the built-in around_perform callback. Hotwire Turbo stream errors and ActionCable channel disconnects are surfaced as their own event classes so you can filter them in the dashboard.

• api_key (required) — read from ENV['BUGSTACK_API_KEY'].
• environment (optional) — defaults to Rails.env.
• release (optional) — set to your deployed git SHA; exposed via ENV['HEROKU_SLUG_COMMIT'], ENV['RENDER_GIT_COMMIT'], or similar.
• sample_rate (optional) — 0.0–1.0 float, default 1.0.
• before_send (optional) — block that receives an event hash and returns a modified hash or nil to drop.
• ignored_exceptions (optional) — array of exception class names as strings to skip entirely (e.g. 'ActionController::RoutingError').

The errors that appear most often in production Rails apps, each with a dedicated fix guide:

• ActiveRecord::RecordNotFound
• ActionController::RoutingError
• N+1 query detected by Bullet
• ActionController::UnpermittedParameters
• InvalidAuthenticityToken
• Migration pending
• PG::ConnectionBad
• Sidekiq retry exhaustion

No events after deploy? Check your initializer runs in production — Rails eager-loads initializers in production but some config.after_initialize blocks don't execute if an earlier initializer raises. Run RAILS_ENV=production bundle exec rails runner 'puts Bugstack.configured?' to verify.

Sidekiq errors missing? Confirm the bugstack gem is in the default group, not :web. Sidekiq workers load their own subset of the Gemfile, and gems scoped to :web will be silently absent in the worker process.

Error fingerprints look inconsistent? If your controllers use dynamic error messages (e.g. raise "User #{id} not found"), fingerprinting will produce one event per ID. Normalize the message and put the ID in context data instead.

See the full Ruby installation guide for Sidekiq pro configuration, ActionMailer capture, and custom controller concerns.

The SDK transmits the exception class, message, backtrace, controller and action, request path and method, and response status to the bugstack API. Filtered parameters (those matching Rails.application.config.filter_parameters) are redacted before transmission — your password, secret, and token params stay on your servers. Cookies and session contents are never transmitted. The GitHub App reads only the Ruby files named in the backtrace — not your full application. All data travels over TLS and is encrypted at rest. Review the data handling doc for retention policies and deletion workflows.

The gem follows semver. Ruby 3.0+ is supported; 2.7 reaches EOL on our side when Ruby itself drops it. Rails 6.1, 7.0, 7.1, and 7.2 are all supported. Sidekiq 6.x and 7.x work out of the box. The gem has zero runtime dependencies outside the Ruby standard library and concurrent-ruby, which Rails already pulls in. gem install bugstack or adding gem 'bugstack' to your Gemfile is the entire install.

View the full source code, report issues, and contribute on GitHub.

← Back to Documentation