Back to Details

sentry-ruby-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sentry Ruby SDK

Sentry Ruby SDK

Opinionated wizard that scans the project and guides through complete Sentry setup.
这是一个指导性工具，会扫描项目并引导你完成完整的Sentry配置流程。

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 or Honeybadger 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.
  • 用户要求“在Ruby中添加Sentry”或在Ruby应用中“配置Sentry”
  • 用户需要为Ruby应用实现错误监控、链路追踪、日志、指标、性能分析或定时任务监控
  • 用户提及
    sentry-ruby
    、
    sentry-rails
    或Ruby版Sentry SDK
  • 用户需要从AppSignal或Honeybadger迁移至Sentry
  • 用户希望监控Rails/Sinatra中的异常、HTTP请求或后台任务
注意： 以下SDK API基于sentry-ruby v6.4.0版本。 实施前请务必对照docs.sentry.io/platforms/ruby/确认最新内容。

Phase 1: Detect

阶段1：项目检测

bash
undefined
bash
undefined

Existing Sentry gems

Existing Sentry gems

grep -i sentry Gemfile 2>/dev/null
grep -i sentry Gemfile 2>/dev/null

Framework

Framework

grep -E '"rails"|"sinatra"' Gemfile 2>/dev/null
grep -E '"rails"|"sinatra"' Gemfile 2>/dev/null

Background jobs

Background jobs

grep -E '"sidekiq"|"resque"|"delayed_job"' Gemfile 2>/dev/null
grep -E '"sidekiq"|"resque"|"delayed_job"' Gemfile 2>/dev/null

Competitor monitoring tools — triggers migration path if found

Competitor monitoring tools — triggers migration path if found

grep -E '"appsignal"|"honeybadger"' Gemfile 2>/dev/null
grep -E '"appsignal"|"honeybadger"' Gemfile 2>/dev/null

Existing metric patterns (StatsD, Datadog, Prometheus)

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
grep -rE "(statsd|dogstatsd|prometheus|.gauge|.histogram|.increment|.timing)"
app/ lib/ --include="*.rb" 2>/dev/null | grep -v "_spec|_test" | head -20

Companion frontend

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`) → load `references/migration.md` first; **delete the competitor initializer** (`config/initializers/honeybadger.rb` or `config/initializers/appsignal.rb`) 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

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

**根据检测结果选择对应流程：**
- **检测到竞品工具**（`appsignal`、`honeybadger`）→ 先加载`references/migration.md`；迁移过程中需**删除竞品的初始化文件**（`config/initializers/honeybadger.rb`或`config/initializers/appsignal.rb`）
- **已存在Sentry** → 直接跳至阶段2配置功能
- **Rails项目** → 使用`sentry-rails` + `config/initializers/sentry.rb`配置
- **Rack/Sinatra项目** → 使用`sentry-ruby` + `Sentry::Rack::CaptureExceptions`中间件
- **Sidekiq项目** → 添加`sentry-sidekiq`；若检测到现有指标工具，推荐配置Metrics功能

---

Phase 2: Recommend

阶段2：功能推荐

Lead with a concrete proposal — don't ask open-ended questions:
FeatureRecommend when...
Error MonitoringAlways
TracingRails / Sinatra / Rack / any HTTP framework
LoggingAlways — 
enable_logs: true
costs nothing
MetricsSidekiq present; existing metric lib (StatsD, Prometheus) detected
Profiling⚠️ Beta — performance profiling requested; requires 
stackprof
or 
vernier
gem
CronsScheduled jobs detected (ActiveJob, Sidekiq-Cron, Clockwork, Whenever)
Propose: "I recommend Error Monitoring + Tracing + Logging [+ Metrics if applicable]. Shall I proceed?"
直接给出具体方案，避免开放式问题：
功能推荐场景
错误监控所有场景必选
链路追踪Rails / Sinatra / Rack 或任何HTTP框架项目
日志采集所有场景必选 — 开启
enable_logs: true
无额外成本
指标监控存在Sidekiq的项目；检测到现有指标库（StatsD、Prometheus）的项目
性能分析⚠️ 测试功能 — 用户明确要求性能分析；需依赖
stackprof
或
vernier
gem
定时任务监控检测到定时任务（ActiveJob、Sidekiq-Cron、Clockwork、Whenever）的项目
推荐话术：“我建议配置错误监控 + 链路追踪 + 日志采集 [+ 指标监控（若适用）]。是否继续？”

Phase 3: Guide

阶段3：配置引导

Install

安装依赖

Rails:
ruby
undefined
Rails项目：
ruby
undefined

Gemfile

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:**
```ruby
gem "sentry-ruby"
Run 
bundle install
.
gem "sentry-ruby" gem "sentry-rails" gem "sentry-sidekiq" # 若使用Sidekiq gem "sentry-resque" # 若使用Resque gem "sentry-delayed_job" # 若使用DelayedJob

