最終更新: 2026/07/07 02:50

ADR-0215 週次観測ログ

ADR-0215 (確定申告完了イベント連携方式 · 2026-07-06 受理) の Confirmation 6 KPI の観測結果を時系列で記録する。SQL 骨格 (BQ) と Cloud Monitoring metric の指定は本ファイル各節 · SSoT は ADR-0215 §9 Confirmation。実 SQL の実行は Phase 0 dogfood 開始 (vlt/terraform/ の Pub/Sub topic fiscal-year-close-confirmed + Cloud Tasks queue retention-downgrade + 2 Cloud Run service + outbox relay ジョブ shipping) 後に開始する。

Week 0 (2026-07-06 · Phase 0 dogfood 前 · 準備段階)

Phase 0 dogfood 未着手のため実測データなし。6 KPI の SQL 骨格 / Cloud Monitoring metric + SLO + 実施頻度 + 撤退条件連動を先出しで整理する。dogfood 開始時点で本節を Week 1 として実測数値に置き換える。

KPI 1: subscription lag (5 分間隔 · 目標 P95 < 300 秒)

  • SLO: P95 < 300 秒 (5 分)
  • 実施頻度: 5 分間隔 (Cloud Monitoring metric)
  • 撤退条件連動: P95 > 300 秒で Cloud Monitoring alert 発報 → SRE runbook 起動 · ADR-0215 §8-1 (Phase 0 で 4 KPI 逸脱 2 週間継続) の観測入力

Cloud Monitoring metric:

  • metric: pubsub.googleapis.com/subscription/oldest_unacked_message_age
  • subscription: retention-downgrader-sub (Cloud Run 2 service が pull する subscription · Phase 0 dogfood で実名を確定)
  • aggregator: percentile_95_ALIGNER · alignment_period=300s
  • alert threshold: > 300

BigQuery 二重観測 SQL 骨格 (発火単位の詳細分析用 · 発火ごと):

SELECT
  event_id,
  TIMESTAMP_DIFF(
    consumed_at,
    published_at,
    SECOND
  ) AS subscription_lag_sec
FROM `${project}.${dataset}.pubsub_subscription_log`
WHERE topic_name = 'fiscal-year-close-confirmed'
  AND event_id IN (
    SELECT event_id FROM `${project}.${dataset}.fiscal_year_close_events`
    WHERE dispatched_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  )
ORDER BY subscription_lag_sec DESC;
-- 期待値: P95 subscription_lag_sec < 300

KPI 2: Cloud Tasks DLQ 転送率 + 絶対件数 (発火ごと + 月次二重観測)

  • SLO: 発火単位 DLQ 転送 < 10 件 · 2 週間観測 < 1%
  • 実施頻度: 発火ごと + 月次
  • 撤退条件連動: 発火単位で 10 件超 or 2 週間観測で 1% 超のいずれかで即時 IntegrityGuard 発報 → runbook で再実行手順起動 (ADR-0215 §8-4 発火)

BigQuery SQL 骨格 (発火単位):

WITH per_event AS (
  SELECT
    event_id,
    COUNT(CASE WHEN dlq_dispatched_at IS NOT NULL THEN 1 END) AS dlq_count,
    COUNT(*) AS enqueue_count
  FROM `${project}.${dataset}.cloud_tasks_worker_log`
  WHERE queue_name = 'retention-downgrade'
    AND event_id IN (
      SELECT event_id FROM `${project}.${dataset}.fiscal_year_close_events`
      WHERE dispatched_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 14 DAY)
    )
  GROUP BY event_id
)
SELECT
  event_id,
  dlq_count,
  enqueue_count,
  SAFE_DIVIDE(dlq_count, enqueue_count) AS dlq_ratio
FROM per_event;
-- 期待値: MAX(dlq_count) < 10 (発火単位) · AVG(dlq_ratio) < 0.01 (2 週間観測)

KPI 3: 10 年仮残留数 (月次 · 目標 6 ヶ月以内に 0 収束)

  • SLO: 事業年度確定から 6 ヶ月以内に 0 収束 (ADR-0208 §Confirmation #6 と統合)
  • 実施頻度: 月次
  • 撤退条件連動: >0 件で発生源 UI の運用ログ調査 + fiscal_year_close_events 表との突合 + 手動 downgrade 実行

BigQuery SQL 骨格:

SELECT COUNT(*) AS ten_year_provisional_residual_count
FROM `${project}.${dataset}.receipts`
WHERE retention_class = '10yr'
  AND fiscal_year_close_confirmed_at IS NULL
  AND created_at < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 180 DAY);
-- 期待値: 0 (ADR-0217 KPI 2 と同 SQL · 統合観測)

補足: 本 SQL は ADR-0217 §9 KPI 2 と同一。両 ADR の Confirmation は統合観測されるため、docs/_internal/06_ops/adr-0217-observation-log.md KPI 2 の SQL 実行結果を参照する。

KPI 4: 確定申告完了から downgrade 完了までの latency (発火ごと · 目標 P95 < 24 時間)

  • SLO: P95 < 24 時間
  • 実施頻度: 発火ごと (Phase 0 で年 1 回 · Phase 1 で年 50 回)
  • 撤退条件連動: P95 > 24 時間で Cloud Tasks queue の rate limit / GCS API クォータの見直し (ADR-0215 §8-5 発火)

