auditing-warehouse-data-health

データウェアハウスの健全性を監査する

このスキルは、プロジェクト全体のデータウェアハウスパイプラインを監査します。個別の同期を深掘りするのではなく、問題の全体像を把握したい場合に使用します。個々の失敗を深掘りするスキルは diagnosing-failed-warehouse-syncs です。このスキルでは、まずどこを調べるべきかを確認できます。

このスキルを使用するタイミング

• 「データウェアハウスで何が壊れていますか？」／「健全性を確認してください」
• 「データパイプラインを監査してください」
• プロジェクトに参加したばかりで、引き継いだ内容を把握したい場合
• パイプラインの健全性を毎週または毎月確認する場合
• ダッシュボードのデータが古く、どのソースに問題があるのか分からない場合

利用可能なツール

ツール	用途
data-warehouse-data-health-issues-retrieve	一括確認：パイプライン全体で失敗または劣化している項目をすべて取得します
external-data-sources-list	ステータスと最新のエラーを含む、すべてのソースを取得します
external-data-schemas-list	ステータス、last_synced_at、latest_errorを含む、すべてのスキーマを取得します
view-list	ステータスと最新のエラーを含む、すべての保存済みクエリ／マテリアライズドビューを取得します
view-run-history	特定のマテリアライズドビューの実行履歴を取得します
external-data-sources-webhook-info-retrieve	ソースごとのWebhookの状態を確認します（data-health-issuesでは対象外）

data-health-issuesエンドポイントは、マテリアライゼーション、同期スキーマ、ソース、バッチエクスポート先、変換処理をすでに集約しているため、概要を把握するには最も迅速な方法です。概要だけでは情報が足りず、行数、失敗していない項目、スキーマレベルの詳細が必要な場合は、一覧取得用のエンドポイントを使用します。

「問題」とみなされるもの

データヘルスエンドポイントは、次の5つのカテゴリの項目を返します。

type	発生条件	一般的な緊急度
source	ExternalDataSource.status = Error — ソース接続全体の障害	高
external_data_sync	スキーマが Failed または BillingLimitReached の状態（データヘルスエンドポイントは、それぞれ status: "failed" または status: "billing_limit" を返します）	中〜高
materialized_view	DataWarehouseSavedQuery.is_materialized=true, status=Failed	中
destination	バッチエクスポートの最新実行が FAILED / FAILED_RETRYABLE / TIMEDOUT / TERMINATED	中
transformation	HogFunction の変換が DISABLED / DEGRADED / FORCEFULLY_* の状態	低〜中

各項目には、id、name、type、status、error、failed_at、url と、（同期／ソースの場合は） source_type が含まれます。

データヘルスエンドポイントが報告するのは、_現在発生している障害_のみです。次の項目は検出されません。

• ユーザーが一時停止したスキーマ（should_sync = false）
• エラーのある非マテリアライズドビュー（マテリアライズドビューのみが報告されます）
• 技術的には Completed だが、同期が遅い、または古いスキーマ
• sync_type: "webhook" のスキーマにおけるWebhook の問題。一括同期のセーフティネットが成功していても、Webhook のプッシュチャネルが（登録解除、リモート側での無効化、署名検証の失敗などにより）ひそかに機能しなくなっていることがあります。これらは data-health-issues には表示されません。ソースごとに webhook-info-retrieve で確認してください。

ユーザーがデータの古さや未使用の項目について尋ねた場合は、このエンドポイントだけでなく、Step 4 も確認してください。

ワークフロー

Step 1 — 一括取得

data-warehouse-data-health-issues-retrieve を呼び出します。このリクエスト1回で、現在障害が発生しているすべての項目が返されます。

応答が空の場合は、パイプラインは正常であることをユーザーに伝え、そこで終了します。問題をでっち上げないでください。

Step 2 — グループ化して優先順位を付ける

問題を type ごとにグループ化し、各グループ内では深刻度順に並べます。

