sentry-ruby-setup

Sentry Ruby 设置

在 Ruby 项目中安装并配置 Sentry。

何时使用此技能

• 用户要求在 Ruby 应用中 "add Sentry to Ruby" 或 "install Sentry"
• 用户希望在 Ruby 中进行错误监控、日志记录或追踪
• 用户提到 "sentry-ruby" gem 或 Ruby on Rails

重要： 下面的配置选项和代码示例仅供参考。实施前请务必对照 docs.sentry.io 进行核实，因为 API 和默认值可能已发生变化。

要求

• Ruby 2.4+ 或较新的 JRuby 版本

安装

添加到 Gemfile：

gem "sentry-ruby"

# For profiling, add ONE of:
gem "stackprof"  # SDK 5.9.0+ — works on all Ruby versions
# gem "vernier"  # SDK 5.21.0+ — requires Ruby 3.2.1+, better for multi-threaded servers
                 # Also requires: config.profiler_class = Sentry::Vernier::Profiler

然后运行：

bundle install

配置

尽可能早地初始化：

require "sentry-ruby"

Sentry.init do |config|
  config.dsn = "YOUR_SENTRY_DSN"
  config.send_default_pii = true
  
  # Breadcrumbs from logs
  config.breadcrumbs_logger = [:sentry_logger, :http_logger]
  
  # Tracing
  config.traces_sample_rate = 1.0
  
  # Profiling (requires stackprof or vernier gem)
  config.profiles_sample_rate = 1.0
  # config.profiler_class = Sentry::Vernier::Profiler  # Uncomment if using vernier
  
  # Logs
  config.enable_logs = true
end

Rails 集成

对于 Rails，添加到 config/initializers/sentry.rb：

Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.send_default_pii = true
  config.breadcrumbs_logger = [:active_support_logger, :http_logger]
  config.traces_sample_rate = 1.0
  config.profiles_sample_rate = 1.0
  config.enable_logs = true
end

Rails 专用 Gem

# Gemfile
gem "sentry-ruby"
gem "sentry-rails"  # Rails integration
gem "sentry-sidekiq"  # If using Sidekiq
gem "sentry-delayed_job"  # If using Delayed Job
gem "sentry-resque"  # If using Resque

配置选项

选项	描述	默认值
dsn	Sentry DSN	nil（没有它 SDK 不执行任何操作）
send_default_pii	包含用户数据	false
traces_sample_rate	追踪的事务百分比	nil（追踪已禁用）
profiles_sample_rate	分析的追踪百分比	nil（分析已禁用）
enable_logs	将日志发送到 Sentry	false
environment	环境名称	"development"（依次检查 SENTRY_CURRENT_ENV、SENTRY_ENVIRONMENT、RAILS_ENV、RACK_ENV）
release	发布版本	自动检测

面包屑日志记录器

日志记录器	描述
:sentry_logger	Sentry 自有的日志记录器
:http_logger	HTTP 请求面包屑
:redis_logger	Redis 命令面包屑
:active_support_logger	Rails ActiveSupport（仅限 Rails）

环境变量

SENTRY_DSN=https://[email protected]/456
SENTRY_AUTH_TOKEN=sntrys_xxx
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project

验证

# Capture test message
Sentry.capture_message("Test message from Ruby")

# Or trigger intentional error
1 / 0

故障排除

问题	解决方案
错误未出现	确保尽早调用 Sentry.init，检查 DSN
没有追踪	将 traces_sample_rate 设置为 > 0
没有分析	添加 stackprof gem，设置 profiles_sample_rate
Rails 错误缺失	使用 sentry-rails gem 而不是 sentry-ruby