BigQuery SQL 骨格:

WITH per_event AS (
  SELECT
    fyc.event_id,
    fyc.confirmed_at,
    MAX(rbl.completed_at) AS last_downgrade_at
  FROM `${project}.${dataset}.fiscal_year_close_events` AS fyc
  LEFT JOIN `${project}.${dataset}.retention_downgrade_log` AS rbl
    ON rbl.event_id = fyc.event_id
  WHERE fyc.confirmed_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 90 DAY)
  GROUP BY fyc.event_id, fyc.confirmed_at
)
SELECT
  APPROX_QUANTILES(
    TIMESTAMP_DIFF(last_downgrade_at, confirmed_at, HOUR), 100
  )[OFFSET(95)] AS downgrade_latency_p95_hours
FROM per_event
WHERE last_downgrade_at IS NOT NULL;
-- 期待値: downgrade_latency_p95_hours < 24

KPI 5: dispatcher 途中クラッシュ検出 (15 分間隔 · 目標 常時 0 件)

  • SLO: 常時 0 件
  • 実施頻度: 15 分間隔 (BQ scheduled query)
  • 撤退条件連動: 1 件以上検出で IntegrityGuard 発報 → runbook で dispatcher 手動再実行 (Pub/Sub message の nack + 再配信起動 · ADR-0215 §8-3 / 盲点 #8 対応)

BigQuery SQL 骨格:

SELECT
  event_id,
  confirmed_at,
  dispatched_at,
  TIMESTAMP_DIFF(CURRENT_TIMESTAMP(), confirmed_at, MINUTE) AS elapsed_min
FROM `${project}.${dataset}.fiscal_year_close_events`
WHERE dispatched_at IS NULL
  AND confirmed_at < TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR);
-- 期待値: 0 行返却

KPI 6: outbox relay 遅延 (1 分間隔 · 目標 P95 < 5 分)

  • SLO: P95 < 5 分 (300 秒)
  • 実施頻度: 1 分間隔 (Cloud Monitoring alert · BQ 補完観測は週次)
  • 撤退条件連動: P95 > 5 分で Cloud Monitoring alert 発報 → outbox relay ジョブの再起動 or polling 間隔調整 (ADR-0215 §8-3 / 盲点 #4 対応)

Cloud Monitoring metric (推奨) + BigQuery 週次補完:

SELECT
  APPROX_QUANTILES(
    TIMESTAMP_DIFF(CURRENT_TIMESTAMP(), created_at, SECOND), 100
  )[OFFSET(95)] AS unpublished_age_p95_sec,
  COUNT(*) AS unpublished_count
FROM `${project}.${dataset}.pubsub_outbox`
WHERE published_at IS NULL
  AND created_at < CURRENT_TIMESTAMP();
-- 期待値: unpublished_age_p95_sec < 300 · unpublished_count は情報値 (SLO は age P95 側)

補足: 本 SQL は「未 publish の outbox 行のみを対象」に P95 age を測る。ADR-0217 KPI 3 (published_at があるレコードの TIMESTAMP_DIFF(published_at, created_at) の P95) とは対象母集団が異なる (relay 遅延 vs 発生済み relay lag)。両者を併記して観測する。

Phase 0 dogfood 開始時の確定タスク

Phase 0 dogfood 開始 (vlt/terraform/ shipping · Pub/Sub topic + Cloud Tasks queue + Cloud Run 2 service + outbox relay ジョブ 稼働) の時点で以下を確定する:

  1. table 名 / subscription 名の確定: ${project} / ${dataset} / subscription 名 (retention-downgrader-sub) の実値を SQL 骨格に埋め込む
  2. Cloud Monitoring alert 設定: KPI 1 (subscription lag P95) と KPI 6 (outbox relay 遅延 P95) を Cloud Monitoring 側で alert 化 · SRE runbook 連携
  3. BQ scheduled query 登録: KPI 2 (発火ごと + 月次) · KPI 3/4 (月次 or 発火ごと) · KPI 5 (15 分間隔) · KPI 6 (週次補完)
  4. integration test 整備: dispatcher 途中クラッシュ / GCS API 連続失敗 / Cloud SQL unique constraint 同時衝突の 3 シナリオを .github/workflows/integration-test-retention-downgrade.yml (新設 · ADR-0215 §11 実装配線) で実施 (Phase 1 GA 受入条件 · 盲点 #12)
  5. 本ページ Week 1 更新: dogfood 1 週間後に本節を Week 1 として実測値へ置き換え

関連 SSoT

  • ADR-0215 (確定申告完了イベント連携方式): docs/adr/0215-decide-tax-filing-event-integration.md (§9 Confirmation が本 SQL 骨格の SSoT)
  • 親決定 ADR-0208 (保存年限管理と期限後廃棄): docs/adr/0208-*.md (Confirmation #6 と KPI 3 で統合)
  • amend ADR-0217 (fiscal-year-close 関連 schema 3 点追加): docs/adr/0217-*.md (KPI 3 = ADR-0217 KPI 2 と同 SQL · 統合観測)
  • 実装 SSoT: vlt/terraform/ (Phase 0 dogfood shipping 後) + vlt/src/db/schema.sql (ADR-0217 PR-4 実装)
  • 観測手順 pattern の先例: docs/_internal/06_ops/adr-0212-observation-log.md (drp domain · 週次観測ログ)