1. まず Error 状態のソース。 ソースの障害は連鎖し、そのソース配下のすべてのスキーマは、ソースが再接続されるまで実質的に利用できなくなります。最初に修正してください。
2. 次に同期スキーマ。 以下の順に並べます。
   • status: "billing_limit" の項目（請求に関する問題で、技術的な問題ではありません。指摘して請求担当に引き継いでください）
   • 利用頻度の高いテーブルの Failed（ユーザーに確認するか、必要に応じて schemas-list で行数を確認してください）
   • 利用頻度の低いテーブルの Failed
3. マテリアライズドビュー。 通常、ソースとは独立しています。ビューの障害は、ビュー自体の HogQL またはデータの問題です。
4. バッチエクスポート先。 PostHog から_出ていく_データに影響します。重要ですが、通常は読み取りを妨げません。
5. 変換。 取り込みに影響します。これらは HogFunction の問題であり、ウェアハウス同期の問題ではないため、別途指摘してください。

Step 3 — 監査結果を提示する

優先順位を付けたレポートを作成します。生の JSON をそのまま出力せず、カテゴリごとに人が読みやすい表にまとめてください。

## Data warehouse health — 7 issues

### 🔴 Sources (1)
- Stripe — authentication failed (failed 2h ago)
  → `diagnosing-failed-warehouse-syncs` on this source

### 🟠 Sync schemas (3)
- postgres_prod.orders (Failed 6h ago) — column "updated_at" does not exist
- postgres_prod.invoices (Failed 6h ago) — column "updated_at" does not exist
- hubspot.contacts (BillingLimitReached) — team quota exceeded

### 🟠 Materialized views (2)
- monthly_revenue — view failed (syntax error in HogQL)
- active_users_30d — view failed (missing table reference)

### 🟡 Destinations (1)
- S3 export "daily-events" (FAILED_RETRYABLE 3 runs in a row)

Recommended order:
1. Stripe auth (everything under it is dead)
2. Schema-drift on postgres_prod.orders / invoices — looks like upstream renamed a column
3. Billing limit on hubspot
4. Materialized views (independent — can be tackled any time)

厳密な形式よりも、優先順位が付けられていること、グループ化されていること、対応につながること、次に使うべきスキルのヒントがあることが重要です。

Step 4 — アクティブな障害の範囲を超えて確認する（依頼された場合）

ユーザーが「今発生している障害」だけでなく、「ほかに何を確認すればよいですか？」など、より広い確認を求めている場合は、次の項目を照合します。

古いのに「Completed」になっているスキーマ： external-data-schemas-list を呼び出し、sync_frequency に対して last_synced_at が古いスキーマを探します。 1hour の頻度で、最後の同期が3日前のスキーマは、ステータスが Completed でも実質的に壊れています。

未使用のマテリアライズドビュー： view-list を呼び出します。マテリアライズドビューは、実行のたびにストレージとコンピューティングリソースを消費します。マテリアライズドビューとして設定されているものの、最近クエリされていないものがあれば、cleaning-up-stale-warehouse-views の対象として提示します（まだ実装されていませんが、データは利用できます）。

同期アクティビティがゼロのソース： すべてのスキーマで should_sync: false または status = Paused になっているソースです。設定後に放置されたものであり、external-data-sources-destroy によるクリーンアップの候補です。

Webhook タイプのスキーマで壊れている Webhook： sync_type: "webhook" のスキーマを持つソース（external-data-schemas-list で確認できます）を順に確認します。それぞれについて、external-data-sources-webhook-info-retrieve({source_id}) を呼び出します。

• スキーマが sync_type: "webhook" なのに exists: false → Webhook が登録されていないか、削除されています。プッシュチャネルは機能しておらず、一括フォールバックのみがデータを取り込んでいます。
• external_status.error がある → リモートサービスが問題を報告しています（権限の取り消し、またはサービスのダッシュボードでエンドポイントが削除されたなど）。
• external_status.status が "enabled" ではない → リモートサービスがエンドポイントを無効にしています（配信の失敗が繰り返された後によく発生します）。

