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 '\brails\b|\bsinatra\b' Gemfile 2>/dev/null

# Web server — Puma triggers queue time guidance
grep -iE '\bpuma\b' Gemfile 2>/dev/null

# Background jobs
grep -iE '\bsidekiq\b|\bresque\b|\bdelayed_job\b' Gemfile 2>/dev/null

# Competitor monitoring tools — triggers migration path if found
grep -iE '\bappsignal\b|\bhoneybadger\b|\bbugsnag\b|\brollbar\b|\bairbrake\b' Gemfile 2>/dev/null

# Scheduled jobs — triggers Crons recommendation
grep -iE '\bsidekiq-cron\b|\bclockwork\b|\bwhenever\b|\brufus-scheduler\b' Gemfile 2>/dev/null
grep -rn "Sidekiq::Cron\|Clockwork\|every.*do" config/ lib/ --include="*.rb" 2>/dev/null | head -10

# OpenTelemetry tracing — check for SDK + instrumentations
grep -iE '\bopentelemetry-sdk\b|\bopentelemetry-instrumentation\b' Gemfile 2>/dev/null
grep -rn "OpenTelemetry::SDK\.configure\|\.use_all\|\.in_span" config/ lib/ app/ --include="*.rb" 2>/dev/null | head -5

# OpenTelemetry logging — check for logs SDK (much less common in Ruby)
grep -iE '\bopentelemetry-logs-sdk\b|\bopentelemetry-logs-api\b' Gemfile 2>/dev/null
grep -rn "OpenTelemetry::Logs" config/ lib/ app/ --include="*.rb" 2>/dev/null | head -5

# Existing metric patterns (StatsD, Datadog, Prometheus)
grep -rE "(statsd|dogstatsd|prometheus|\.gauge|\.histogram|\.increment|\.timing)" \
  app/ lib/ --include="*.rb" 2>/dev/null | grep -v "_spec\|_test" | head -20

# Companion frontend
cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'

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:

Feature	Recommend when...
Error Monitoring	Always
OTLP Integration	OTel tracing detected — replaces native Tracing
Tracing	Rails / Sinatra / Rack / any HTTP framework; skip if OTel tracing detected
Logging	Always — enable_logs: true costs nothing; skip only if OTel logging detected
Metrics	Sidekiq present; existing metric lib (StatsD, Prometheus) detected
Profiling	⚠️ Beta — performance profiling requested; requires stackprof or vernier gem
Crons	Scheduled jobs detected (ActiveJob, Sidekiq-Cron, Clockwork, Whenever)

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:

# Gemfile
gem "sentry-ruby"
gem "sentry-rails"
gem "sentry-sidekiq"      # if using Sidekiq
gem "sentry-resque"       # if using Resque
gem "sentry-delayed_job"  # if using DelayedJob

Rack / Sinatra / plain Ruby:

gem "sentry-ruby"

Run bundle install.

Framework Integration

Framework / Runtime	Gem	Init location	Auto-instruments
Rails	sentry-rails	config/initializers/sentry.rb	Controllers, ActiveRecord, ActiveJob, ActionMailer
Rack / Sinatra	sentry-ruby	Top of config.ru	Requests (via Sentry::Rack::CaptureExceptions middleware)
Sidekiq	sentry-sidekiq	Sentry initializer or Sidekiq config	Worker execution → transactions
Resque	sentry-resque	Sentry initializer	Worker execution → transactions
DelayedJob	sentry-delayed_job	Sentry initializer	Job execution → transactions

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

Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.spotlight = Rails.env.development?  # local Spotlight UI; no DSN needed in dev
  config.breadcrumbs_logger = [:active_support_logger, :http_logger]
  config.send_default_pii = true
  config.traces_sample_rate = 1.0  # lower to 0.05–0.2 in production
  config.enable_logs = true
  # Metrics on by default; disable with: config.enable_metrics = false
end

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

Init — Rack / Sinatra

require "sentry-ruby"

Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.spotlight = ENV["RACK_ENV"] == "development"
  config.breadcrumbs_logger = [:sentry_logger, :http_logger]
  config.send_default_pii = true
  config.traces_sample_rate = 1.0
  config.enable_logs = true
end

use Sentry::Rack::CaptureExceptions  # in config.ru, before app middleware

Init — Sidekiq standalone

require "sentry-ruby"
require "sentry-sidekiq"

Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.spotlight = ENV.fetch("RAILS_ENV", "development") == "development"
  config.breadcrumbs_logger = [:sentry_logger]
  config.traces_sample_rate = 1.0
  config.enable_logs = true
