sentry-ruby-sdk

すべてのスキル > SDK のセットアップ > 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.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 を追加します。既存のメトリクスパターンが見つかった場合は、メトリクスを推奨します
• Yabeda を検出 → sentry-yabeda を追加します。Yabeda のメトリクスを Sentry のメトリクスに送ります
• 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 トレースに自動的に関連付けます

---

フェーズ 2：推奨

自由回答形式の質問はせず、具体的な提案から始めます。

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

OTel トレーシングを検出した場合： 「プロジェクトで OpenTelemetry トレーシングが使われているようです。既存の OTel セットアップ経由で Sentry の OTLP 統合を使ったトレーシングと、エラー監視、Sentry ログ記録を推奨します［該当する場合はメトリクス／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
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]

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

機能を一度に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 の詳細な出力を stdout に表示します
capture_queue_time	Boolean	true	X-Request-Start ヘッダーからリクエストのキュー時間を記録します（v6.4.0 以降。Rails では v6.4.1 で修正済み）
otlp.enabled	Boolean	false	OTLP 経由で OTel スパンを Sentry に送信します。traces_sample_rate と併用しないでください
otlp.collector_url	String	nil	OTel Collector の OTLP HTTP エンドポイント（例：http://localhost:4318/v1/traces）。設定すると、スパンは Sentry に直接送信されず、Collector に送信されます
org_id	String	nil	明示的な組織 ID。DSN から抽出された値を上書きします。セルフホスト／Relay の構成で便利です（v6.5.0 以降）
strict_trace_continuation	Boolean	false	受信したトレースの sentry-org_id baggage が SDK の組織 ID と一致する場合にのみ継続します。サードパーティサービスからのトレースの結合を防ぎます（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?（上記の初期化ブロックにすでに記述されています）を設定すると、イベントは自動的にローカルのサイドカーに送られます。

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