**Rack / Sinatra / 纯Ruby项目：**
```ruby
gem "sentry-ruby"
执行
bundle install
完成安装。

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

初始化 — Rails项目（
config/initializers/sentry.rb
）

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
end
sentry-rails
auto-instruments ActionController, ActiveRecord, ActiveJob, ActionMailer.
ruby
Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.spotlight = Rails.env.development?  # 本地Spotlight UI；开发环境无需DSN
  config.breadcrumbs_logger = [:active_support_logger, :http_logger]
  config.send_default_pii = true
  config.traces_sample_rate = 1.0  # 生产环境建议调低至0.05–0.2
  config.enable_logs = true
  # 指标监控默认开启；可通过以下配置关闭：config.enable_metrics = false
end
sentry-rails
会自动集成ActionController、ActiveRecord、ActiveJob、ActionMailer。

Init — Rack / Sinatra

初始化 — Rack / Sinatra项目

ruby
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
ruby
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  # 在config.ru中，置于应用中间件之前

Init — Sidekiq standalone

初始化 — 独立Sidekiq项目

ruby
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
ruby
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

环境变量配置

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

Feature reference files

功能参考文件

Load each reference when implementing the corresponding feature:
FeatureReferenceLoad when...
Migration
references/migration.md
Competitor gem found — load before installing Sentry
Error Monitoring
references/error-monitoring.md
Always
Tracing
references/tracing.md
HTTP handlers / distributed tracing
Logging
references/logging.md
Structured log capture
Metrics
references/metrics.md
Sidekiq present; existing metric patterns
Profiling
references/profiling.md
Performance profiling requested (beta)
Crons
references/crons.md
Scheduled jobs detected or requested
实现对应功能时加载对应的参考文件：
功能参考文件加载场景
迁移指南
references/migration.md
检测到竞品gem — 安装Sentry前加载
错误监控
references/error-monitoring.md
所有场景
链路追踪
references/tracing.md
HTTP处理 / 分布式追踪场景
日志采集
references/logging.md
结构化日志采集场景
指标监控
references/metrics.md
存在Sidekiq的项目；检测到现有指标工具的项目
性能分析
references/profiling.md
用户明确要求性能分析（测试功能）
定时任务监控
references/crons.md
检测到或用户要求定时任务监控的场景

Configuration Reference

配置参考

Key 
Sentry.init
Options

Sentry.init
核心配置项

OptionTypeDefaultPurpose
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
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
配置项类型默认值用途
dsn
字符串
nil
为空时SDK禁用；可通过环境变量
SENTRY_DSN
配置
environment
字符串
nil
例如
"production"
；可通过环境变量
SENTRY_ENVIRONMENT
配置
release
字符串
nil
例如
"myapp@1.0.0"
；可通过环境变量
SENTRY_RELEASE
配置
spotlight
布尔值
false
将事件发送至Spotlight本地服务（开发环境无需DSN）
send_default_pii
布尔值
false
包含IP地址和请求头信息
sample_rate
浮点数
1.0
错误事件采样率（0.0–1.0）
traces_sample_rate
浮点数
nil
事务采样率；
nil
表示禁用链路追踪
profiles_sample_rate
浮点数
nil
性能分析采样率（基于链路追踪采样率）；需依赖
stackprof
或
vernier
enable_logs
布尔值
false
开启Sentry结构化日志采集
enable_metrics
布尔值
true
开启自定义指标监控（默认开启）
breadcrumbs_logger
数组
[]
自动采集面包屑的日志器（参考日志采集文档）
max_breadcrumbs
整数
100
每个事件最多保留的面包屑数量
debug
布尔值
false
开启SDK详细日志输出至标准输出
before_send
Lambda
nil
发送前修改或丢弃错误事件
before_send_transaction
Lambda
nil
发送前修改或丢弃事务事件
before_send_log
Lambda
nil
发送前修改或丢弃日志事件

Environment Variables

环境变量映射

VariableMaps toPurpose
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.
环境变量对应配置项用途
SENTRY_DSN
dsn
数据源名称
SENTRY_RELEASE
release
应用版本（例如
my-app@1.0.0
）
SENTRY_ENVIRONMENT
environment
部署环境
Sentry.init
中的配置会覆盖环境变量。

Verification

验证配置

Local dev (no DSN needed) — Spotlight:
bash
npx @spotlightjs/spotlight          # browser UI at http://localhost:8969
本地开发环境（无需DSN）—— 使用Spotlight：
bash
npx @spotlightjs/spotlight          # 浏览器UI地址：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:**
```ruby
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>
.
npx @spotlightjs/spotlight tail traces --format json
`config.spotlight = Rails.env.development?`（已包含在上述初始化代码中）会自动将事件路由至本地服务。

