sentry-ruby-sdk

Sentry Ruby SDK

プロジェクトをスキャンし、Sentry のセットアップを完了できるように案内する、意見を反映したウィザードです。

このスキルを呼び出すタイミング

• ユーザーが Ruby アプリに「Sentry を追加」または「Sentry をセットアップ」したい場合
• ユーザーが Ruby でエラー監視、トレーシング、ログ記録、メトリクス、プロファイリング、または cron を利用したい場合
• ユーザーが 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 とインストルメンテーションがある、またはソースに OpenTelemetry::SDK.configure がある）→ OTLP パスを使用します：config.otlp.enabled = true。traces_sample_rate は設定しないでください。Sentry はエラーを OTel トレースに自動的に関連付けます
• OTel ログ記録を検出（Gemfile に opentelemetry-logs-sdk がある、またはソースに OpenTelemetry::Logs がある）→ enable_logs は省略します。ログのエクスポートは OTel が処理します
• OTel トレーシングはあるが、ログ記録はない（一般的なケース）→ トレーシングには OTLP を、ログ記録には Sentry ネイティブの enable_logs: true を使用します

---

フェーズ 2：推奨

自由回答式の質問をするのではなく、具体的な提案から始めます。

機能	次の場合に推奨...
エラー監視	常に
OTLP 統合	OTel トレーシングが検出された場合 — ネイティブのトレーシングを置き換えます
トレーシング	Rails / Sinatra / Rack / あらゆる HTTP フレームワーク。OTel トレーシングが検出された場合は省略します
ログ記録	常に — enable_logs: true のコストはかかりません。OTel ログ記録が検出された場合にのみ省略します
メトリクス	Sidekiq が存在する場合、既存のメトリクスライブラリ（StatsD、Prometheus）が検出された場合
プロファイリング	⚠️ ベータ版 — パフォーマンスのプロファイリングが求められる場合。stackprof または vernier gem が必要です
cron	スケジュールされたジョブが検出された場合（ActiveJob、Sidekiq-Cron、Clockwork、Whenever）

OTel トレーシングあり、OTel ログ記録なし（一般的なケース）：「プロジェクトで OpenTelemetry のトレーシングが使われているようです。トレーシングには（既存の OTel セットアップを利用する）Sentry の OTLP 統合を、さらにエラー監視と Sentry のログ記録をおすすめします［該当する場合はメトリクス／cron も追加します］。進めてもよろしいですか？」

OTel トレーシングと OTel ログ記録あり： 「トレーシングとログ記録の両方を OpenTelemetry が処理しているようです。Sentry の OTLP 統合とエラー監視をおすすめします［該当する場合はメトリクス／cron も追加します］。進めてもよろしいですか？」

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 / plain 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 のイニシャライザー	ジョブの実行 → トランザクション

初期化 — 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]

機能のリファレンスファイル

機能を一度に1つずつ確認します。各機能のリファレンスファイルを読み込み、手順に従って、次の機能に進む前に動作を確認してください。

機能	リファレンスファイル	読み込むタイミング
移行	${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	パフォーマンスプロファイリングを要求された場合（ベータ）
Cron	${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 サイドカーにイベントを送信します（ローカル開発では 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 スパンを 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?（上記の初期化ブロックにすでに記述されています）を設定すると、イベントは自動的にローカルのサイドカーに送られます。

実際の 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 を設定してください