end

Environment variables

SENTRY_DSN=https://xxx@oYYY.ingest.sentry.io/ZZZ
SENTRY_ENVIRONMENT=production   # overrides RAILS_ENV / RACK_ENV
SENTRY_RELEASE=my-app@1.0.0

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:

Feature	Reference file	Load when...
Migration	${SKILL_ROOT}/references/migration.md	Competitor gem found — load before installing Sentry
Error Monitoring	${SKILL_ROOT}/references/error-monitoring.md	Always
Tracing	${SKILL_ROOT}/references/tracing.md	HTTP handlers / distributed tracing
Logging	${SKILL_ROOT}/references/logging.md	Structured log capture
Metrics	${SKILL_ROOT}/references/metrics.md	Sidekiq present; existing metric patterns
Profiling	${SKILL_ROOT}/references/profiling.md	Performance profiling requested (beta)
Crons	${SKILL_ROOT}/references/crons.md	Scheduled jobs detected or requested

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

---

Configuration Reference

Key Sentry.init Options

Option	Type	Default	Purpose
dsn	String	nil	SDK disabled if empty; env: SENTRY_DSN
environment	String	nil	e.g., "production"; env: SENTRY_ENVIRONMENT
release	String	nil	e.g., "myapp@1.0.0"; env: SENTRY_RELEASE
spotlight	Boolean	false	Send events to Spotlight sidecar (local dev, no DSN needed)
send_default_pii	Boolean	false	Include IP addresses and request headers
sample_rate	Float	1.0	Error event sample rate (0.0–1.0)
traces_sample_rate	Float	nil	Transaction sample rate; nil disables tracing
profiles_sample_rate	Float	nil	Profiling rate relative to traces_sample_rate; requires stackprof or vernier
enable_logs	Boolean	false	Enable Sentry structured Logs
enable_metrics	Boolean	true	Enable custom metrics (on by default)
breadcrumbs_logger	Array	[]	Loggers for automatic breadcrumbs (see logging reference)
max_breadcrumbs	Integer	100	Max breadcrumbs per event
debug	Boolean	false	Verbose SDK output to stdout
capture_queue_time	Boolean	true	Record request queue time from X-Request-Start header (v6.4.0+)
otlp.enabled	Boolean	false	Route OTel spans to Sentry via OTLP; do not combine with traces_sample_rate
before_send	Lambda	nil	Mutate or drop error events before sending
before_send_transaction	Lambda	nil	Mutate or drop transaction events before sending
before_send_log	Lambda	nil	Mutate or drop log events before sending

Environment Variables

Variable	Maps to	Purpose
SENTRY_DSN	dsn	Data Source Name
SENTRY_RELEASE	release	App version (e.g., my-app@1.0.0)
SENTRY_ENVIRONMENT	environment	Deployment environment

Options set in Sentry.init override environment variables.

---

Verification

Local dev (no DSN needed) — Spotlight:

npx @spotlightjs/spotlight          # browser UI at http://localhost:8969
# or stream events to terminal:
npx @spotlightjs/spotlight tail traces --format json

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

With a real DSN:

Sentry.capture_message("Sentry Ruby SDK test")

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

---

Phase 4: Cross-Link

cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'

Frontend detected	Suggest
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue	@sentry/vue — docs.sentry.io/platforms/javascript/guides/vue/

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

---

Troubleshooting

Issue	Solution
Events not appearing	config.debug = true; verify DSN; ensure Sentry.init before first request
Rails exceptions missing	Must use sentry-rails — sentry-ruby alone doesn't hook Rails error handlers
No traces (native)	Set traces_sample_rate > 0; ensure sentry-rails or Sentry::Rack::CaptureExceptions
No traces (OTLP)	Verify opentelemetry-exporter-otlp gem is installed; do not set traces_sample_rate when using otlp.enabled = true
Sidekiq jobs not traced	Add sentry-sidekiq gem
Missing request context	Set config.send_default_pii = true
Logs not appearing	Set config.enable_logs = true; sentry-ruby ≥ 5.27.0 required
Metrics not appearing	Check enable_metrics is not false; verify DSN
Events lost on shutdown	Process.exit! skips at_exit hooks — call Sentry.flush explicitly before forced exits
Forking server loses events	Puma/Unicorn fork workers — re-initialize in on_worker_boot or after_fork; without this, the background worker thread dies in child processes
DSN rejected / events not delivered	Verify DSN format: https://<key>@o<org>.ingest.sentry.io/<project>; set config.debug = true to see transport errors