exploring-endpoint-execution-logs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Exploring endpoint execution logs

探索端点执行日志

Every endpoint run emits one execution log entry to PostHog's

log_entries

store. This skill reads those entries for a specific endpoint to answer "what happened when it ran?". It is the log-level counterpart to

diagnosing-endpoint-performance

(which reasons about cache/materialisation strategy from config and

query_log

每次端点运行都会向PostHog的

log_entries

存储中写入一条执行日志条目。本技能读取特定端点的这些条目，以回答“运行时发生了什么？”的问题。它是

diagnosing-endpoint-performance

（从配置和

query_log

分析缓存/物化策略）在日志层面的对应技能。

When to use this skill

何时使用本技能

"Why is my endpoint failing / erroring?"
"Show me the logs / recent runs for endpoint X"
"Did the last run hit cache? How many rows did it return?"
"What happened the last time endpoint Y ran?"

If the question is "this endpoint is slow, what should I change?", use

diagnosing-endpoint-performance

. If it's project-wide ("what can I clean up?"), use

auditing-endpoints

“为什么我的端点运行失败/报错？”
“展示端点X的日志/最近运行记录”
“上次运行是否命中缓存？返回了多少行数据？”
“端点Y上次运行时发生了什么？”

如果问题是“这个端点运行缓慢，我应该做什么调整？”，请使用

diagnosing-endpoint-performance

。如果是项目范围的问题（“我可以清理哪些内容？”），请使用

auditing-endpoints

。

What an execution log entry looks like

执行日志条目的格式

Each run produces exactly one entry. The level is

INFO

on success and

ERROR

on failure, and the message carries the extra data as searchable

key=value

tokens:

text

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

Token meanings:

Token	Values	Meaning
`path`	`materialized` / `inline` / `ducklake` / `ducklake_fallback`	Which execution path ran
`cache`	`hit` / `miss`	Whether the query result cache was used (omitted for ducklake)
`duration_ms`	integer	Wall-clock execution time
`rows`	integer	Number of result rows returned
`version`	integer	Which endpoint version ran
`error`	e.g. `ResolutionError` , `HogVMException`	Error class / HogQL code name (failures only)

Each run gets a distinct

instance_id

, so logs group one-per-execution in the viewer.

每次运行都会生成恰好一条日志条目。成功时级别为

INFO

，失败时为

ERROR

，消息中携带可搜索的

key=value

格式扩展数据：

text

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

各字段含义：

字段（Token）	取值范围	含义
`path`	`materialized` / `inline` / `ducklake` / `ducklake_fallback`	运行的执行路径类型
`cache`	`hit` / `miss`	是否使用了查询结果缓存（ducklake路径不包含此字段）
`duration_ms`	整数	实际执行时间（毫秒）
`rows`	整数	返回的结果行数
`version`	整数	运行的端点版本号
`error`	例如 `ResolutionError` 、 `HogVMException`	错误类/HogQL代码名称（仅失败条目包含）

每次运行都有一个唯一的

instance_id

，因此在日志查看器中，每条日志对应一次执行。

Available tools

可用工具

Tool	Purpose
`endpoint-logs`	Primary. Execution log entries for one endpoint by name. Filter by level, search, time range, instance_id; `limit` up to 500.
`endpoint-get`	Endpoint config for context (current version, materialisation, query kind)
`execute-sql`	Fallback / aggregation directly against `log_entries` ( `log_source='endpoints'` )

工具名称	用途
`endpoint-logs`	核心工具。按名称查询单个端点的执行日志条目。可按级别、关键词、时间范围、instance_id过滤； `limit` 参数最大可设为500。
`endpoint-get`	获取端点配置信息以了解上下文（当前版本、物化方式、查询类型）
`execute-sql`	备选/聚合工具，直接查询 `log_entries` 表（需指定 `log_source='endpoints'` ）

Filtering

过滤规则

endpoint-logs

exposes the standard log filters:

level — comma-separated, e.g.
```
ERROR
```
to see only failed runs, or
```
INFO,ERROR
```
for all.
search — case-insensitive substring over the message. Because the extra data is in
```
key=value
```
tokens, you can search
```
cache=miss
```
,
```
path=inline
```
,
```
error=ResolutionError
```
, or a specific
```
version=3
```
.
after / before — ISO timestamps to bound the time range.
instance_id — pin a single execution.
limit — 1–500 (default 50).

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）。

Workflow

工作流程

Identify the endpoint by name. If given a URL, parse it from
```
/api/projects/{team_id}/endpoints/{name}/run
```
.
Start broad:
```
endpoint-logs
```
for the endpoint with a recent time range. Skim levels and tokens.
Narrow to the symptom:
- Failures →
```
level=ERROR
```
  ; read the
```
error=
```
  token and
```
path=
```
  to see where it broke.
- Cache concerns →
```
search=cache=miss
```
  to see how often runs miss cache.
- Wrong results → compare
```
rows=
```
  across runs, and
```
version=
```
  to spot a regression after a version bump.

For counts/trends across many runs (e.g. error rate over a week), drop to

execute-sql

against

log_entries

sql

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

Get the endpoint UUID from

endpoint-get

(the

log_source_id

is the endpoint id, not its name).

Summarize: what's failing, since when, on which version/path, and whether it's a config issue (hand off to
```
diagnosing-endpoint-performance
```
) or a query bug.

确定端点名称。如果提供的是URL，从
```
/api/projects/{team_id}/endpoints/{name}/run
```
中解析端点名称。
先进行宽泛查询：使用
```
endpoint-logs
```
查询该端点近期的日志，浏览日志级别和字段信息。
根据症状缩小范围：
- 失败问题 → 设置
```
level=ERROR
```
  ；查看
```
error=
```
  字段和
```
path=
```
  字段以确定故障位置。
- 缓存相关问题 → 设置
```
search=cache=miss
```
  以查看未命中缓存的运行频率。
- 结果异常问题 → 对比不同运行的
```
rows=
```
  字段，结合
```
version=
```
  字段排查版本更新后的回归问题。

如需统计多次运行的趋势（例如一周内的错误率），使用

execute-sql

查询

log_entries

表：

sql

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

端点UUID可通过

endpoint-get

获取（

log_source_id

为端点ID，而非端点名称）。

总结结论：明确故障内容、起始时间、涉及的版本/路径，并判断是配置问题（转交至
```
diagnosing-endpoint-performance
```
处理）还是查询Bug。

Example interaction

交互示例

text

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?"

text

用户：“weekly_signups从今天早上开始报错了”

Agent步骤：
- 调用endpoint-logs查询weekly_signups，设置level=ERROR，after=<今天早上>
  → 返回多条“Endpoint execution failed · path=inline error=ResolutionError version=5”
- 调用endpoint-get查询weekly_signups → 当前版本为v5（今日更新）
- 调用endpoint-logs查询weekly_signups，设置level=INFO，before=<今天早上>
  → 之前的运行记录：“path=inline cache=hit ... version=4”均成功

- 回复：“今日早上更新的v5版本在inline路径下运行失败，报错为ResolutionError——无法解析表或字段引用。v4版本运行正常。这看起来是新版本中的查询语句存在问题。需要我获取v5版本的查询语句（通过endpoint-versions）来修复，还是回滚到v4版本？”

Important notes

重要说明

One entry per run. Don't expect step-by-step traces — endpoints log a single completion line. The detail lives in the tokens, not in multiple lines.
log_source_id
is the endpoint UUID, not the name. For
```
execute-sql
```
, fetch it via
```
endpoint-get
```
first.
Logs are retained ~90 days (the
```
log_entries
```
TTL). Older runs won't appear.
Execution logs ≠ query performance.
```
endpoint-logs
```
tells you what happened and why a run failed; for "should I materialise / bump cache TTL?" use
```
diagnosing-endpoint-performance
```
, which reasons over config and
```
query_log
```
cost metrics.
Best-effort emission. A log line is emitted after each run but never blocks it — if a run succeeded for the caller but no log shows, the emit was dropped, not the query.

每次运行对应一条日志。不要期望得到分步追踪信息——端点仅记录一条完成状态日志。详细信息存储在字段中，而非多行日志。
log_source_id
是端点UUID，而非端点名称。使用
```
execute-sql
```
前，需先通过
```
endpoint-get
```
获取该ID。
日志保留约90天（
```
log_entries
```
表的TTL）。更早的运行记录无法查询。
执行日志≠查询性能。
```
endpoint-logs
```
用于告知运行时发生的情况及失败原因；若需解决“是否应该启用物化/调整缓存TTL？”这类问题，请使用
```
diagnosing-endpoint-performance
```
，它会基于配置和
```
query_log
```
的成本指标进行分析。
日志为尽力发送。每条运行记录后都会尝试发送日志，但不会阻塞运行——如果用户侧显示运行成功但无日志记录，说明日志发送失败，而非查询执行失败。