Back to Details

auditing-endpoints

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auditing endpoints

端点审计

This skill produces a project-wide audit of the Endpoints product. Use it when the user wants to find what to clean up — unused endpoints, failing materialisations, materialised versions that nobody calls any more. It does not modify anything; it reports.
The deeper investigation per endpoint is 
diagnosing-endpoint-performance
. The audit's job is to find candidates and hand off.
本技能可对Endpoints产品进行全项目审计。当用户想要 找出需要清理的内容时使用——包括未使用的端点、执行失败的物化、无人再调用的物化版本。该技能仅生成报告，不会修改任何内容。
针对单个端点的深度排查可使用
diagnosing-endpoint-performance
技能。本审计技能的职责是找出待处理候选对象并转交至对应技能。

When to use this skill

何时使用本技能

  • "Audit my endpoints" / "What endpoints can I clean up?"
  • The user is taking over a project and wants to know what they've inherited
  • A periodic review (monthly / quarterly) of endpoint sprawl
  • The user is over a materialisation cost budget and wants to know what to disable
The dedicated tools give a fast endpoint-level view. For call frequency, recency, and cost over time, query the 
query_log
table with 
execute-sql
(endpoint-level). Per-version recency comes from 
endpoint-versions
— each version carries its own 
last_executed_at
.
  • “审计我的端点” / “我可以清理哪些端点？”
  • 用户接管项目后，想要了解已继承的端点情况
  • 定期（每月/每季度）检查端点膨胀问题
  • 用户超出物化成本预算，想要了解需禁用的内容
专用工具可快速提供端点级视图。如需查看调用频率、最近调用时间及随时间变化的成本，可使用
execute-sql
（端点级）查询
query_log
表。各版本的最近调用时间可从
endpoint-versions
获取——每个版本都有自己的
last_executed_at
字段。

Available tools

可用工具

ToolWhat it's for
execute-sql
(HogQL)		Primary read path. Query 
system.data_modeling_endpoints
for metadata (name, is_active, current_version, derived_from_insight, last_executed_at) and 
query_log
for endpoint-level usage (call counts, recency, duration, bytes)
endpoint-materialization-status
Per endpoint: is materialisation eligible, current status, last run, last error (not in the system tables — use this tool)
endpoint-versions
All versions for one endpoint, latest first, with each version's query, materialisation state, and 
last_executed_at
endpoint-update
Write path — disable (
is_active: false
) or unmaterialise (
is_materialized: false
) after the user confirms
agent-feedback
Tell the PostHog team what's missing or confusing in this flow so the product and skill improve
Prefer reading from the system tables over the 
endpoints-get-all
/ 
endpoint-get
tools — one SQL query returns the whole inventory and lets you join metadata to usage in 
query_log
.
工具名称用途
execute-sql
(HogQL)		主要读取路径。查询
system.data_modeling_endpoints
获取元数据（名称、是否激活、当前版本、是否源自洞察、最后执行时间），并查询
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
中的使用情况关联。

What counts as an issue

问题判定标准

CategoryTriggerTypical action
Never calledNo rows in 
query_log
for the endpoint (personal-API-key calls only)		Confirm with the user, then disable
Stale
query_log
shows the last call more than 30 days ago		Confirm with the user; often safe to disable
Inactive
is_active = 0
in 
system.data_modeling_endpoints
Verify intent; if abandoned, delete
Failing materialisation
endpoint-materialization-status
returns 
Failed
with an error		Hand off to 
diagnosing-endpoint-performance
Unused materialised versionA materialised version whose 
last_executed_at
(from 
endpoint-versions
) is null or long stale		Unmaterialise that version, or roll to a newer one
Drifted versionsMany versions exist (query changed repeatedly)History noise — not an issue, but worth noting
Usage counts only personal-API-key calls — an endpoint exercised solely from the Playground tab or the app will look unused. Per-version 
last_executed_at
is recorded only for runs since that tracking was added, so a version can read null while still being used; always confirm before removing.
类别触发条件典型操作
从未被调用该端点在
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
仅记录该跟踪功能启用后的运行情况，因此版本的该字段为空并不代表未被使用；删除前务必与用户确认。

Workflow

工作流程

1. List endpoints and their metadata

