sentry-ruby-sdk

Sentry Ruby SDK

Opinionated wizard that scans the project and guides through complete Sentry setup.

Invoke This Skill When

• User asks to "add Sentry to Ruby" or "set up Sentry" in a Ruby app
• User wants error monitoring, tracing, logging, metrics, profiling, or crons in Ruby
• User mentions sentry-ruby, sentry-rails, or the Ruby Sentry SDK
• User is migrating from AppSignal, Honeybadger, Bugsnag, Rollbar, or Airbrake to Sentry
• User wants to monitor exceptions, HTTP requests, or background jobs in Rails/Sinatra

Note: SDK APIs below reflect sentry-ruby v6.4.0. Always verify against docs.sentry.io/platforms/ruby/ before implementing.

Phase 1: Detect

# Existing Sentry gems
grep -i sentry Gemfile 2>/dev/null
 
# Framework
grep -iE

Route from what you find:

• Competitor detected (appsignal, honeybadger, bugsnag, rollbar, airbrake) → load ${SKILL_ROOT}/references/migration.md first; delete the competitor initializer as part of migration
• Sentry already present → skip to Phase 2 to configure features
• Rails → use sentry-rails + config/initializers/sentry.rb
• Rack/Sinatra → sentry-ruby + Sentry::Rack::CaptureExceptions middleware
• Sidekiq → add sentry-sidekiq; recommend Metrics if existing metric patterns found
• Puma detected → queue time capture is automatic (v6.4.0+), but the reverse proxy must set X-Request-Start header; see ${SKILL_ROOT}/references/tracing.md → "Request Queue Time"
• OTel tracing detected (opentelemetry-sdk + instrumentations in Gemfile, or OpenTelemetry::SDK.configure in source) → use OTLP path: config.otlp.enabled = true; do not set traces_sample_rate; Sentry links errors to OTel traces automatically
• OTel logging detected (opentelemetry-logs-sdk in Gemfile, or OpenTelemetry::Logs in source) → skip enable_logs; OTel handles log export
• OTel tracing present but NOT logging (the common case) → use OTLP for tracing and Sentry native enable_logs: true for logging

Phase 2: Recommend

Lead with a concrete proposal — don't ask open-ended questions:

OTel tracing + no OTel logging (the common case): "I see OpenTelemetry tracing in the project. I recommend Sentry's OTLP integration for tracing (via your existing OTel setup) + Error Monitoring + Sentry Logging [+ Metrics/Crons if applicable]. Shall I proceed?"

OTel tracing + OTel logging: "I see OpenTelemetry handling both tracing and logging. I recommend Sentry's OTLP integration + Error Monitoring [+ Metrics/Crons if applicable]. Shall I proceed?"

No OTel: "I recommend Error Monitoring + Tracing + Logging [+ Metrics if applicable]. Shall I proceed?"

Phase 3: Guide

Install

Rails:

Rack / Sinatra / plain Ruby:

Run bundle install.

Framework Integration

Init — Rails (config/initializers/sentry.rb)

sentry-rails auto-instruments ActionController, ActiveRecord, ActiveJob, ActionMailer.

Init — Rack / Sinatra

Init — Sidekiq standalone

Environment variables

Feature reference files

Walk through features one at a time. Load the reference file for each, follow its steps, and verify before moving to the next:

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

Configuration Reference

Key Sentry.init Options

Environment Variables

Options set in Sentry.init override environment variables.

Verification

Local dev (no DSN needed) — Spotlight:

config.spotlight = Rails.env.development? (already in the init block above) routes events to the local sidecar automatically.

With a real DSN:

Nothing appears? Set config.debug = true and check stdout. Verify DSN format: https://<key>@o<org>.ingest.sentry.io/<project>.

Phase 4: Cross-Link

For trace stitching between Ruby backend and JS frontend, see references/tracing.md → "Frontend trace stitching".

Troubleshooting