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.
- Installs
- 306
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-ruby-sdk- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads sentry-ruby-sdk automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.mdfirst; 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::CaptureExceptionsmiddleware - 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-Startheader; see${SKILL_ROOT}/references/tracing.md→ "Request Queue Time" - OTel tracing detected (
opentelemetry-sdk+ instrumentations in Gemfile, orOpenTelemetry::SDK.configurein source) → use OTLP path:config.otlp.enabled = true; do not settraces_sample_rate; Sentry links errors to OTel traces automatically - OTel logging detected (
opentelemetry-logs-sdkin Gemfile, orOpenTelemetry::Logsin source) → skipenable_logs; OTel handles log export - OTel tracing present but NOT logging (the common case) → use OTLP for tracing and Sentry native
enable_logs: truefor 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 |
FAQ
What does the sentry-ruby-sdk skill do?
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.
How do I install sentry-ruby-sdk?
Run npx skills add https://github.com/getsentry/sentry-agent-skills --skill sentry-ruby-sdk in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sentry-ruby-sdk/ (personal) or .claude/skills/sentry-ruby-sdk/ (project).
Which AI agents can use sentry-ruby-sdk?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is sentry-ruby-sdk safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains sentry-ruby-sdk?
It is published by getsentry in getsentry/sentry-agent-skills, and it is an official skill from the maker of the technology it covers. It has 306 recorded installs.
More from getsentry/sentry-agent-skills
sentry-fix-issues
getsentry/sentry-agent-skills
Find and fix issues from Sentry using MCP. Use when asked to fix Sentry errors, debug production issues, investigate exceptions, or resolve bugs reported in Sentry. Methodically analyzes stack traces, breadcrumbs, traces, and context to identify root causes.
sentry-react-setup
getsentry/sentry-agent-skills
Setup Sentry in React apps. Use when asked to add Sentry to React, install @sentry/react, or configure error monitoring, error boundaries, session replay, or browser tracing for React applications.
sentry-setup-ai-monitoring
getsentry/sentry-agent-skills
Setup Sentry AI Agent Monitoring in any project. Use when asked to monitor LLM calls, track AI agents, or instrument OpenAI/Anthropic/Vercel AI/LangChain/Google GenAI/Pydantic AI. Detects installed AI SDKs and configures appropriate integrations.
sentry-nextjs-sdk
getsentry/sentry-agent-skills
Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router.
sentry-pr-code-review
getsentry/sentry-agent-skills
Review a project's PRs to check for issues detected in code review by Seer Bug Prediction. Use when asked to review or fix issues identified by Sentry in PR comments, or to find recent PRs with Sentry feedback.
sentry-create-alert
getsentry/sentry-agent-skills
Create Sentry alerts using the workflow engine API. Use when asked to create alerts, set up notifications, configure issue priority alerts, or build workflow automations. Supports email, Slack, PagerDuty, Discord, and other notification actions.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.