オブザーバビリティ設計

設計原則

計測対象マップ

相関設計

トレース伝播ルール

標準属性（テレメトリ契約）

全コンポーネント・全シグナル共通。OTel の属性命名規約（dot 区切り小文字）に従う。

シグナル設計

トレース — 手動スパン

HTTP・DB・Redis は自動計装に任せ、ドメイン上意味のある操作だけ手動 span を切る。

メトリクスカタログ

HTTP の基本メトリクスは自動計装に任せ、ここではドメインメトリクスのみ定義する。接頭辞 interview.。

ログ

• 形式: 全サービス JSON 構造化ログ（1 行 1 イベント）。フィールドは標準属性＋ severity / message / trace_id / span_id（OTel ログブリッジで自動注入）。
• レベル運用: INFO = ドメインイベント（Room 作成・入退室・録画遷移・webhook 配信結果）、WARN = 自動回復した異常（リトライ成功・入室拒否）、ERROR = 要調査（provision 失敗・録画 failed・配信 exhausted）。
• アクセスログはインフラ層の標準機能に任せ、アプリでは重複して出さない。
• 本文の扱い: チャット・文字起こし・提示物の中身はログに載せない（P5）。長さ・件数のみ可。
• 監査との分界: 「誰が何をしたか」の証跡は RoomEvent（DB）が正本。ログは運用調査用で保持 30 日。監査要件をログ基盤に負わせない。

エラートラッキング（Sentry）

未捕捉例外・要調査エラーの追跡は Sentry に集約する。minedia-www は既に Sentry を「エラー 100% 送信・本番の performance tracing 無効」で運用しており、本設計の分界と矛盾しない。

• プロジェクト分割: interview-core / interview-transcriber / interview-agent を www と別プロジェクトにする（issue のオーナーシップとアラート経路の分離）。
• タグ契約: 標準属性（room.uuid / tenant.id など）を同名で Sentry タグに付与。「Sentry issue → room.uuid → ログ・トレース横断検索」が障害調査の 4 手に接続する。
• 依存の隔離: アプリコードから Sentry API を直接呼ばない。接点は「初期化 1 ファイル」＋「明示 capture 用ラッパー 1 枚」に限定し、将来の乗り換えコストを固定する。
• Grafana を単一画面にする: Grafana Labs 公式の Sentry データソースプラグイン（Issues / Events / Org Stats をクエリ可・v2.0.0+ で Events の取得フィールド選択可・要 Grafana 10.4+・認証は Sentry Internal Integration トークン）で、ダッシュボードに Sentry issue をトレース・メトリクスと並置できる。Sentry UI ⇔ Grafana を行き来せず、Grafana 起点で調査を完結させる方向とする。
• PII: sendDefaultPii: false を明示。リクエストボディのキャプチャは無効。

コンポーネント別実装方針

共通環境変数（送信先の差し替えはここだけ）

OTEL_SERVICE_NAME=interview-core            # サービスごとに変更
OTEL_RESOURCE_ATTRIBUTES="service.namespace=interview,deployment.environment=production"
OTEL_EXPORTER_OTLP_ENDPOINT=<OTLP エンドポイント>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <credentials>"

アラート

イベント駆動アラート

整合性監視（split-brain 対策）

webhook 欠落時に core と minedia-www の状態が乖離するリスクに対し、www 側に日次の突合ジョブ（ローカル参照 ⇔ core の Room 状態照合)を置き、乖離件数を interview.reconciliation.mismatches counter で出す。> 0 で P3 アラート。

バックエンドとコスト

バックエンド比較

エラートラッキングはいずれの案でも Sentry で確定（既存契約の増分利用）。バックエンドの最終決定はインフラ ADR と同時に行う。

コスト試算（Grafana Cloud Pro・月 200 インタビュー想定）

前提: 月 200 インタビュー・平均 6 参加者 × 60 分（= 1,200 参加者セッション/月）。

サンプリング・保持

• トレースは当面 100% 保持（parentbased_always_on）。1 セッションの障害調査価値が高く、量も問題にならない。head sampling は「稀な障害を落とす」ため採らない。
• 量が問題になったら tail sampling（エラー・遅延トレースは全量、正常系を絞る）へ移行。
• 保持期間: ログ 30 日 / メトリクス 13 ヶ月 / トレース 30 日。

セキュリティ・PII

段階導入プラン

計装は後付けにせず、core の最初のエンドポイントから標準属性の契約で書き始める（contract-first はテレメトリにも適用）。

ダッシュボード構成（Phase D で 2 枚）

未決事項