sentry-ruby-sdk

所有技能 > SDK 设置 > Ruby SDK

Sentry Ruby SDK

一个有主见的向导，会扫描项目并指导你完成 Sentry 设置。

在以下情况调用此技能

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

注意： 以下 SDK API 适用于 sentry-ruby v6.6.2。 实施前请务必对照 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

# Yabeda metrics framework
grep -iE '\byabeda\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

# 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
• 检测到 Yabeda → 添加 sentry-yabeda；将 Yabeda 指标路由到 Sentry 指标
• 检测到 Puma → 队列时间采集是自动的（v6.4.0+），但反向代理必须设置 X-Request-Start 标头；参阅 ${SKILL_ROOT}/references/tracing.md → “请求队列时间”
• 检测到 OTel 追踪（Gemfile 中有 opentelemetry-sdk + 检测项，或源代码中有 OpenTelemetry::SDK.configure）→ 使用 OTLP 路径：config.otlp.enabled = true；不要设置 traces_sample_rate；Sentry 会自动将错误关联到 OTel 追踪

---

阶段 2：推荐

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

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

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

未检测到 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
gem "sentry-yabeda"       # if using Yabeda metrics framework

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 配置	工作进程执行 → 事务
Resque	sentry-resque	Sentry 初始化文件	工作进程执行 → 事务
DelayedJob	sentry-delayed_job	Sentry 初始化文件	任务执行 → 事务
Yabeda 指标	sentry-yabeda	Sentry 初始化文件	Yabeda 指标事件 → Sentry 指标

初始化 — 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	用户请求性能分析时（测试版）
定时任务	${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 输出写入 stdout
capture_queue_time	Boolean	true	根据 X-Request-Start 标头记录请求排队时间（v6.4.0+，Rails 于 v6.4.1 修复）
otlp.enabled	Boolean	false	通过 OTLP 将 OTel spans 路由到 Sentry；不要与 traces_sample_rate 同时使用
otlp.collector_url	String	nil	OTel Collector 的 OTLP HTTP 端点（例如，http://localhost:4318/v1/traces）；设置后，spans 会发送到 Collector，而不是直接发送到 Sentry
org_id	String	nil	显式指定组织 ID；覆盖从 DSN 提取的值；适用于可自托管 / Relay 配置（v6.5.0+）
strict_trace_continuation	Boolean	false	仅当传入 trace 的 sentry-org_id baggage 与 SDK 的组织 ID 相符时才继续；防止与第三方服务拼接 trace（v6.5.0+）
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 以查看传输错误