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.