OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add getsentry/sentry-for-claude --skill sentry-ruby-sdk
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, tracing, logging, metrics, profiling, or crons for Ruby applications. Also handles migration from AppSignal, Honeybadger, Bugsnag, Rollbar, or Airbrake. Supports Rails, Sinatra, Rack, Sidekiq, and Resque.
This repo is now called getsentry/sentry-for-ai. Both names install the same content, but the install count here only covers this one.
npx skills add getsentry/sentry-for-claude --skill sentry-ruby-sdk
All Skills > SDK Setup > Ruby SDK
Opinionated wizard that scans the project and guides through complete Sentry setup.
sentry-ruby, sentry-rails, or the Ruby Sentry SDKNote: SDK APIs below reflect sentry-ruby v6.6.2. Always verify against docs.sentry.io/platforms/ruby/ before implementing.
Route from what you find:
appsignal, honeybadger, bugsnag, rollbar, airbrake) → load ${SKILL_ROOT}/references/migration.md first; delete the competitor initializer as part of migrationsentry-rails + config/initializers/sentry.rbsentry-ruby + Sentry::Rack::CaptureExceptions middlewaresentry-sidekiq; recommend Metrics if existing metric patterns foundsentry-yabeda; routes Yabeda metrics to Sentry metricsX-Request-Start header; see ${SKILL_ROOT}/references/tracing.md → "Request Queue Time"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 automaticallyLead 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 |
| Metrics | Sidekiq present; existing metric lib (StatsD, Prometheus) detected |
| Profiling | ⚠️ Beta — performance profiling requested; requires stackprof or vernier gem; skip if OTel tracing detected (requires traces_sample_rate, incompatible with OTLP) |
| Crons | Scheduled jobs detected (ActiveJob, Sidekiq-Cron, Clockwork, Whenever) |
OTel tracing detected: "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?"
No OTel: "I recommend Error Monitoring + Tracing + Logging [+ Metrics if applicable]. Shall I proceed?"
Rails:
Rack / Sinatra / plain Ruby:
Run bundle install.
| 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 |
| Yabeda metrics | sentry-yabeda | Sentry initializer | Yabeda metric events → Sentry metrics |
config/initializers/sentry.rb)sentry-rails auto-instruments ActionController, ActiveRecord, ActiveJob, ActionMailer.
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.
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+, Rails fixed in v6.4.1) |
otlp.enabled | Boolean | false | Route OTel spans to Sentry via OTLP; do not combine with traces_sample_rate |
otlp.collector_url | String | nil | OTLP HTTP endpoint of an OTel Collector (e.g., http://localhost:4318/v1/traces); when set, spans are sent to the collector instead of directly to Sentry |
org_id | String | nil | Explicit org ID; overrides DSN-extracted value; useful for self-hosted/Relay setups (v6.5.0+) |
strict_trace_continuation | Boolean | false | Only continue incoming traces when sentry-org_id baggage matches SDK's org ID; prevents trace stitching from third-party services (v6.5.0+) |
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 |
| 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.
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>.
| 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".
| 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 |
# 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
gem "sentry-yabeda" # if using Yabeda metrics frameworkgem "sentry-ruby"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
endrequire "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 middlewarerequire "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
endSENTRY_DSN=https://xxx@oYYY.ingest.sentry.io/ZZZ
SENTRY_ENVIRONMENT=production # overrides RAILS_ENV / RACK_ENV
SENTRY_RELEASE=my-app@1.0.0npx @spotlightjs/spotlight # browser UI at http://localhost:8969
# or stream events to terminal:
npx @spotlightjs/spotlight tail traces --format jsonSentry.capture_message("Sentry Ruby SDK test")cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'