snare-sdk

Ruby SDK for Snare — captures unhandled exceptions and manually-reported errors, batches them, and reports them to your Snare project.

Install

Not yet published to RubyGems. In this repo, add to a Gemfile:

gem "snare-sdk", path: "packages/sdk-ruby"

Usage

require "snare"

Snare.init(project_id: "proj_abc123", api_key: "snare_sdk_...", api_base: "https://intake.snare.dev")

begin
  risky_call
rescue => e
  Snare.capture_exception(e)
end
  • Snare.init(project_id:, api_key:, api_base: "https://intake.snare.dev") registers crash-capture handling and starts the batching queue. Safe to call more than once — each call re-initializes cleanly.
  • Snare.capture_exception(exception) reports an exception from your own rescue blocks. exception defaults to $!, so it can also be called bare from inside a live rescue block: rescue => e; Snare.capture_exception; end.
  • Snare.flush forces immediate delivery of whatever is currently queued — useful in a graceful-shutdown hook.

Events are batched and flushed after 5 events are queued, or 10 seconds after the oldest queued event, whichever comes first. Delivery is best-effort and silent: a dropped batch (network error, timeout, non-2xx response) never raises into your application.

Known limitation: background threads

Unhandled exceptions are captured via an at_exit hook that checks $!, the same approach Sentry's own Ruby SDK uses. This only catches exceptions that propagate all the way to the top of the main thread.

It will not automatically catch an exception that kills a background Thread — Ruby raises those silently by default (unless Thread.report_on_exception is set), and there's no clean, generic hook to intercept them. If you spawn background threads and want their exceptions reported, call Snare.capture_exception yourself inside a rescue in that thread's body.

Development

ruby packages/sdk-ruby/verify_capture.rb

runs the verify script — every line should print PASS.

Non-goals (v1)

Publishing to RubyGems; Rails-specific middleware/railtie integration; automatically capturing exceptions that kill background threads; console/log capture.