auditing-warehouse-source-health

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

このスキルは、データウェアハウスのパイプラインにおけるソースと同期の側面、つまりソース接続、同期スキーマ、Webhook のプッシュチャネルについて、プロジェクト全体を監査します。特定の同期を詳しく調べるのではなく、ユーザーがインポートの何が問題なのかを要約してほしい場合に使用します。個々の失敗を詳しく調べるには diagnosing-failed-warehouse-syncs を使用します。このスキルでは、まずどこを確認すべきかを特定します。

同じ基盤エンドポイント（data-warehouse-data-health-issues-retrieve）では、マテリアライズドビュー、バッチエクスポート先、変換の問題も報告されます。マテリアライズドビューについては auditing-warehouse-view-health で扱います。エクスポート先（バッチエクスポート）と変換は他のプロダクトが担当するため、表示された場合は取り上げますが、ここで診断せず、該当チームに案内してください。

このスキルを使用する場合

• 「インポートに失敗するのはなぜですか？」／「ソースの何が問題ですか？」
• 「ウェアハウスのデータが古いのはなぜですか？」
• ユーザーがプロジェクトに初めて参加し、引き継いだソースとその健全性を把握したい場合
• ソース／同期の健全性を週次または月次で確認する場合
• ダッシュボードのデータが古く、どのソースに問題があるか分からない場合

利用可能なツール

ツール	目的
data-warehouse-data-health-issues-retrieve	一括取得：パイプライン全体の失敗または劣化した項目
external-data-sources-list	ステータスと最新のエラーを含む、すべてのソース
external-data-schemas-list	ステータス、last_synced_at、最新のエラーを含む、すべてのスキーマ
external-data-sources-webhook-info-retrieve	ソースごとの Webhook の状態を確認（data-health-issues では対象外）

data-health-issues エンドポイントはパイプライン全体の情報を集約するため、要約を得る最も速い方法です。この監査では、結果を source と external_data_sync のタイプに絞り込んでください。要約より詳しい情報（行数、失敗していない項目、スキーマ単位の詳細）が必要な場合は、一覧エンドポイントを使用します。

ソース／同期の「問題」として扱うもの

データヘルスエンドポイントでは、この監査の対象となるのは5つのカテゴリのうち2つです。

type	トリガー	一般的な緊急度
source	ExternalDataSource.status = Error — ソース接続全体の障害	高
external_data_sync	スキーマが Failed または BillingLimitReached の状態（データヘルスエンドポイントは、それぞれ status: "failed" または status: "billing_limit" を返します）	中〜高

各エントリには、id、name、type、status、error、failed_at、url、source_type が含まれます。

エンドポイントが返すその他のカテゴリは、このスキルの対象外です。

• materialized_view → auditing-warehouse-view-health
• destination（バッチエクスポート）→ バッチエクスポート／データパイプライン製品の担当範囲です
• transformation（HogFunction）→ CDP／データ取り込み側の担当範囲です

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

• ユーザーが一時停止したスキーマ（should_sync = false）
• 技術的には Completed だが、処理が遅い、またはデータが古いスキーマ
• sync_type: "webhook" のスキーマにおけるWebhookの問題。 バルク同期の安全策が成功していても、Webhookのプッシュチャネルが気づかれないまま機能しなくなることがあります（登録解除、リモート側での無効化、署名検証の失敗など）。 これらは data-health-issues には表示されません。webhook-info-retrieve を使ってソースごとに確認してください。

データの古さや未使用項目についてユーザーから尋ねられた場合は、このエンドポイント以外も確認してください。ステップ4を参照してください。

ワークフロー

ステップ1 — 一括取得

data-warehouse-data-health-issues-retrieve を呼び出し、source と external_data_sync のエントリを確認します。

ソース／同期の問題がなければ、ソースは健全であるとユーザーに伝えて終了します。問題をでっち上げないでください。

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

1. まず、Error 状態のソースを確認します。 ソースの障害は連鎖し、その下にあるすべてのスキーマはソースが再接続されるまで実質的に利用できなくなります。まずこれらを修正してください。
2. 次に同期スキーマを、以下の順に確認します。
   • status: "billing_limit" のエントリ（技術的な問題ではなく、請求に関する問題です。明記して請求担当に回してください）
   • よく使われるテーブルの Failed（ユーザーに確認するか、必要に応じて schemas-list で行数を確認してください）
   • あまり使われないテーブルの Failed

ステップ3 — 監査結果を提示する

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

## Data warehouse source health — 4 issues

### 🔴 Sources (1)
- Stripe — authentication failed (failed 2h ago). All 8 tables under it are currently dead.
  → `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

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 — 稼働中の障害以外も確認する（依頼された場合）

ユーザーが「何が問題になっているか」だけでなく、「ほかに確認すべきことは？」なども尋ねている場合は、次の項目を照合します。

「Completed」だが古いスキーマ： external-data-schemas-list を呼び出し、last_synced_at が sync_frequency に対して古いスキーマを探します。 同期頻度が 1hour のスキーマで、最終同期が 3 日前であれば、ステータスが Completed でも実質的に機能していません。

同期アクティビティがゼロのソース： すべてのスキーマで 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）。

こうした追加チェックは、ユーザーがより広範な監査を明示的に依頼した場合に限って実行します。追加のツール呼び出しとヒューリスティックを伴うためです。

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

明確な引き継ぎ案内で監査を締めくくります。

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

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

重要な注意事項

• 監査は読み取り専用です。 監査の手順では、破壊的なツールを決して呼び出さないでください。診断／調整スキルに引き継ぎ、それらのスキルでも実行前に確認します。
• 空であれば正常です。 空の監査結果を仮定上の問題で埋めないでください。「ソースに問題は見つかりませんでした」は適切な回答です。
• ソースの障害は連鎖します。 Error 状態のソースを報告する際は、その配下で影響を受けているスキーマ（または次回同期時に影響を受けるスキーマ）も明記してください。ユーザーは影響範囲を把握する必要があります。
• 請求上限は技術的な問題ではありません。 その旨を伝えますが、復旧対応ではなく、請求／クォータの相談に案内してください。
• data-health-issues で検出できるのは稼働中の障害のみです。 古さや放置されたソースについては、一覧エンドポイントとの照合が必要です。より詳細な監査をユーザーが明示的に依頼した場合に限り、これを行ってください。
• Webhook の健全性とスキーマの健全性は別です。 data-health エンドポイントは Webhook の状態を把握しません。ユーザーの依頼に「リアルタイム」「Stripe webhook」、または「Webhook ソースのデータが何時間も遅れているのはなぜ？」という内容が含まれる場合は、スキーマの状態から推測せず、webhook-info-retrieve を直接呼び出してください。
• マテリアライズドビュー、宛先、変換処理はここでは対象外です。 これらも data-health エンドポイントを共有しますが、別の監査／製品に属するため、診断せず担当先に案内してください。