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 installdependencies: 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 endRaven.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/1export 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) endRaven.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")reserve_product("crystal-setup-check")
Build the application and run that path once:
shards build bin/inventory setup-checkshards 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
ProductNotFound
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)Raven.capture(exception)
ProductNotFound: Product crystal-handled is not in inventory normalized-uuid normalized-uuid None normalized-uuid event time event time event time N 127.0.0.1 ProductNotFound: Product crystal-handled is not in inventoryBugsink preview: handled Crystal exception
Key info
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" }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" }
error inventory Warehouse feed is unavailableBugsink preview: error log record
Log Entry
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")Raven.capture("Inventory queue is not responding")
error Inventory queue is not respondingBugsink preview: captured message
Log Entry
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") doRaven.tags_context(component: "inventory") do
inventoryBugsink preview: component tag
Tags
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") doRaven.extra_context(sku: sku, warehouse: "eu-west") do
crystal-handled eu-westBugsink preview: inventory data
Extra
Breadcrumbs
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}, )Raven.breadcrumbs.record( category: "inventory", message: "Starting inventory reservation", level: :info, data: {sku: sku}, )
Bugsink preview: breadcrumb
inventory
Starting inventory reservation
event time
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.
