ADR-005: Sentry + OpenTelemetry ハイブリッドによるエンドツーエンドトレーサビリティ
- ステータス: Accepted
- 日付: 2026-02-24
- 決定者: アーキテクトチーム
コンテキスト
TASHIKA はユーザー操作からバックエンド処理までのエンドツーエンドトレーサビリティを必要としている。具体的には:
- フロントエンドエラーをバックエンドの分散トレースと相関付けする必要がある
- エラー発生時にユーザーが TraceId をサポートに報告できる仕組みが必要である
- → QA-003 可観測性 が4つの可観測性の柱（ログ、メトリクス、トレース、フロントエンドエラー）を定義している
- システムはマイナンバー等の機密データを扱うため、エラー情報の開示範囲を慎重に制御する必要がある
- 障害発生時 5分以内 に根本原因（RCA）の特定に着手できる体制を構築する必要がある（→ QA-003）
決定
ハイブリッドアプローチを採用する:
- Sentry: フロントエンドエラー追跡（Error Boundary 統合、eventId、Session Replay）
- OpenTelemetry W3C Trace Context: フロントエンド → バックエンド間のトレース相関（
traceparentヘッダー伝播） - OpenTelemetry → Google Cloud Trace: バックエンドの分散トレーシング（OTLP エクスポート）
理由
- Sentry は最も成熟した React Error Boundary 統合を提供する:
eventIdをフォールバック UI に直接表示でき、Session Replay によりエラー発生時のユーザー操作を再現可能 - W3C
traceparentは分散トレース伝播の業界標準: ベンダーロックインを回避し、将来のツール変更に対応可能 - OpenTelemetry Browser SDK 2.0 のコアトレーシングは安定版だが、ブラウザ自動計装はまだ Experimental ステータス: Error Boundary + eventId の統合を自前で構築するコストは高い
- Google Cloud Trace は OTLP ネイティブサポート（2025年 GA）: TASHIKA の GCP インフラと自然に統合できる
- ASP.NET Core は Activity / W3C Trace Context を組み込みサポート: バックエンド側の追加ライブラリが最小限
- Sentry Free tier（5,000 イベント/月）は MVP に十分: 初期コストを抑えつつ、必要に応じて Team tier（$26/月）にアップグレード可能
- 将来の移行パス: Sentry → GlitchTip（OSS Sentry 互換）への移行は DSN 変更のみで実現可能
却下した代替案
| 代替案 | 却下理由 |
|---|---|
| OpenTelemetry Browser SDK のみ | ブラウザ自動計装が Experimental ステータス。ErrorBoundary + eventId 統合には大量のカスタム実装が必要 |
| Datadog RUM + APM | 高コスト（$1.50+/1,000 セッション）。ベンダーロックイン。初期規模にはオーバースペック |
| New Relic Browser | Datadog と同様のコスト・ベンダーロックイン懸念。React 固有のツーリングが Sentry より弱い |
| カスタムエラー追跡（SaaS なし） | 実装コストが高い。Session Replay をゼロから構築する必要がある。車輪の再発明 |
| Sentry 単体（OTel traceparent なし） | Sentry 独自の sentry-trace ヘッダーによるベンダーロックインが発生。W3C traceparent による相互運用性を確保すべき |
トレードオフ・リスク
- Sentry SaaS 依存（MVP 時点）: GlitchTip（OSS Sentry 互換、DSN 変更のみで移行可能）というエスケープハッチが存在する
- 2つのトレーシングシステムの運用（Sentry + OTel）: 各領域で最良のツールを使うための複雑性コストとして受容する
- Sentry Free tier のイベント上限: 本番環境でイベント数が 5,000/月を超える場合、Team tier（$26/月）へのアップグレードが必要
- Session Replay による DOM キャプチャ: マイナンバー入力フィールドは Sentry SDK の
mask設定とカスタム属性 (data-sentry-mask) で必ずマスキングする。beforeSendフックでマイナンバーパターン（12桁数字）のスクラビングを実施する
結果
docs/design/error-handling/にエラーハンドリング・トレーサビリティの実装仕様を記載- フロントエンド依存パッケージに
@sentry/reactおよび@opentelemetry/instrumentation-fetchを追加 - バックエンドに
TraceIdResponseMiddlewareを ASP.NET Core パイプラインに追加し、全レスポンスにX-Trace-Idヘッダーを付与 - CORS 設定に
Access-Control-Expose-Headers: X-Trace-Idを追加し、フロントエンドからヘッダーを参照可能にする - Sentry データスクラビング:
beforeSendフックでマイナンバーパターンをストリップ。Session Replay のmask設定でマイナンバー入力フィールドをマスキング error-handling/frontend-handling.mdの Error Boundary セクションから本 ADR を参照