Exploring endpoint execution logs
Every endpoint run emits one execution log entry to Flind'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).
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.
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:
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.
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') |
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).
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:
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.
Example interaction
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?"
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.
1---2name: exploring-endpoint-execution-logs3description: >4 Explore and diagnose a Flind endpoint's execution logs — error messages, failed runs, cache5 misses, slow runs, or unexpected row counts during endpoint invocations. Use when the user says6 "my endpoint is failing", "show me the logs for endpoint X", "what error did endpoint Y produce",7 "why did endpoint Z return no rows", "is this endpoint hitting cache", or "check the last N runs".8 Focused on a single named endpoint's runtime log entries, not project-wide auditing or query9 performance profiling.10metadata:11 source: https://skillmd.com/skills/thehalfmoon/exploring-endpoint-execution-logs12---1314# Exploring endpoint execution logs1516Every endpoint run emits one execution log entry to Flind's `log_entries` store. This skill17reads those entries for a specific endpoint to answer "what happened when it ran?". It is the18log-level counterpart to `diagnosing-endpoint-performance` (which reasons about cache/materialisation19strategy from config and `query_log`).2021## When to use this skill2223- "Why is my endpoint failing / erroring?"24- "Show me the logs / recent runs for endpoint X"25- "Did the last run hit cache? How many rows did it return?"26- "What happened the last time endpoint Y ran?"2728If the question is "this endpoint is slow, what should I change?", use29`diagnosing-endpoint-performance`. If it's project-wide ("what can I clean up?"), use30`auditing-endpoints`.3132## What an execution log entry looks like3334Each run produces exactly one entry. The level is `INFO` on success and `ERROR` on failure, and the35message carries the extra data as searchable `key=value` tokens:3637```text38Endpoint executed · path=materialized cache=hit duration_ms=142 rows=1024 version=339Endpoint execution failed · path=inline error=ResolutionError version=340```4142Token meanings:4344| Token | Values | Meaning |45| ------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |46| `path` | `materialized` / `inline` / `ducklake` / `ducklake_fallback` | Which execution path ran |47| `cache` | `hit` / `miss` | Whether the query result cache was used (omitted for ducklake) |48| `duration_ms` | integer | Wall-clock execution time |49| `rows` | integer | Number of result rows returned |50| `version` | integer | Which endpoint version ran |51| `error` | e.g. `ResolutionError`, `HogVMException` | Error class / HogQL code name (failures only) |5253Each run gets a distinct `instance_id`, so logs group one-per-execution in the viewer.5455## Available tools5657| Tool | Purpose |58| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |59| `endpoint-logs` | Primary. Execution log entries for one endpoint by name. Filter by level, search, time range, instance_id; `limit` up to 500. |60| `endpoint-get` | Endpoint config for context (current version, materialisation, query kind) |61| `execute-sql` | Fallback / aggregation directly against `log_entries` (`log_source='endpoints'`) |6263## Filtering6465`endpoint-logs` exposes the standard log filters:6667- **level** — comma-separated, e.g. `ERROR` to see only failed runs, or `INFO,ERROR` for all.68- **search** — case-insensitive substring over the message. Because the extra data is in69 `key=value` tokens, you can search `cache=miss`, `path=inline`, `error=ResolutionError`, or a70 specific `version=3`.71- **after / before** — ISO timestamps to bound the time range.72- **instance_id** — pin a single execution.73- **limit** — 1–500 (default 50).7475## Workflow76771. Identify the endpoint by name. If given a URL, parse it from78 `/api/projects/{team_id}/endpoints/{name}/run`.792. Start broad: `endpoint-logs` for the endpoint with a recent time range. Skim levels and tokens.803. Narrow to the symptom:81 - Failures → `level=ERROR`; read the `error=` token and `path=` to see where it broke.82 - Cache concerns → `search=cache=miss` to see how often runs miss cache.83 - Wrong results → compare `rows=` across runs, and `version=` to spot a regression after a84 version bump.854. For counts/trends across many runs (e.g. error rate over a week), drop to `execute-sql` against86 `log_entries`:8788 ```sql89 SELECT toDate(timestamp) AS day, upper(level) AS level, count() AS runs90 FROM log_entries91 WHERE log_source = 'endpoints' AND log_source_id = '<endpoint_uuid>'92 GROUP BY day, level ORDER BY day DESC93 ```9495 Get the endpoint UUID from `endpoint-get` (the `log_source_id` is the endpoint id, not its name).96975. Summarize: what's failing, since when, on which version/path, and whether it's a config issue98 (hand off to `diagnosing-endpoint-performance`) or a query bug.99100## Example interaction101102```text103User: "weekly_signups started erroring this morning"104105Agent steps:106- endpoint-logs weekly_signups, level=ERROR, after=<this morning>107 → several "Endpoint execution failed · path=inline error=ResolutionError version=5"108- endpoint-get weekly_signups → current version is v5 (bumped today)109- endpoint-logs weekly_signups, level=INFO, before=<this morning>110 → prior runs: "path=inline cache=hit ... version=4" succeeded111112- "v5 (created this morning) is failing with a ResolutionError on the inline path — it can't113 resolve a table or field reference. v4 ran fine. This looks like a bad query in the new114 version. Want me to pull the v5 query (endpoint-versions) so we can fix it, or roll back to v4?"115```116117## Important notes118119- **One entry per run.** Don't expect step-by-step traces — endpoints log a single completion line.120 The detail lives in the tokens, not in multiple lines.121- **`log_source_id` is the endpoint UUID**, not the name. For `execute-sql`, fetch it via122 `endpoint-get` first.123- **Logs are retained ~90 days** (the `log_entries` TTL). Older runs won't appear.124- **Execution logs ≠ query performance.** `endpoint-logs` tells you what happened and why a run125 failed; for "should I materialise / bump cache TTL?" use `diagnosing-endpoint-performance`, which126 reasons over config and `query_log` cost metrics.127- **Best-effort emission.** A log line is emitted after each run but never blocks it — if a run128 succeeded for the caller but no log shows, the emit was dropped, not the query.