1. 列出端点及其元数据

One 
execute-sql
query gets the whole inventory from 
system.data_modeling_endpoints
:
sql
SELECT name, is_active, current_version, derived_from_insight, last_executed_at
FROM system.data_modeling_endpoints
ORDER BY name
No rows → the project has no endpoints; say so and stop. Don't invent issues. (The 
last_executed_at
column here is a convenience endpoint-level timestamp; for call frequency and cost, use 
query_log
in the next step.)
通过一次
execute-sql
查询从
system.data_modeling_endpoints
获取完整清单：
sql
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. Pull usage from 
query_log

2. 从
query_log
获取使用情况

query_log
records every personal-API-key call, tagged with the endpoint name. One query gives recency and call counts across all endpoints:
sql
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
Cross-reference with step 1:
  • In metadata, absent from 
    query_log
     → never called via API key
  • Last call more than 30 days ago → stale
query_log
also exposes 
query_duration_ms
, 
read_rows
, and 
read_bytes
per call — useful to flag expensive endpoints in the same pass. This is endpoint-level; per-version recency comes from 
endpoint-versions
(step 3).
query_log
记录了每一次个人API密钥调用，并标记了端点名称。一次查询即可获取所有端点的最近调用时间和调用次数：
sql
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. Check materialisation health and unused versions

3. 检查物化健康状态及未使用版本

