SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场auditing-warehouse-data-health

auditing-warehouse-data-health

数据与分析

查看项目

更新于 10-15 18:41

技能介绍

用途

本技能对 PostHog 项目的数据仓库管道做项目级审计，回答“仓库里什么坏了”“给我一次健康检查”“审计我的数据管道”之类的问题。当用户刚接手一个项目、想了解继承了什么，或需要每周／每月管道健康复盘，以及仪表盘数据陈旧但不确定是哪个来源出错时，都可以使用它。它是一次扫描，用来告诉用户先看哪里，而不是对单个同步做深入排查——单个失败的深入诊断属于 diagnosing-failed-warehouse-syncs。

主要能力

可用工具包括：

  • data-warehouse-data-health-issues-retrieve：一次性获取整条管道中所有失败／降级项。
  • external-data-sources-list：列出所有来源及其状态和最新错误。
  • external-data-schemas-list：列出所有 schema 及其状态、last_synced_at、latest_error。
  • view-list：列出所有已保存查询／物化视图及其状态和最新错误。
  • view-run-history：查看某个物化视图的运行历史。
  • external-data-sources-webhook-info-retrieve：检查每个来源的 webhook 状态（data-health-issues 不覆盖此项）。

data-health-issues 端点已聚合 materializations、sync schemas、sources、batch export destinations 和 transformations，是获取摘要最快的路径。需要更多上下文时（行数、未失败项、schema 级细节），再使用各 list 端点。

“问题”的范围

data-health 端点返回五类条目：

  • source：ExternalDataSource.status = Error，整个来源连接断开，紧急度高。
  • external_data_sync：schema 处于 Failed 或 BillingLimitReached 状态（分别对应 status: "failed" 或 status: "billing_limit"），紧急度中到高。
  • materialized_view：DataWarehouseSavedQuery.is_materialized=true 且 status=Failed，紧急度中。
  • destination：批量导出的最近一次运行是 FAILED／FAILED_RETRYABLE／TIMEDOUT／TERMINATED，紧急度中。
  • transformation：HogFunction transformation 处于 DISABLED／DEGRADED／FORCEFULLY_* 状态，紧急度低到中。

每个条目包含 id、name、type、status、error、failed_at、url，以及（对同步／来源而言）source_type。

注意 data-health 端点只报告活跃失败，不标记：用户暂停的 schema（should_sync = false）；非物化视图的错误（只报告物化视图）；缓慢或陈旧但技术上为 Completed 的 schema；sync_type: "webhook" 的 schema 上的 webhook 问题。批量同步安全网可能成功，而 webhook 推送通道已静默损坏（被注销、远端禁用、签名验证失败），这些不会出现在 data-health-issues 中，需对每个来源用 webhook-info-retrieve 检查。若用户询问陈旧度或未使用项，需超出该端点范围，参见下文步骤 4。

工作流程

步骤 1 — 一次性拉取：调用 data-warehouse-data-health-issues-retrieve，返回所有活跃失败项。若响应为空，告知用户管道健康并停止，不要编造问题。

步骤 2 — 分组与排序：按类型分组，组内按严重程度排序。

  1. 来源处于 Error 的先处理——来源故障会级联，其下每个 schema 实际上都失效。
  2. 同步 schema：先 status: "billing_limit"（账单问题，非技术性，标记并转交账单）；再是高使用率表上的 Failed；然后是低使用率表上的 Failed。
  3. 物化视图：通常独立于来源，视图失败通常是 HogQL 或视图自身数据问题。
  4. 批量导出目标：影响数据出站，重要但一般不阻塞读取。
  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)

关键不在具体格式，而在于：有优先级、有分组、可行动，并提示正确的下一个技能。

步骤 4 — 在用户要求时超出活跃失败：若用户想要“还有什么该看”，做以下交叉检查：

  • 陈旧但“Completed”的 schema：调用 external-data-schemas-list，找出 last_synced_at 与其 sync_frequency 相比过旧的 schema。1 小时频率却 3 天未同步，即使状态为 Completed 也实际已坏。
  • 未使用的物化视图：调用 view-list。物化视图每次运行都消耗存储和计算，若有标记为物化但近期未被查询，提示出来（清理陈旧仓库视图属于 cleaning-up-stale-warehouse-views 的范围，尚未实现，但数据可用）。
  • 零同步活动的来源：所有 schema 都是 should_sync: false 或 status = Paused 的来源，属于建立后被遗弃，可用 external-data-sources-destroy 清理。
  • webhook 类型 schema 上的损坏 webhook：遍历有 sync_type: "webhook" schema 的来源（通过 external-data-schemas-list 可见），对每个调用 external-data-sources-webhook-info-retrieve({source_id})：exists: false 而 schema 是 webhook 类型，说明 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 的 schema 漂移吗？”交接给 tuning-incremental-sync-config；“要我禁用触发账单上限的 schema 吗？”通过 external-data-schemas-partial-update 一键完成。绝不要从审计自主开始应用修复——审计的职责是报告和建议，不是修复，任何修复都需明确确认后再执行。

示例交互

用户：“检查我们数据仓库的健康状况”

Agent 调用 data-warehouse-data-health-issues-retrieve 得到 4 条，然后报告发现 4 个问题：Stripe 来源 2 小时前认证失败 401，其下 8 张表当前全部失效；postgres_prod.orders 的 updated_at 列在源端被删除，增量同步找不到；monthly_revenue 视图 HogQL 语法错误（把 FROM 写成了 FORM）；S3 daily-events 导出写入时访问被拒。建议修复顺序：先处理 Stripe 凭证（解除其下全部阻塞）、再处理 orders 增量字段漂移、然后修 monthly_revenue 拼写、最后修 S3 权限，并询问是否从 Stripe 开始。

适用场景与限制

适用：项目级管道健康概览、接手项目摸底、周期健康复盘、仪表盘陈旧时定位问题来源、需要按优先级列出所有活跃失败并给出下一步建议。

限制与注意事项：审计为只读，绝不从审计流程调用破坏性工具。为空即健康，不要用假设的问题填充空审计，“未发现问题”是好答案。来源故障会级联，报告来源 Error 时也要说明其下哪些 schema 受影响。账单限制不是技术问题，要标记并转交账单／配额讨论，而不是恢复动作。转换问题单独处理，HogFunction 不是仓库同步，在上游摄取侧，应交给管道类技能。data-health-issues 只呈现活跃失败，陈旧、未使用视图或废弃来源需交叉检查 list 端点，且仅在用户明确要求更深审计时进行。webhook 健康与 schema 健康分离，data-health 端点不知道 webhook 状态；当用户提到“实时”“Stripe webhook”或“为什么 webhook 来源数据落后数小时”时，应直接用 webhook-info-retrieve，而不是从 schema 状态推断。资料未提供价格、收费、平台支持范围、具体性能效果等其他信息。