sentry-ruby-sdk

by sentry

Full Sentry SDK setup for Ruby. Use when asked to add Sentry to Ruby, install sentry-ruby, setup Sentry in Rails/Sinatra/Rack, or configure error monitoring,… npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-ruby-sdk Download ZIPGitHub19

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://[email protected]/ZZZ
SENTRY_ENVIRONMENT=production # overrides RAILS_ENV / RACK_ENV
[email protected]

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.

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".