Exploring Endpoint Execution Logs

1---
2name: exploring-endpoint-execution-logs
3description: >
4  Explore and diagnose a PostHog endpoint's execution logs — error messages, failed runs, cache
5  misses, slow runs, or unexpected row counts during endpoint invocations. Use when the user says
6  "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 query
9  performance profiling.
10---
11 
12# Exploring endpoint execution logs
13 
14Every endpoint run emits one execution log entry to PostHog's `log_entries` store. This skill
15reads those entries for a specific endpoint to answer "what happened when it ran?". It is the
16log-level counterpart to `diagnosing-endpoint-performance` (which reasons about cache/materialisation
17strategy from config and `query_log`).
18 
19## When to use this skill
20 
21- "Why is my endpoint failing / erroring?"
22- "Show me the logs / recent runs for endpoint X"
23- "Did the last run hit cache? How many rows did it return?"
24- "What happened the last time endpoint Y ran?"
25 
26If the question is "this endpoint is slow, what should I change?", use
27`diagnosing-endpoint-performance`. If it's project-wide ("what can I clean up?"), use
28`auditing-endpoints`.
29 
30## What an execution log entry looks like
31 
32Each run produces exactly one entry. The level is `INFO` on success and `ERROR` on failure, and the
33message carries the extra data as searchable `key=value` tokens:
34 
35```text
36Endpoint executed · path=materialized cache=hit duration_ms=142 rows=1024 version=3
37Endpoint execution failed · path=inline error=ResolutionError version=3
38```
39 
40Token meanings:
41 
42| Token         | Values                                                       | Meaning                                                        |
43| ------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
44| `path`        | `materialized` / `inline` / `ducklake` / `ducklake_fallback` | Which execution path ran                                       |
45| `cache`       | `hit` / `miss`                                               | Whether the query result cache was used (omitted for ducklake) |
46| `duration_ms` | integer                                                      | Wall-clock execution time                                      |
47| `rows`        | integer                                                      | Number of result rows returned                                 |
48| `version`     | integer                                                      | Which endpoint version ran                                     |
49| `error`       | e.g. `ResolutionError`, `HogVMException`                     | Error class / HogQL code name (failures only)                  |
50 
51Each run gets a distinct `instance_id`, so logs group one-per-execution in the viewer.
52 
53## Available tools
54 
55| Tool            | Purpose                                                                                                                       |
56| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
57| `endpoint-logs` | Primary. Execution log entries for one endpoint by name. Filter by level, search, time range, instance_id; `limit` up to 500. |
58| `endpoint-get`  | Endpoint config for context (current version, materialisation, query kind)                                                    |
59| `execute-sql`   | Fallback / aggregation directly against `log_entries` (`log_source='endpoints'`)                                              |
60 
61## Filtering
62 
63`endpoint-logs` exposes the standard log filters:
64 
65- **level** — comma-separated, e.g. `ERROR` to see only failed runs, or `INFO,ERROR` for all.
66- **search** — case-insensitive substring over the message. Because the extra data is in
67  `key=value` tokens, you can search `cache=miss`, `path=inline`, `error=ResolutionError`, or a
68  specific `version=3`.
69- **after / before** — ISO timestamps to bound the time range.
70- **instance_id** — pin a single execution.
71- **limit** — 1–500 (default 50).
72 
73## Workflow
74 
751. Identify the endpoint by name. If given a URL, parse it from
76   `/api/projects/{team_id}/endpoints/{name}/run`.
772. Start broad: `endpoint-logs` for the endpoint with a recent time range. Skim levels and tokens.
783. Narrow to the symptom:
79   - Failures → `level=ERROR`; read the `error=` token and `path=` to see where it broke.
80   - Cache concerns → `search=cache=miss` to see how often runs miss cache.
81   - Wrong results → compare `rows=` across runs, and `version=` to spot a regression after a
82     version bump.
834. For counts/trends across many runs (e.g. error rate over a week), drop to `execute-sql` against
84   `log_entries`:
85 
86   ```sql
87   SELECT toDate(timestamp) AS day, upper(level) AS level, count() AS runs
88   FROM log_entries
89   WHERE log_source = 'endpoints' AND log_source_id = '<endpoint_uuid>'
90   GROUP BY day, level ORDER BY day DESC
91   ```
92 
93   Get the endpoint UUID from `endpoint-get` (the `log_source_id` is the endpoint id, not its name).
94 
955. Summarize: what's failing, since when, on which version/path, and whether it's a config issue
96   (hand off to `diagnosing-endpoint-performance`) or a query bug.
97 
98## Example interaction
99 
100```text
101User: "weekly_signups started erroring this morning"
102 
103Agent steps:
104- endpoint-logs weekly_signups, level=ERROR, after=<this morning>
105  → several "Endpoint execution failed · path=inline error=ResolutionError version=5"
106- endpoint-get weekly_signups → current version is v5 (bumped today)
107- endpoint-logs weekly_signups, level=INFO, before=<this morning>
108  → prior runs: "path=inline cache=hit ... version=4" succeeded
109 
110- "v5 (created this morning) is failing with a ResolutionError on the inline path — it can't
111   resolve a table or field reference. v4 ran fine. This looks like a bad query in the new
112   version. Want me to pull the v5 query (endpoint-versions) so we can fix it, or roll back to v4?"
113```
114 
115## Important notes
116 
117- **One entry per run.** Don't expect step-by-step traces — endpoints log a single completion line.
118  The detail lives in the tokens, not in multiple lines.
119- **`log_source_id` is the endpoint UUID**, not the name. For `execute-sql`, fetch it via
120  `endpoint-get` first.
121- **Logs are retained ~90 days** (the `log_entries` TTL). Older runs won't appear.
122- **Execution logs ≠ query performance.** `endpoint-logs` tells you what happened and why a run
123  failed; for "should I materialise / bump cache TTL?" use `diagnosing-endpoint-performance`, which
124  reasons over config and `query_log` cost metrics.
125- **Best-effort emission.** A log line is emitted after each run but never blocks it — if a run
126  succeeded for the caller but no log shows, the emit was dropped, not the query.
127