これらはほかのカテゴリとは問題の性質が異なり、修正に使うスキルも異なるため、主な監査結果とは分けて報告します（diagnosing-failed-warehouse-syncs のシナリオ I、または setting-up-a-data-warehouse-source のステップ 5.5）。

追加のツール呼び出しやヒューリスティックを伴うため、こうした追加確認は、ユーザーがより広範な監査を明示的に依頼した場合にのみ実施します。

Step 5 — 次のステップを提案する

監査の最後に、次の対応へ明確に引き継ぎます。

• 「Stripe の障害を詳しく調べましょうか？」→ diagnosing-failed-warehouse-syncs に引き継ぎます
• 「orders のスキーマドリフトを修正しましょうか？」→ tuning-incremental-sync-config に引き継ぎます
• 「請求上限に達したスキーマを無効にしましょうか？」→ external-data-schemas-partial-update でワンクリック対応します

監査から自律的に修正を開始してはいけません。監査の役割は報告と提案であり、修復ではありません。修正を実行する前に、必ず明示的な確認を得てください。

やり取りの例

User: "Check the health of our data warehouse"

Agent:
- data-warehouse-data-health-issues-retrieve → 4 items
   [{type: "source", name: "Stripe", error: "401 Unauthorized", ...},
    {type: "external_data_sync", name: "postgres_prod.orders",
     error: "column \"updated_at\" does not exist", ...},
    {type: "materialized_view", name: "monthly_revenue",
     error: "syntax error at or near \"FORM\"", ...},
    {type: "destination", name: "S3 daily-events", error: "AccessDenied", ...}]

- Report:
  "Found 4 issues in your data warehouse:

   🔴 Sources (1)
   - Stripe — auth failure 2h ago (401). All 8 tables under it are currently dead.

   🟠 Sync schemas (1)
   - postgres_prod.orders — column `updated_at` was dropped on the source side,
     incremental sync can't find it.

   🟠 Materialized views (1)
   - monthly_revenue — HogQL syntax error ('FORM' instead of 'FROM').

   🟡 Destinations (1)
   - S3 export 'daily-events' — access denied on write.

   Suggest fixing in this order:
   1. Stripe credentials (unblocks everything under it)
   2. orders incremental-field drift
   3. monthly_revenue typo
   4. S3 permissions

   Want me to start on Stripe?"

重要な注意事項

• 監査は読み取り専用です。 監査のフローでは、破壊的なツールを呼び出してはいけません。診断や調整のスキルに引き継ぎ、これらのスキルで実行前に確認を取ります。
• 空の結果は正常です。 問題が何もない監査結果に、仮定上の問題を付け加えてはいけません。「問題は見つかりませんでした」は適切な回答です。
• ソースの障害は波及します。 Error のソースを報告する際は、その配下で影響を受けているスキーマ（または、次回の同期時に影響を受けるスキーマ）も伝えてください。ユーザーは影響範囲を把握する必要があります。
• 請求上限は技術的な問題ではありません。 問題として提示しますが、復旧対応ではなく、請求やクォータに関する相談へ案内します。
• 変換の問題は別扱いです。 HogFunctions はウェアハウスの同期ではありません。より広範なパイプラインの一部であるため監査に表示されますが、posthog の取り込み側に属します。ここで直接修正するのではなく、パイプライン関連のスキルへ案内します。
• data-health-issues で表示されるのはアクティブな障害だけです。 データの古さ、未使用のビュー、放置されたソースを確認するには、リスト取得エンドポイントとの照合が必要です。より詳細な監査をユーザーが明示的に依頼した場合にのみ実施してください。
• Webhook の健全性とスキーマの健全性は別です。 data-health エンドポイントでは Webhook の状態を把握できません。ユーザーの依頼に「リアルタイム」「Stripe webhook」「Webhook ソースのデータが数時間遅れるのはなぜですか」などの内容が含まれる場合は、スキーマのステータスから推測するのではなく、webhook-info-retrieve を直接呼び出してください。