Install the Bugstack Ruby SDK

The gem reports uncaught server errors to Bugstack, which starts a fix. Setup for Rails, Sinatra and plain Ruby, with the full config reference.

Compatibility

Ruby 3.0+

Fixes for Ruby apps arrive as pull requests for your review. Bugstack’s verification sandbox does not run Ruby yet, so Autopilot does not merge Ruby fixes on its own.

Install

Gemfile

gem 'bugstack', '~> 1.0'

Then run:

bundle install

Or install directly:

gem install bugstack

Initialize

Call Bugstack.init once at startup with your API key and the Bugstack endpoint. Pass endpoint explicitly: the published gem does not default to it yet. Options can also be set in a block (Bugstack.init { |config| config.endpoint = "..." }).

require "bugstack"

Bugstack.init(
  api_key: ENV["BUGSTACK_API_KEY"],
  endpoint: ENV.fetch("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk")
)

begin
  process_job(job)
rescue => e
  Bugstack.capture_exception(e, metadata: { job: job.id })
  raise
end

Rails

One initializer loads the Rails integration, initializes Bugstack, and places its middleware inside Rails' own error pages. The gem's automatic placement sits outside them, where a production Rails app has already turned the exception into an error page, so nothing would be reported.

# config/initializers/bugstack.rb
require "bugstack/integrations/rails"

Bugstack.init(
  api_key: ENV["BUGSTACK_API_KEY"],
  endpoint: ENV.fetch("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk")
)

# Inside Rails' own error pages, so bugstack sees the error before they answer it:
Rails.application.config.middleware.insert_after(
  ActionDispatch::DebugExceptions,
  Bugstack::Integrations::RackMiddleware
)

Sinatra

The extension reports the error and re-raises it, so Sinatra's own handling still runs.

require "bugstack"
require "bugstack/integrations/sinatra"

Bugstack.init(
  api_key: ENV["BUGSTACK_API_KEY"],
  endpoint: ENV.fetch("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk")
)

class App < Sinatra::Base
  register Bugstack::Integrations::Sinatra
  # ... your routes
end

Plain Ruby

For workers, scripts or any other Ruby process, report errors where you handle them, as in Initialize above. The gem also has an at_exit hook (require "bugstack/integrations/generic", then Bugstack::Integrations::Generic.install!), but reports are sent from a background thread, so an exception that ends the process can exit before it is sent.

Configuration Reference

Every option is a keyword argument to Bugstack.init, or a setter in its block.

Option Type Default Description
api_key String — Required. Your project API key (starts bsk_).
endpoint String a placeholder address Where reports go. Set it to https://dashboard.bugstack.ai/api/ingest/sdk.
project_id String "" Explicit project identifier.
environment String "production" Environment name sent with each report.
enabled Boolean true Master switch for error capture.
debug Boolean false Log SDK activity to STDERR.
dry_run Boolean false Log errors instead of sending them.
deduplication_window Float 300.0 Seconds during which the same error is sent only once. Bugstack also folds repeats within 24 hours.
timeout Float 5.0 HTTP timeout in seconds.
max_retries Integer 3 Attempts per report, with backoff (1s, 2s).
ignored_errors Array [] Exception classes, or substrings of messages, not to report.
before_send Proc nil Change an event before it is sent, or return nil to drop it.
auto_fix Boolean false Sent with each report. What Bugstack does with a fix is set by the repository's autonomy level in Bugstack, not by this flag.

Data Control

before_send hook example

Drop errors from a health check:

Bugstack.init(
  api_key: ENV.fetch("BUGSTACK_API_KEY"),
  endpoint: "https://dashboard.bugstack.ai/api/ingest/sdk",
  # Drop errors from the health check; send everything else.
  before_send: ->(event) {
    event.request && event.request[:route] == "/health" ? nil : event
  },
)

dry_run mode

Test your setup without sending anything:

Bugstack.init(
  api_key: ENV.fetch("BUGSTACK_API_KEY"),
  endpoint: "https://dashboard.bugstack.ai/api/ingest/sdk",
  dry_run: true, # log each event instead of sending it
  debug: true,
)

Next Steps

Get started

Sign up with GitHub and start the 14-day trial, or book a demo and we set it up with you. Once the SDK is in, an uncaught server error starts a fix: specialist agents work out the cause and write a small change, it arrives as a pull request that runs through your CI, and what happens next depends on the autonomy level you set. Connecting the repository also starts repository scanning.

Get started Book a demo