exploring-endpoint-execution-logs

探索端点执行日志

每次端点运行都会在 PostHog 的 log_entries 存储中生成一条执行日志。本技能 会读取指定端点的日志条目，回答“运行时发生了什么？”。它是 diagnosing-endpoint-performance 的日志级对应技能，后者会根据配置和 query_log 推断缓存／物化 策略。

何时使用此技能

• “为什么我的端点运行失败／报错了？”
• “显示端点 X 的日志／最近运行记录。”
• “上次运行命中缓存了吗？返回了多少行？”
• “端点 Y 上次运行时发生了什么？”

如果问题是“这个端点很慢，我应该更改什么？”，请使用 diagnosing-endpoint-performance。如果问题涉及整个项目（“我可以清理什么？”），请使用 auditing-endpoints。

执行日志条目的格式

每次运行恰好生成一条条目。成功时级别为 INFO，失败时为 ERROR，消息中会以可搜索的 key=value 令牌形式携带额外数据：

Endpoint executed · path=materialized cache=hit duration_ms=142 rows=1024 version=3
Endpoint execution failed · path=inline error=ResolutionError version=3

令牌含义：

令牌	值	含义
path	materialized / inline / ducklake / ducklake_fallback	执行时使用的路径
cache	hit / miss	是否使用了查询结果缓存（ducklake 时省略）
duration_ms	integer	执行耗时
rows	integer	返回的结果行数
version	integer	运行的端点版本
error	例如 ResolutionError、HogVMException	错误类／HogQL 代码名称（仅失败时）

每次运行都会获得一个不同的 instance_id，因此在查看器中，日志会按每次执行一条进行分组。

可用工具

工具	用途
endpoint-logs	主要工具。按名称查询单个端点的执行日志条目。可按级别、搜索内容、时间范围和 instance_id 筛选；limit 最高为 500。
endpoint-get	获取端点配置作为上下文（当前版本、物化方式、查询类型）
execute-sql	后备方案／直接针对 log_entries 进行聚合（log_source='endpoints'）

筛选

endpoint-logs 提供标准日志筛选条件：

• level — 逗号分隔，例如使用 ERROR 仅查看失败的运行，或使用 INFO,ERROR 查看全部运行。
• search — 对消息进行不区分大小写的子字符串搜索。由于额外数据以 key=value 令牌形式存储，你可以搜索 cache=miss、path=inline、error=ResolutionError，或指定的 version=3。
• after / before — 用于限定时间范围的 ISO 时间戳。
• instance_id — 指定单次执行。
• limit — 1–500（默认值为 50）。

工作流

1. 按名称识别端点。如果给出 URL，从 /api/projects/{team_id}/endpoints/{name}/run 中解析。

2. 从宽泛范围开始：对该端点使用近期时间范围查询 endpoint-logs。浏览日志级别和令牌。

3. 根据症状缩小范围：

   • 失败 → 使用 level=ERROR；查看 error= 令牌和 path=，了解故障发生的位置。
   • 缓存问题 → 使用 search=cache=miss，查看运行未命中缓存的频率。
   • 结果错误 → 比较各次运行的 rows=，并查看 version=，以发现版本升级后是否出现回归。

4. 要统计多次运行的数量或趋势（例如一周内的错误率），请使用 execute-sql 查询 log_entries：

   SELECT toDate(timestamp) AS day, upper(level) AS level, count() AS runs
   FROM log_entries
   WHERE log_source = 'endpoints' AND log_source_id = '<endpoint_uuid>'
   GROUP BY day, level ORDER BY day DESC
   

   通过 endpoint-get 获取端点 UUID（log_source_id 是端点 ID，不是名称）。

5. 总结：什么出现了故障、从何时开始、涉及哪个版本/路径，以及是否属于配置问题 （转交给 diagnosing-endpoint-performance）或查询错误。

交互示例

User: "weekly_signups started erroring this morning"

Agent steps:
- endpoint-logs weekly_signups, level=ERROR, after=<this morning>
  → several "Endpoint execution failed · path=inline error=ResolutionError version=5"
- endpoint-get weekly_signups → current version is v5 (bumped today)
- endpoint-logs weekly_signups, level=INFO, before=<this morning>
  → prior runs: "path=inline cache=hit ... version=4" succeeded

- "v5 (created this morning) is failing with a ResolutionError on the inline path — it can't
   resolve a table or field reference. v4 ran fine. This looks like a bad query in the new
   version. Want me to pull the v5 query (endpoint-versions) so we can fix it, or roll back to v4?"

重要说明

• 每次运行对应一条日志。 不要期待逐步跟踪记录——端点只记录一条完成日志。 详细信息在令牌中，而非多条日志中。
• log_source_id 是端点 UUID，不是名称。使用 execute-sql 时，请先通过 endpoint-get 获取它。
• 日志保留约 90 天（log_entries 的 TTL）。更早的运行不会显示。
• 执行日志 ≠ 查询性能。 endpoint-logs 会告诉你发生了什么，以及运行失败的原因；要了解“是否应该物化 / 延长缓存 TTL？”，请使用 diagnosing-endpoint-performance，它会根据配置和 query_log 成本指标进行判断。
• 尽力写入。 每次运行后都会写入一条日志，但不会阻塞运行——如果调用方的运行成功，却没有显示日志，则是日志写入被丢弃，而不是查询未执行。