**使用真实DSN验证：**
```ruby
Sentry.capture_message("Sentry Ruby SDK test")
无事件显示？设置
config.debug = true
并查看标准输出。验证DSN格式是否正确：
https://<key>@o<org>.ingest.sentry.io/<project>
。

Phase 4: Cross-Link

阶段4：跨端关联

bash
cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'
Frontend detectedSuggest
React / Next.js
sentry-react-setup
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".
bash
cat package.json frontend/package.json web/package.json 2>/dev/null | grep -E '"@sentry|"sentry-'
检测到前端框架推荐配置
React / Next.js
sentry-react-setup
Svelte / SvelteKit
sentry-svelte-sdk
Vue
@sentry/vue
— 参考文档docs.sentry.io/platforms/javascript/guides/vue/
如需实现Ruby后端与JS前端的链路追踪关联，请参考
references/tracing.md
→ “Frontend trace stitching”章节。

Troubleshooting

故障排查

IssueSolution
Events not appearing
config.debug = true
; verify DSN; ensure 
Sentry.init
before first request
Rails exceptions missingMust use 
sentry-rails
— 
sentry-ruby
alone doesn't hook Rails error handlers
No tracesSet 
traces_sample_rate > 0
; ensure 
sentry-rails
or 
Sentry::Rack::CaptureExceptions
Sidekiq jobs not tracedAdd 
sentry-sidekiq
gem
Missing request contextSet 
config.send_default_pii = true
Logs not appearingSet 
config.enable_logs = true
; sentry-ruby ≥ 5.24.0 required
Metrics not appearingCheck 
enable_metrics
is not 
false
; verify DSN
问题解决方案
事件未显示设置
config.debug = true
；验证DSN格式；确保
Sentry.init
在首次请求前执行
Rails异常未捕获必须使用
sentry-rails
— 单独使用
sentry-ruby
无法集成Rails错误处理器
无链路追踪数据设置
traces_sample_rate > 0
；确保使用
sentry-rails
或
Sentry::Rack::CaptureExceptions
Sidekiq任务无追踪数据添加
sentry-sidekiq
gem
请求上下文缺失设置
config.send_default_pii = true
日志未显示设置
config.enable_logs = true
；需使用sentry-ruby ≥ 5.24.0版本
指标数据未显示确认
enable_metrics
未设置为
false
；验证DSN格式