Connect Crystal to Bugsink

When a Crystal application fails, Bugsink gives you the exception, its Crystal stack trace, and the source around the failing line.

This guide uses raven.cr, a community-maintained open-source client released under the MIT licence. Bugsink accepts the event protocol it uses, so the client can send errors directly to your Bugsink project. You’ll add the shard, connect an application, and trigger a deliberate exception first.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Add Raven

Add raven to your shard.yml, then install the dependency with Shards:

dependencies:
  raven:
    github: Sija/raven.cr
    version: ~> 1.9.5
:::bash
shards install

Configure your DSN

Require Raven and initialize it near the start of the application. Raven reads SENTRY_DSN from the environment; setting the project root to the current directory lets it identify application frames and attach their source:

Raven.configure do |config|
  config.project_root = Dir.current
end

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export SENTRY_DSN=https://key@bugsink.example/1

raven.cr does not install a global unhandled-exception hook. Wrap your outermost application call with Raven.capture; it reports an exception and then re-raises it, preserving the normal failure and exit status:

Raven.capture do
  run_scenario(scenario)
end

Send a test error

Temporarily call a code path that raises an exception. This inventory example asks for a deliberately unknown product:

reserve_product("crystal-setup-check")

Build the application and run that path once:

shards build
bin/inventory setup-check

See the error in Bugsink

Open your Bugsink project. The new ProductNotFound issue contains the exception message and the Crystal source line where it was raised.

Bugsink preview: Crystal exception
Bugsink preview

That’s it: exceptions reaching the outer wrapper will now be reported to Bugsink and will still terminate the application normally.

Capture other kinds of errors

The outer wrapper handles failures that leave the application. You can also report exceptions your code recovers from, error-level log records, and exceptional conditions represented only by a message.

Handled exceptions

Handled exceptions do not reach the outer wrapper because your application rescued them. Pass the rescued exception to Raven.capture() when the failure should still be investigated; the call sends it without raising it again, so your recovery path remains in control:

Raven.capture(exception)

Bugsink preview: handled Crystal exception
Bugsink preview

Log records

Log records let existing Crystal Log calls report operational failures. Add Raven::LogBackend with capture_all: true at :error to turn error records into events; the record source becomes the logger name in Bugsink, while the IO backend continues to write locally:

Log.setup do |logging|
  logging.bind "*", :info, Log::IOBackend.new
  logging.bind "*", :info, Raven::LogBackend.new(record_breadcrumbs: true)
  logging.bind "*", :error, Raven::LogBackend.new(capture_all: true)
end
:::crystal
LOG.error { "Warehouse feed is unavailable" }

Bugsink preview: error log record
Bugsink preview

Messages without exceptions

Messages report an exceptional condition when there is no exception object to capture. Pass a string to Raven.capture() for a failed health check or an unresponsive queue. The message becomes an error event without an exception stack, so prefer a real exception when one naturally exists:

Raven.capture("Inventory queue is not responding")

Bugsink preview: captured message
Bugsink preview

Add useful context

An exception tells you what failed; context helps explain which part of the application and which operation were involved. Raven applies context within blocks, so related jobs can add useful values without leaking them into the next job.

Tags

Tags make events searchable by short key/value pairs. Bugsink already records standard values such as release; add your own component, region, plan, or feature flag when it helps separate otherwise similar failures. Every event captured inside this block receives component:inventory:

Raven.tags_context(component: "inventory") do

Bugsink preview: component tag
Bugsink preview

Additional data

Additional data records values you want to inspect but do not need to search. Use it for operation details such as an inventory SKU or warehouse; Raven adds the named values to every event captured inside the block, and Bugsink shows them in the event’s Extra section:

Raven.extra_context(sku: sku, warehouse: "eu-west") do

Bugsink preview: inventory data
Bugsink preview

Breadcrumbs record the steps leading up to an error without creating issues of their own. Add one for an application action Raven cannot infer, such as a reservation attempt or retry; the next event includes its category, message, level, and optional data:

Raven.breadcrumbs.record(
  category: "inventory",
  message: "Starting inventory reservation",
  level: :info,
  data: {sku: sku},
)

Bugsink preview: breadcrumb
Bugsink preview

Raven also reads SENTRY_RELEASE and SENTRY_ENVIRONMENT. Set a stable release for each build and a short environment such as production or staging; both values are then attached to every event and can be used while investigating a deployment-specific failure.

Limitations

raven.cr is community-maintained rather than a first-party Crystal SDK. It sends events through the older Sentry Store API, which Bugsink accepts, but it does not expose modern SDK features such as performance transactions, release health sessions, attachments, or the newer structured-logs protocol.

The setup above covers Raven’s core client. Raven also provides a separate crash handler and integrations for Kemal, Amber, Lucky, Sidekiq.cr, and action-controller. Those paths need their own setup and are not covered here.