Connect Ruby to Bugsink
When a Ruby application fails, Bugsink gives you the exception, stack trace, and application context you need to investigate it.
This guide covers the initial setup, other ways to capture errors, and the useful context you can attach to them. You’ll start by connecting an application and triggering a deliberate exception to confirm that it reaches Bugsink.
To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.
Install the SDK
Add the open-source Sentry Ruby SDK to your application’s bundle. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:
bundle add sentry-rubybundle add sentry-ruby
Configure your DSN
Initialize the SDK as early as possible in your application’s startup. Reading the DSN from the environment keeps it out of source control. The logger option also retains standard Ruby log records as breadcrumbs on a later error:
Sentry.init do |config| config.dsn = ENV.fetch("SENTRY_DSN") config.breadcrumbs_logger = [:sentry_logger] endSentry.init do |config| config.dsn = ENV.fetch("SENTRY_DSN") config.breadcrumbs_logger = [:sentry_logger] end
Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the
application:
export SENTRY_DSN=https://key@bugsink.example/1export SENTRY_DSN=https://key@bugsink.example/1
Send a test error
Capture a deliberate exception in a code path you can run. A standalone Ruby
process does not have a framework request handler to catch top-level errors,
so call capture_exception() before re-raising the exception normally:
begin raise RuntimeError, "Bugsink setup check" rescue RuntimeError => error Sentry.capture_exception(error) Sentry.close raise endbegin raise RuntimeError, "Bugsink setup check" rescue RuntimeError => error Sentry.capture_exception(error) Sentry.close raise end
Sentry.close waits for the background sender before this short-lived process
exits. Long-running web applications normally flush events in the background.
See the error in Bugsink
Open your Bugsink project. The new RuntimeError issue contains the Ruby stack
trace and points at the line that raised the exception.
RuntimeError
That’s it: your Ruby application is connected. Remove the deliberate exception. Capture failures where your application handles them, or use a framework integration to report unhandled request and job exceptions.
Capture other kinds of errors
The initial example captures and re-raises an exception. You can also report an exception your code handles or a noteworthy condition that does not have an exception.
Handled exceptions
Handled exceptions let your application recover while preserving the original
type and stack in Bugsink. Call capture_exception() in the rescue block after
deciding that the failure is worth reporting:
begin InventoryReport.quantity_for(sku) rescue ProductNotFound => error Sentry.capture_exception(error) endbegin InventoryReport.quantity_for(sku) rescue ProductNotFound => error Sentry.capture_exception(error) end
The command continues normally while Bugsink receives the exception.
Bugsink preview: handled exception
ProductNotFound
Messages without exceptions
A message creates a Bugsink event without an exception. Use capture_message()
for a condition such as a stale inventory feed, and set the level on a local
scope when it should differ from the default. Prefer an exception when a useful
stack exists:
Sentry.with_scope do |scope| scope.set_level(:warning) Sentry.capture_message("Inventory feed is stale") endSentry.with_scope do |scope| scope.set_level(:warning) Sentry.capture_message("Inventory feed is stale") end
warning Inventory feed is staleBugsink preview: captured message
Log Entry
Short-lived processes
Short-lived processes can finish before the SDK’s background sender does. Call
Sentry.close after the last event in a command, worker child, or one-off
script so pending events are delivered before the process exits:
# Flush pending events before this command exits. Sentry.close# Flush pending events before this command exits. Sentry.close
Framework servers normally stay alive and manage their own shutdown lifecycle, so request handlers should not close the shared SDK client.
Add useful context
An exception tells you what failed; context helps explain why. Use
Sentry.with_scope around one operation so its data is attached to that event
without leaking into later work in a long-running process.
Tags
Tags make events searchable by short key/value pairs. Bugsink already records
standard values such as environment and release; add your own component,
region, plan, or feature flag with set_tag():
scope.set_tag("component", "inventory")scope.set_tag("component", "inventory")
inventoryBugsink preview: component tag
Tags
Structured context
Structured context adds a named group of details you want to inspect but do
not need to search. set_context() creates a Checkout section containing the
SKU and requested quantity on the event:
scope.set_context("checkout", {sku: sku, quantity: 1})scope.set_context("checkout", {sku: sku, quantity: 1})
ruby-handled 1Bugsink preview: structured context
Contexts
CHECKOUT
Breadcrumbs
Breadcrumbs record what happened before an error without creating a separate issue. Add one for a domain step the SDK cannot observe itself, such as starting a reservation or retrying an external inventory service:
Sentry.add_breadcrumb( Sentry::Breadcrumb.new( category: "checkout", message: "Starting inventory reservation", level: "info" ) )Sentry.add_breadcrumb( Sentry::Breadcrumb.new( category: "checkout", message: "Starting inventory reservation", level: "info" ) )
Bugsink preview: breadcrumb
checkout
Starting inventory reservation
event time
logger
Looking up inventory for ruby-handled
event time
Log breadcrumbs
Log breadcrumbs preserve ordinary Ruby Logger calls before an error. With
breadcrumbs_logger enabled in the initializer, this informational record is
attached to the next event instead of creating a separate issue:
Logger.new($stdout).info("Looking up inventory for #{sku}")Logger.new($stdout).info("Looking up inventory for #{sku}")
Bugsink preview: log breadcrumb
checkout
Starting inventory reservation
event time
logger
Looking up inventory for ruby-handled
event time
Ruby web frameworks
Framework integrations capture unhandled request failures and add the relevant route, request, and application stack automatically.
