All Skills > SDK Setup > Ruby SDK

Sentry Ruby SDK

プロジェクトをスキャンして、Sentry の完全セットアップをガイドする意見型ウィザード。

このスキルを使う場合

• ユーザーが Ruby アプリに「Sentry を追加する」または「Sentry をセットアップする」と言う
• ユーザーが Ruby でエラー監視、トレーシング、ログ記録、メトリクス、プロファイリング、または crons が必要
• ユーザーが sentry-ruby、sentry-rails、または Ruby Sentry SDK について述べる
• ユーザーが AppSignal、Honeybadger、Bugsnag、Rollbar、または Airbrake から Sentry へ移行している
• ユーザーが Rails/Sinatra で例外、HTTP リクエスト、またはバックグラウンドジョブを監視したい

注記: 下記の SDK API は sentry-ruby v6.4.1 を反映しています。 実装する前に、必ず docs.sentry.io/platforms/ruby/ で確認してください。

---

Phase 1: 検出

# 既存の Sentry gems
grep -i sentry Gemfile 2>/dev/null

# フレームワーク
grep -iE '\brails\b|\bsinatra\b' Gemfile 2>/dev/null

# Web サーバー — Puma はキュータイムガイダンスをトリガー
grep -iE '\bpuma\b' Gemfile 2>/dev/null

# バックグラウンドジョブ
grep -iE '\bsidekiq\b|\bresque\b|\bdelayed_job\b' Gemfile 2>/dev/null

# Yabeda メトリクスフレームワーク
grep -iE '\byabeda\b' Gemfile 2>/dev/null

# 競合監視ツール — 見つかった場合、移行パスをトリガー
grep -iE '\bappsignal\b|\bhoneybadger\b|\bbugsnag\b|\brollbar\b|\bairbrake\b' Gemfile 2>/dev/null

# スケジュールされたジョブ — Crons 推奨をトリガー
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 トレーシング — 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

# 既存メトリクスパターン (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

# フロントエンドの同類ツール
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 が既に存在 → Phase 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 + instrumentations または OpenTelemetry::SDK.configure がソースにある) → OTLP パスを使用：config.otlp.enabled = true；traces_sample_rate を設定しない；Sentry はエラーを OTel トレースに自動的にリンク

---

Phase 2: 推奨

具体的な提案で始める — オープンエンドの質問をしない：

フィーチャー	推奨する場合...
エラー監視	常に
OTLP インテグレーション	OTel トレーシング検出 — ネイティブトレーシングに置き換え
トレーシング	Rails / Sinatra / Rack / その他の HTTP フレームワーク；OTel トレーシング検出時はスキップ
ログ記録	常に — enable_logs: true はコストなし
メトリクス	Sidekiq が存在；既存メトリクスライブラリ (StatsD, Prometheus) 検出
プロファイリング	⚠️ Beta — パフォーマンスプロファイリング要求時；stackprof または vernier gem が必要；OTel トレーシング検出時はスキップ (traces_sample_rate 必要、OTLP と互換性なし)
Crons	スケジュールされたジョブ検出 (ActiveJob, Sidekiq-Cron, Clockwork, Whenever)

OTel トレーシング検出: "プロジェクトで OpenTelemetry トレーシングを検出しました。Sentry の OTLP インテグレーション (既存 OTel セットアップ経由) + エラー監視 + Sentry ログ記録 [+ 該当する場合はメトリクス/Crons] を推奨します。進めますか？"

OTel なし: "エラー監視 + トレーシング + ログ記録 [+ 該当する場合はメトリクス] を推奨します。進めますか？"

---

Phase 3: ガイド

インストール

Rails:

# Gemfile
gem "sentry-ruby"
gem "sentry-rails"
gem "sentry-sidekiq"      # Sidekiq を使用している場合
gem "sentry-resque"       # Resque を使用している場合
gem "sentry-delayed_job"  # DelayedJob を使用している場合
gem "sentry-yabeda"       # Yabeda メトリクスフレームワークを使用している場合

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 の先頭	リクエスト (via 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?  # ローカル Spotlight UI；dev では DSN 不要
  config.breadcrumbs_logger = [:active_support_logger, :http_logger]
  config.send_default_pii = true
  config.traces_sample_rate = 1.0  # 本番では 0.05–0.2 に低下
  config.enable_logs = true
  # メトリクスはデフォルトで有効；無効化: 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  # config.ru で、アプリミドルウェアの前

初期化 — 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://xxx@oYYY.ingest.sentry.io/ZZZ
SENTRY_ENVIRONMENT=production   # RAILS_ENV / RACK_ENV をオーバーライド
SENTRY_RELEASE=my-app@1.0.0

フィーチャーリファレンスファイル

一度に 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	パフォーマンスプロファイリング要求 (beta)
Crons	${SKILL_ROOT}/references/crons.md	スケジュールされたジョブ検出または要求

各フィーチャーについて：${SKILL_ROOT}/references/<feature>.md を読み、ステップに正確に従い、動作を検証します。

---

設定リファレンス

キー Sentry.init オプション

オプション	型	デフォルト	目的
dsn	String	nil	空の場合 SDK は無効；環境変数：SENTRY_DSN
environment	String	nil	例："production"；環境変数：SENTRY_ENVIRONMENT
release	String	nil	例："myapp@1.0.0"；環境変数：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 gem が必要
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	OTel スパンを Sentry へ OTLP 経由でルーティング；traces_sample_rate と併用しない
otlp.collector_url	String	nil	OTel Collector の OTLP HTTP エンドポイント (例：http://localhost:4318/v1/traces)；設定時、スパンはコレクターへ送信され、Sentry へ直接送信されません
org_id	String	nil	明示的な org ID；DSN 抽出値をオーバーライド；セルフホスト/Relay セットアップに有用 (v6.5.0+)
strict_trace_continuation	Boolean	false	sentry-org_id baggage が SDK の org ID と一致する場合のみ着信トレース継続；サードパーティサービスからのトレースステッチングを防止 (v6.5.0+)
before_send	Lambda	nil	エラーイベント送信前にミューテートまたはドロップ
before_send_transaction	Lambda	nil	トランザクションイベント送信前にミューテートまたはドロップ
before_send_log	Lambda	nil	ログイベント送信前にミューテートまたはドロップ

環境変数

変数	マップ先	目的
SENTRY_DSN	dsn	データソース名
SENTRY_RELEASE	release	アプリバージョン (例：my-app@1.0.0)
SENTRY_ENVIRONMENT	environment	デプロイメント環境

Sentry.init で設定されたオプションは環境変数をオーバーライドします。

---

検証

ローカル開発 (DSN 不要) — Spotlight:

npx @spotlightjs/spotlight          # ブラウザ UI は http://localhost:8969
# または、トレースをターミナルにストリーム：
npx @spotlightjs/spotlight tail traces --format json

config.spotlight = Rails.env.development? (上記イニシャライザブロックに既に含まれる) は、イベントをローカルサイドカーへ自動的にルーティングします。

実際の DSN の場合:

Sentry.capture_message("Sentry Ruby SDK test")

何も表示されません？ config.debug = true に設定し、stdout を確認してください。DSN 形式を検証してください：https://<key>@o<org>.ingest.sentry.io/<project>。

---

Phase 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 → "Frontend trace stitching" を参照してください。

---

トラブルシューティング

問題	解決策
イベントが表示されない	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 に設定してトランスポートエラーを確認