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 和最新错误
view-list	所有已保存的查询 / 物化视图及其状态和最新错误
view-run-history	特定物化视图的运行历史
external-data-sources-webhook-info-retrieve	检查各数据源的 Webhook 状态（data-health-issues 未覆盖此项）

data-health-issues 端点已汇总物化操作、同步架构、数据源、批量导出目标和转换，因此是获取概要最快的途径。当你需要比概要更详细的上下文（行数、未失败的项目、架构级别的详细信息）时，请使用列表端点。

什么算作“问题”

数据健康端点会返回以下五类条目：

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。

如果用户询问数据陈旧或未使用的条目，请不要局限于此端点——参见步骤 4。

工作流

步骤 1 — 一次性拉取

调用 data-warehouse-data-health-issues-retrieve。该调用会在一次请求中返回所有当前处于失败状态的条目。

如果响应为空，告诉用户其数据管道运行正常，然后停止。不要凭空编造问题。

步骤 2 — 分组并确定优先级

按 type 对问题分组，并在每个分组内按严重程度排序：

1. 优先处理处于 Error 状态的数据源。 数据源故障会产生连锁影响——在数据源重新连接前，其下的所有架构实际上都无法使用。先修复这些问题。
2. 接下来处理同步架构，按以下顺序排列：
   • status: "billing_limit" 条目（计费问题，非技术问题——标记并转交计费团队）
   • 使用频繁的表上的 Failed 状态（根据需要询问用户，或通过 schemas-list 检查行数）
   • 使用较少的表上的 Failed 状态
3. 物化视图。 通常独立于数据源——视图失败通常是视图本身的 HogQL 或数据问题。
4. 批量导出目标。 影响从 PostHog _导出_的数据——很重要，但通常不会阻止读取。
5. 转换。 影响数据摄取。请单独标记，因为这些是 HogFunction 问题，而非数据仓库同步问题。

步骤 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，查找 last_synced_at 相对于 sync_frequency 已过时的架构。 如果某个架构的同步频率为 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 健康状况与架构健康状况是分开的。 数据健康端点无法获知 Webhook 状态。当用户提到“实时”、“Stripe webhook”或“为什么 Webhook 数据源的数据延迟了几个小时”时，应直接调用 webhook-info-retrieve，而不是根据架构状态推断。