sentry-ruby-sdk

Sentry Ruby SDK

一款立场鲜明的向导，可扫描项目并引导完成 Sentry 的完整设置。

在以下情况下调用此技能

• 用户要求“向 Ruby 添加 Sentry”或“在 Ruby 应用中设置 Sentry”
• 用户希望在 Ruby 中进行错误监控、追踪、日志记录、指标监控、性能分析或定时任务监控
• 用户提到 sentry-ruby、sentry-rails 或 Ruby Sentry SDK
• 用户正从 AppSignal、Honeybadger、Bugsnag、Rollbar 或 Airbrake 迁移到 Sentry
• 用户希望在 Rails/Sinatra 中监控异常、HTTP 请求或后台任务

**注意：**以下 SDK API 反映的是 sentry-ruby v6.4.0。 实施前请务必对照 docs.sentry.io/platforms/ruby/ 进行核实。

---

阶段 1：检测

# 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-'

根据检测结果选择方案：

• 检测到竞品（appsignal、honeybadger、bugsnag、rollbar、airbrake）→ 首先加载 ${SKILL_ROOT}/references/migration.md；迁移时删除竞品的初始化文件
• 已存在 Sentry → 跳到阶段 2 配置功能
• Rails → 使用 sentry-rails + config/initializers/sentry.rb
• Rack/Sinatra → 使用 sentry-ruby + Sentry::Rack::CaptureExceptions 中间件
• Sidekiq → 添加 sentry-sidekiq；如果发现现有指标模式，建议使用 Metrics
• 检测到 Puma → 队列时间捕获会自动启用（v6.4.0+），但反向代理必须设置 X-Request-Start 标头；参见 ${SKILL_ROOT}/references/tracing.md →“Request Queue Time”
• 检测到 OTel 追踪（Gemfile 中有 opentelemetry-sdk + instrumentations，或源码中有 OpenTelemetry::SDK.configure）→ 使用 OTLP 路径：config.otlp.enabled = true；不要设置 traces_sample_rate；Sentry 会自动将错误关联到 OTel 追踪
• 检测到 OTel 日志记录（Gemfile 中有 opentelemetry-logs-sdk，或源码中有 OpenTelemetry::Logs）→ 跳过 enable_logs；由 OTel 负责日志导出
• 存在 OTel 追踪但没有 OTel 日志记录（常见情况）→ 追踪使用 OTLP，日志记录使用 Sentry 原生的 enable_logs: true

---

阶段 2：推荐

先给出具体方案，不要提出开放式问题：

功能	推荐条件
错误监控	始终推荐
OTLP 集成	检测到 OTel 追踪时——替代原生追踪
追踪	Rails / Sinatra / Rack / 任何 HTTP 框架；检测到 OTel 追踪时跳过
日志记录	始终推荐——enable_logs: true 不会产生任何成本；仅在检测到 OTel 日志记录时跳过
指标监控	存在 Sidekiq；检测到现有指标库（StatsD、Prometheus）
性能分析	⚠️ Beta——用户要求进行性能分析时；需要 stackprof 或 vernier gem
定时任务	检测到计划任务（ActiveJob、Sidekiq-Cron、Clockwork、Whenever）

有 OTel 追踪，没有 OTel 日志记录（常见情况）：“我看到项目中使用了 OpenTelemetry 追踪。我建议使用 Sentry 的 OTLP 集成进行追踪（通过你现有的 OTel 设置）+ 错误监控 + Sentry 日志记录 [+ 适用时添加指标监控/定时任务]。我现在继续吗？”

有 OTel 追踪 + OTel 日志记录： “我看到 OpenTelemetry 同时负责追踪和日志记录。我建议使用 Sentry 的 OTLP 集成 + 错误监控 [+ 适用时添加指标监控/定时任务]。我现在继续吗？”

没有 OTel： “我建议使用错误监控 + 追踪 + 日志记录 [+ 适用时添加指标监控]。我现在继续吗？”

---

阶段 3：引导

安装

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 / 纯 Ruby：

gem "sentry-ruby"

运行 bundle install。

框架集成

框架 / 运行时	Gem	初始化位置	自动插桩
Rails	sentry-rails	config/initializers/sentry.rb	控制器、ActiveRecord、ActiveJob、ActionMailer
Rack / Sinatra	sentry-ruby	config.ru 顶部	请求（通过 Sentry::Rack::CaptureExceptions 中间件）
Sidekiq	sentry-sidekiq	Sentry 初始化程序或 Sidekiq 配置	Worker 执行 → 事务
Resque	sentry-resque	Sentry 初始化程序	Worker 执行 → 事务
DelayedJob	sentry-delayed_job	Sentry 初始化程序	Job 执行 → 事务

初始化 — 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 会自动对 ActionController、ActiveRecord、ActiveJob、ActionMailer 进行插桩。

初始化 — 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

初始化 — 独立运行的 Sidekiq

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

环境变量

