auditing-endpoints

审计端点

此技能会对 Endpoints 产品进行项目范围的审计。当用户想要找出需要清理的内容时使用——例如未使用的端点、失败的物化操作，以及已无人调用的物化版本。此技能不会修改任何内容；只会生成报告。

针对每个端点进行更深入的调查，请使用 diagnosing-endpoint-performance。审计的任务是找出候选项并移交后续处理。

何时使用此技能

• “审计我的端点”／“哪些端点可以清理？”
• 用户接管一个项目，想了解自己接手了什么
• 定期审查（每月／每季度）端点的泛滥情况
• 用户超出物化成本预算，想了解应停用哪些内容

专用工具可快速查看端点级信息。要查询一段时间内的调用频率、最近调用时间和成本，请使用 execute-sql 查询 query_log 表（端点级）。每个版本的最近调用时间可通过 endpoint-versions 获取——每个版本都有自己的 last_executed_at。

可用工具

工具	用途
execute-sql (HogQL)	主要读取方式。 查询 system.data_modeling_endpoints 获取元数据（名称、is_active、current_version、derived_from_insight、last_executed_at），查询 query_log 获取端点级用量（调用次数、最近调用时间、耗时、字节数）
endpoint-materialization-status	每个端点的物化资格、当前状态、上次运行时间和上次错误（系统表中不包含这些信息，请使用此工具）
endpoint-versions	某个端点的所有版本，按最新版本优先排列，并显示各版本的查询、物化状态和 last_executed_at
endpoint-update	写入方式——用户确认后停用（is_active: false）或取消物化（is_materialized: false）
agent-feedback	告知 PostHog 团队此流程中缺少或令人困惑的内容，以便改进产品和技能

优先从系统表读取数据，而不是使用 endpoints-get-all / endpoint-get 工具——一条 SQL 查询即可返回完整清单，并可将元数据与 query_log 中的用量数据关联起来。

什么情况算作问题

类别	触发条件	常见操作
从未调用	query_log 中没有该端点的记录（仅统计个人 API 密钥调用）	与用户确认后禁用
已过时	query_log 显示距上次调用已超过 30 天	与用户确认；通常可以安全禁用
未激活	system.data_modeling_endpoints 中的 is_active = 0	核实意图；如果已弃用，则删除
物化失败	endpoint-materialization-status 返回 Failed 并带有错误信息	转交给 diagnosing-endpoint-performance
未使用的物化版本	某个物化版本的 last_executed_at（来自 endpoint-versions）为空或长期未更新	取消该版本的物化，或切换到较新的版本
版本偏离	存在许多版本（查询反复变更）	历史记录噪声——不算问题，但值得指出

使用量只统计个人 API 密钥调用——如果某个端点仅通过 Playground 选项卡或应用执行，就会显示为未使用。每个版本的 last_executed_at 仅记录启用该追踪功能后的运行情况，因此某个版本即使仍在使用，也可能显示为空；移除前务必先确认。

工作流

1. 列出端点及其元数据

通过一条 execute-sql 查询，从 system.data_modeling_endpoints 获取完整清单：

SELECT name, is_active, current_version, derived_from_insight, last_executed_at
FROM system.data_modeling_endpoints
ORDER BY name

如果没有结果 → 项目没有端点；说明这一点并停止。不要臆造问题。（此处的 last_executed_at 列是便于查看的端点级时间戳；要查看调用频率和成本，请在下一步使用 query_log。）

2. 从 query_log 获取使用情况

query_log 会记录每次个人 API 密钥调用，并标注端点名称。通过一条查询即可获取所有端点的最近调用时间和调用次数：

SELECT name, count() AS calls, max(query_start_time) AS last_called
FROM query_log
WHERE endpoint LIKE '%/endpoints/%' AND is_personal_api_key_request
GROUP BY name
ORDER BY name

与第 1 步的结果交叉核对：

• 元数据中存在，但 query_log 中没有 → 从未通过 API 密钥调用
• 距上次调用已超过 30 天 → 已过时

query_log 还会按每次调用记录 query_duration_ms、read_rows 和 read_bytes，可用于在同一轮检查中标记开销较大的端点。这些是端点级数据；每个版本的最近调用时间请查看 endpoint-versions（第 3 步）。

3. 检查物化状态和未使用的版本

对于每个已物化的端点，调用 endpoint-materialization-status（系统表中没有此项）。单独列出任何 status: "Failed" 的端点——这是当前故障，不是过时问题。