For each materialised endpoint, call 
endpoint-materialization-status
(this isn't in the system tables). Surface any with 
status: "Failed"
separately — these are active failures, not staleness.
Then call 
endpoint-versions
and read each version's 
last_executed_at
: a materialised version that's null or long stale is an unused-materialised-version candidate. Treat this as a lead, not proof — per-version recency only counts API-key runs since tracking was added, so confirm with the user before unmaterialising.
针对每个已物化的端点，调用
endpoint-materialization-status
（该信息不在系统表中）。单独标记状态为
status: "Failed"
的端点——这些是活跃故障，而非过期问题。
然后调用
endpoint-versions
并读取每个版本的
last_executed_at
字段：已物化且该字段为空或已过期很久的版本是未使用物化版本的候选对象。将其视为线索而非定论——各版本的最近调用时间仅统计跟踪功能启用后的API密钥调用，因此取消物化前务必与用户确认。

4. Present the audit

4. 呈现审计报告

Render a prioritised report grouped by category. Don't dump raw JSON; use a readable table per section:
text
undefined
生成按类别分组的优先级报告。请勿直接输出原始JSON；每个部分使用易读的表格格式：
text
undefined

Endpoints audit — 9 issues

端点审计 — 9项问题

🔴 Failing materialisations (1)

🔴 物化执行失败（1项）

  • weekly_revenue (v3) — Failed 2h ago, "Column 'event_date' does not exist" → hand off to diagnosing-endpoint-performance
  • weekly_revenue (v3) — 2小时前执行失败，错误信息："Column 'event_date' does not exist" → 转交至diagnosing-endpoint-performance技能处理

🟠 Never called via API key (3)

🟠 从未通过API密钥调用（3项）

  • internal_admin_query — created 5 months ago
  • legacy_signup_funnel — created 1 year ago, materialised
  • experiment_arm_lookup — created 9 months ago
  • internal_admin_query — 创建于5个月前
  • legacy_signup_funnel — 创建于1年前，已物化
  • experiment_arm_lookup — 创建于9个月前

🟠 Unused materialised versions (2) [from endpoint-versions]

🟠 未使用的物化版本（2项） [来自endpoint-versions]

  • monthly_active_users — v3 materialised, last_executed_at null (currently on v4 — unmaterialise v3)
  • order_summary — v1 materialised, last_executed_at null
  • monthly_active_users — v3已物化，last_executed_at为空（当前使用v4 — 取消v3的物化）
  • order_summary — v1已物化，last_executed_at为空

🟡 Stale (3)

🟡 已过期（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

The exact format is less important than: prioritised, grouped, actionable, and hand-off
clear.
  • holiday_promo_2024 — 最后一次调用发生在4个月前
  • ab_test_phase_1 — 最后一次调用发生在2个月前
  • daily_revenue_cohort — 最后一次调用发生在45天前
建议处理顺序：
  1. 排查物化执行失败问题（会阻碍新鲜数据生成）
  2. 取消未使用版本的物化（释放存储和计算资源）
  3. 禁用从未被调用的端点（需用户确认）
  4. 与用户一起审核已过期端点

具体格式不重要，关键是：优先级明确、分组清晰、可执行、转交关系明确。

5. Offer the next step

5. 提供下一步选项

End with a clear question, not a decision:
  • "Want me to unmaterialise the unused versions?" — needs 
    endpoint-update
    with 
    is_materialized: false
    per version
  • "Want me to disable the never-called endpoints?" — needs 
    endpoint-update
    with 
    is_active: false
  • "Want me to dig into the failing materialisation?" — hands off to 
    diagnosing-endpoint-performance
Never act from the audit alone. Disabling or unmaterialising affects external API consumers; always confirm before modifying.
以明确的问题结尾，而非直接决策：
  • “需要我取消未使用版本的物化吗？”——需针对每个版本调用
    endpoint-update
    并设置
    is_materialized: false
  • “需要我禁用从未被调用的端点吗？”——需调用
    endpoint-update
    并设置
    is_active: false
  • “需要我深入排查物化执行失败的问题吗？”——转交至
    diagnosing-endpoint-performance
    技能
切勿仅根据审计结果直接操作。禁用或取消物化会影响外部API消费者；修改前务必确认。

Example interaction

交互示例

text
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?"
text
用户：“审计我的端点”

Agent步骤：
- 对system.data_modeling_endpoints执行execute-sql查询 → 12个端点（4个已物化）
- 对query_log按名称分组执行execute-sql查询 → 8个端点有调用记录
- 对每个已物化端点调用endpoint-materialization-status → 1个执行失败
- 对已物化端点调用endpoint-versions → order_summary v2的last_executed_at为空

- 报告：
  “在12个端点中发现6项需关注的内容：

   🔴 物化执行失败（1项）
   - monthly_active_users (v2) — 物化于昨日失败，错误信息：
     'memory limit exceeded'。该端点仍可在线调用，但响应速度会变慢。

   🟠 从未通过API密钥调用（3项）
   - legacy_funnel_v1 — 创建于11个月前
   - test_export — 创建于3个月前
   - admin_dump — 创建于8个月前，已物化（造成资源浪费）

   🟠 未使用的物化版本（1项）  [来自endpoint-versions]
   - order_summary v2 — 已物化但last_executed_at为空
     当前使用v3。取消v2的物化大概率是安全的。

   🟡 已过期（1项）
   - holiday_2024 — 最后一次调用发生在5个月前

   注意：使用次数仅统计个人API密钥调用；Playground和
   仪表盘中的运行未被统计。各版本的最近调用时间来自
   endpoint-versions，数据可能不完整。禁用前请确认。

   需要我先排查物化执行失败的问题，还是先清理未使用的版本？"

Important notes

重要说明

  • The audit is read-only. Never call destructive tools from this flow. Hand off or confirm before any modification.
  • Empty = healthy. Don't pad an empty report with theoretical issues. "Nothing to clean up" is a good answer.
  • Read with SQL, drill in with the version tool. 
    system.data_modeling_endpoints
    (metadata) and 
    query_log
    (endpoint-level call counts, recency, cost) via 
    execute-sql
    answer most of the audit. Per-version recency comes from 
    endpoint-versions
    (each version's 
    last_executed_at
    ).
  • API-key-only scope. Usage only counts personal-API-key calls. An endpoint exercised only from the Playground tab or the app will look unused. Always confirm before acting.
  • Materialisation costs storage and compute. When an endpoint no longer needs materialisation, the cheapest fix is 
    endpoint-update
    with 
    is_materialized: false
    — not deleting the endpoint.
  • Inactive ≠ stale. An endpoint with 
    is_active: false
    was deliberately turned off. Don't recommend deletion unless the user confirms it's truly abandoned.
  • 审计为只读操作。切勿在此流程中调用破坏性工具。修改前需转交至对应技能或获得用户确认。
  • 无结果=健康。请勿在无问题的报告中添加理论性问题。“无需清理”是合理结果。
  • 用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
    的端点是被故意关闭的。除非用户确认已废弃，否则不建议删除。