SENTRY_DSN=https://[email protected]/ZZZ
SENTRY_ENVIRONMENT=production   # overrides RAILS_ENV / RACK_ENV
[email protected]

功能参考文件

逐项配置功能。每次加载相应的参考文件，按步骤操作，并在继续下一项之前进行验证：

功能	参考文件	加载时机……
迁移	${SKILL_ROOT}/references/migration.md	找到竞品 Gem 时——在安装 Sentry 之前加载
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终
追踪	${SKILL_ROOT}/references/tracing.md	HTTP 处理程序 / 分布式追踪
日志记录	${SKILL_ROOT}/references/logging.md	结构化日志采集
指标	${SKILL_ROOT}/references/metrics.md	存在 Sidekiq；有现有指标模式
性能分析	${SKILL_ROOT}/references/profiling.md	用户请求性能分析时（Beta 版）
定时任务	${SKILL_ROOT}/references/crons.md	检测到或请求配置定时任务时

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其正常运行。

---

配置参考

Sentry.init 的关键选项

选项	类型	默认值	用途
dsn	String	nil	为空时禁用 SDK；环境变量：SENTRY_DSN
environment	String	nil	例如 "production"；环境变量：SENTRY_ENVIRONMENT
release	String	nil	例如 "[email protected]"；环境变量：SENTRY_RELEASE
spotlight	Boolean	false	将事件发送到 Spotlight sidecar（本地开发，无需 DSN）
send_default_pii	Boolean	false	包含 IP 地址和请求标头
sample_rate	Float	1.0	错误事件采样率（0.0–1.0）
traces_sample_rate	Float	nil	事务采样率；nil 会禁用追踪
profiles_sample_rate	Float	nil	相对于 traces_sample_rate 的性能分析采样率；需要 stackprof 或 vernier
enable_logs	Boolean	false	启用 Sentry 结构化日志
enable_metrics	Boolean	true	启用自定义指标（默认开启）
breadcrumbs_logger	Array	[]	用于自动面包屑的日志记录器（参见日志参考）
max_breadcrumbs	Integer	100	每个事件的面包屑上限
debug	Boolean	false	将详细的 SDK 输出写入标准输出
capture_queue_time	Boolean	true	从 X-Request-Start 标头记录请求排队时间（v6.4.0+）
otlp.enabled	Boolean	false	通过 OTLP 将 OTel spans 路由到 Sentry；不要与 traces_sample_rate 一起使用
before_send	Lambda	nil	发送前修改或丢弃错误事件
before_send_transaction	Lambda	nil	发送前修改或丢弃事务事件
before_send_log	Lambda	nil	发送前修改或丢弃日志事件

环境变量

变量	对应选项	用途
SENTRY_DSN	dsn	数据源名称
SENTRY_RELEASE	release	应用版本（例如 [email protected]）
SENTRY_ENVIRONMENT	environment	部署环境

在 Sentry.init 中设置的选项优先于环境变量。

---

验证

本地开发（无需 DSN）— 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?（已在上方的初始化代码块中设置）会自动将事件路由到本地 sidecar。

使用真实 DSN：

Sentry.capture_message("Sentry Ruby SDK test")

没有任何内容显示？设置 config.debug = true 并检查标准输出。验证 DSN 格式：https://<key>@o<org>.ingest.sentry.io/<project>。

---

第 4 阶段：交叉链接

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

检测到的前端	建议
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue	@sentry/vue — docs.sentry.io/platforms/javascript/guides/vue/

如需了解 Ruby 后端与 JS 前端之间的链路拼接，请参阅 references/tracing.md →“前端链路拼接”。

---

故障排除

问题	解决方案
事件未显示	设置 config.debug = true；验证 DSN；确保在首次请求前调用 Sentry.init
Rails 异常缺失	必须使用 sentry-rails — 单独使用 sentry-ruby 不会挂接 Rails 错误处理程序
没有链路（原生）	设置 traces_sample_rate > 0；确保使用 sentry-rails 或 Sentry::Rack::CaptureExceptions
没有链路（OTLP）	验证已安装 opentelemetry-exporter-otlp gem；使用 otlp.enabled = true 时不要设置 traces_sample_rate
Sidekiq 作业未追踪	添加 sentry-sidekiq gem
缺少请求上下文	设置 config.send_default_pii = true
日志未显示	设置 config.enable_logs = true；需要 sentry-ruby ≥ 5.27.0
指标未显示	检查 enable_metrics 是否为 false；验证 DSN
关闭时事件丢失	Process.exit! 会跳过 at_exit 钩子 — 强制退出前显式调用 Sentry.flush
分叉服务器丢失事件	Puma/Unicorn 会分叉工作进程 — 在 on_worker_boot 或 after_fork 中重新初始化；否则，后台工作线程会在子进程中终止
DSN 被拒绝 / 事件未送达	验证 DSN 格式：https://<key>@o<org>.ingest.sentry.io/<project>；设置 config.debug = true 以查看传输错误