最終更新: 2026/07/07 00:20

ADR-0217 週次観測ログ

ADR-0217 (ADR-0203 amend · 確定申告完了関連 schema 3 点追加 · 2026-07-06 受理) の Confirmation 5 KPI の観測結果を時系列で記録する。SQL 骨格は本ファイル各節 · SSoT は ADR-0217 §9 Confirmation。実 SQL の実行は PR-4 実装 (ADR-0203 amend の receipts.fiscal_year_close_confirmed_at 列 + pubsub_outbox 表 + fiscal_year_close_events 表の schema 追加) 完了後に開始する。

Week 0 (2026-07-06 · PR-4 実装前 · 準備段階)

PR-4 (vlt/src/db/schema.sql の追加 migration) 未着手のため実測データなし。5 KPI の SQL 骨格 + SLO + 実施頻度 + 撤退条件連動を先出しで整理する。PR-4 merge 完了時点で本節を Week 1 として実測数値に置き換える。

KPI 1: fiscal_year_close_events UNIQUE 制約 rollback = 0 件/月 (月次)

  • SLO: 月次 0 件
  • 実施頻度: 月次 (BQ scheduled query)
  • 撤退条件連動: >0 件で冪等キー定義バグ調査 (INSERT ... ON CONFLICT DO NOTHING の実装確認) + ADR-0215 §8-3 連動

BigQuery SQL 骨格 (Cloud SQL error log stream):

SELECT COUNT(*) AS unique_violation_count
FROM `${project}.${dataset}.cloud_sql_errors`
WHERE constraint_name = 'fiscal_year_close_events_idempotent_key'
  AND error_code = '23505'  -- Postgres unique_violation
  AND emitted_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY);
-- 期待値: 0

KPI 2: receipts.fiscal_year_close_confirmed_at 6 ヶ月経過後 NULL 残数 = 0 件 (月次)

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

BigQuery SQL 骨格:

SELECT COUNT(*) AS fiscal_year_close_null_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
-- retention_class = '10yr' 限定の意味論は ADR-0217 §3.2 §3.3 参照

KPI 3: pubsub_outbox relay lag P95 < 300 秒 (週次)

  • SLO: P95 < 300 秒
  • 実施頻度: 週次 (BQ scheduled query)
  • 撤退条件連動: P95 > 300 秒で relay ジョブ parallelism 引き上げ + Cloud Tasks queue の rate_limits 見直し (ADR-0215 §Confirmation #1 と統合)

BigQuery SQL 骨格:

SELECT
  APPROX_QUANTILES(
    TIMESTAMP_DIFF(published_at, created_at, SECOND), 100
  )[OFFSET(95)] AS relay_lag_p95_sec,
  COUNT(*) AS relayed_message_count
FROM `${project}.${dataset}.pubsub_outbox`
WHERE published_at IS NOT NULL
  AND published_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY);
-- 期待値: relay_lag_p95_sec < 300

KPI 4: schema 追加 migration 停止時間 < 60 秒 (PR merge 前 staging + 本番 merge 時)

  • SLO: staging 実測 P99 < 60 秒 + 本番 merge 時の実測 < 60 秒
  • 実施頻度: PR-4 merge 前に staging で 1 回 · 本番 merge 時に 1 回
  • 撤退条件連動: >60 秒で CREATE INDEX CONCURRENTLY 化検討 + rollback 検討 (ADR-0203 §Confirmation #4「Phase 0 中 schema 変更 ≤ 1 回」を本 amend が消費する制約下 · KPI 消費済み後の緊急 amend は §8-6 例外条件で許容)

BigQuery SQL 骨格 (Cloud Logging sink 経由):

SELECT
  migration_id,
  execution_start_time,
  execution_end_time,
  TIMESTAMP_DIFF(execution_end_time, execution_start_time, SECOND) AS duration_sec
FROM `${project}.${dataset}.cloud_sql_migration_log`
WHERE migration_id = 'adr-0203-amend-fiscal-year-close-schema'
ORDER BY execution_start_time DESC;
-- 期待値: duration_sec < 60 (staging + 本番の各 1 回)

補足: index 5 本 (partial index WHERE fiscal_year_close_confirmed_at IS NULL + BTree × 4) の実行時間を staging で先行実測し、CREATE INDEX CONCURRENTLY が必要か判断する。本番 merge 時の migration は staging 実測後の Confidence-High 状態で実行する。

KPI 5: fiscal_year_close_events 追記専用トリガー存在数 = 1 件 (週次)

  • SLO: 常時 1 件 (追記専用トリガー fiscal_year_close_events_append_only が Cloud SQL 上に存在)
  • 実施頻度: 週次 (BQ scheduled query · Cloud SQL metadata 取得経由)
  • 撤退条件連動: !=1 件で CI ジョブ / PITR リストア手順の DROP TRIGGER 実行経路を調査 + トリガー再作成 SQL 即時実行 + ADR-0175 3 号真実性ルート要素 (i) 連動監査

BigQuery SQL 骨格:

SELECT COUNT(*) AS append_only_trigger_count
FROM `${project}.${dataset}.pg_information_schema_triggers`
WHERE event_object_table = 'fiscal_year_close_events'
  AND trigger_name = 'fiscal_year_close_events_append_only'
  AND action_timing = 'BEFORE'
  AND event_manipulation IN ('UPDATE', 'DELETE');
-- 期待値: 2 (UPDATE と DELETE の 2 event に対する trigger 定義行)
--        あるいは trigger 1 件で複数 event を扱う場合は 1 (schema 定義に依存)

補足: 本 SQL は Cloud SQL の information_schema.triggers を BQ に周期 export する構成を前提とする。export sink は PR-4 実装時に確立 (Cloud SQL federated query or scheduled export)。

PR-4 merge 完了時の確定タスク

PR-4 (vlt/src/db/schema.sql の schema 追加 migration + Cloud SQL federated query or export sink) merge の時点で以下を確定する:

  1. table 名の確定: ${project} / ${dataset} の実値を SQL 骨格に埋め込む
  2. Cloud SQL federated query 設定 or export sink 設定: KPI 1/5 の Cloud SQL metadata と error log を BQ から参照可能にする
  3. BQ scheduled query 登録: KPI 1/2/5 は月次 or 週次 · KPI 3 は週次 · KPI 4 は PR merge 前後 1 回のみ
  4. staging migration 実測: PR-4 merge 前に staging で index 5 本の execute 時間 P99 を測定 (KPI 4)
  5. 本ページ Week 1 更新: PR-4 merge 完了時に本節を Week 1 として実測値へ置き換え

関連 SSoT

  • ADR-0217 (ADR-0203 amend · 確定申告完了関連 schema 3 点追加): docs/adr/0217-add-tax-filing-completion-related-schema.md (§9 Confirmation が本 SQL 骨格の SSoT)
  • Amend 元 ADR-0203 (receipts と audit_log の schema 基礎): docs/adr/0203-*.md (§Confirmation #4 の KPI 消費制約と連動)
  • 親決定 ADR-0208 (保存年限管理と期限後廃棄): docs/adr/0208-*.md (Confirmation #6 と統合)
  • 関連 ADR-0215 (確定申告完了イベント連携): docs/adr/0215-*.md (§Confirmation #1 subscription lag と KPI 3 pubsub_outbox relay lag を統合観測)
  • 観測手順 pattern の先例: docs/_internal/06_ops/adr-0212-observation-log.md (drp domain · 週次観測ログ)