然后调用 endpoint-versions 并查看每个版本的 last_executed_at：时间为空或长期未更新的物化版本，是未使用物化版本的候选项。请将其视为线索，而非定论——每个版本的最近调用时间只统计启用追踪功能后的 API 密钥运行情况，因此取消物化前请先与用户确认。

4. 呈现审计结果

按类别分组并按优先级呈现报告。不要直接输出原始 JSON；请按各部分使用易读的表格：

## Endpoints audit — 9 issues

### 🔴 Failing materialisations (1)
- weekly_revenue (v3) — Failed 2h ago, "Column 'event_date' does not exist"
  → hand off to diagnosing-endpoint-performance

### 🟠 Never called via API key (3)
- internal_admin_query — created 5 months ago
- legacy_signup_funnel — created 1 year ago, materialised
- experiment_arm_lookup — created 9 months ago

### 🟠 Unused materialised versions (2)  [from endpoint-versions]
- monthly_active_users — v3 materialised, last_executed_at null (currently on v4 — unmaterialise v3)
- order_summary — v1 materialised, last_executed_at null

### 🟡 Stale (3)
- holiday_promo_2024 — last called 4 months ago
- ab_test_phase_1 — last called 2 months ago
- daily_revenue_cohort — last called 45 days ago

Recommended order:
1. Investigate the failing materialisation (blocks fresh data)
2. Unmaterialise the unused versions (free storage + compute)
3. Disable the never-called endpoints (if user confirms)
4. Review stale endpoints with the user

具体格式并不重要，重要的是：优先级明确、分组清晰、可采取行动，并且交接事项一目了然。

5. 提出下一步建议

以明确的问题结束，而不是直接做决定：

• “要我取消未使用版本的物化吗？”——需要针对每个版本调用 endpoint-update，并设置 is_materialized: false
• “要我停用从未调用过的端点吗？”——需要调用 endpoint-update，并设置 is_active: false
• “要我深入调查物化失败的问题吗？”——转交给 diagnosing-endpoint-performance

切勿仅凭审计结果采取行动。 停用或取消物化会影响外部 API 消费者； 修改前务必先征得确认。

交互示例

User: "Audit my endpoints"

Agent steps:
- execute-sql on system.data_modeling_endpoints → 12 endpoints (4 materialised)
- execute-sql on query_log grouped by name → 8 endpoints have calls
- endpoint-materialization-status on each materialised endpoint → 1 failing
- endpoint-versions on the materialised ones → order_summary v2's last_executed_at is null

- Report:
  "Found 6 things worth looking at across 12 endpoints:

   🔴 Failing materialisations (1)
   - monthly_active_users (v2) — materialisation failed yesterday with
     'memory limit exceeded'. The endpoint is still callable inline but
     responses will be slower.

   🟠 Never called via API key (3)
   - legacy_funnel_v1 — created 11 months ago
   - test_export — created 3 months ago
   - admin_dump — created 8 months ago, materialised (wasteful)

   🟠 Unused materialised versions (1)  [from endpoint-versions]
   - order_summary v2 — materialised but its last_executed_at is null
     while v3 is current. Likely safe to unmaterialise v2.

   🟡 Stale (1)
   - holiday_2024 — last called 5 months ago

   Caveat: usage only counts personal-API-key calls; playground and
   dashboard runs aren't counted. Per-version recency comes from
   endpoint-versions and is sparse. Confirm before disabling.

   Want me to start with the failing materialisation, or clean up the
   unused version first?"

重要说明

• 审计是只读的。 切勿在此流程中调用具有破坏性的工具。任何修改前都应转交处理或先征得确认。
• 结果为空 = 状态正常。 不要为了充实空报告而罗列理论问题。“无需清理”也是恰当的回答。
• 使用 SQL 读取，通过版本工具深入调查。 通过 execute-sql 查询 system.data_modeling_endpoints（元数据）和 query_log（端点级调用次数、最近调用时间、成本），即可完成大部分审计。各版本最近调用时间来自 endpoint-versions（每个版本的 last_executed_at）。
• 仅统计 API 密钥调用。 使用情况只统计个人 API 密钥调用。仅在 Playground 标签页或应用中使用的端点会显示为未使用。采取行动前务必先征得确认。
• 物化会占用存储和计算资源。 端点不再需要物化时，成本最低的处理方式是调用 endpoint-update 并设置 is_materialized: false，而不是删除端点。
• 未激活 ≠ 过时。 is_active: false 表示端点已被主动关闭。除非用户确认端点确实已弃用，否则不要建议删除。