← Better StackCONTENT HISTORY
WHAT CHANGED
Update to Better Stack
Snapshot Nov 11, 2026 · 06:08 UTC · version 1.1.3
Collection source: downloaded plugin package.
First saved snapshot
No earlier snapshot is available to establish a change.
Save Better Stack and check future changes in Following.
Up to 3 plugins free · no card required.
Compare saved observations
Download comparison JSONFull technical diff · 0 changed fields
Full snapshot data
{
"description": "Load BEFORE querying Better Stack exception or error-pattern data with SQL - exception counts, trends, first/last occurrence, affected users, raw stack traces. Contains instructions for querying errors/exceptions.",
"included_files": [],
"name": "errors-query",
"skill_md_contents": "---\nname: errors-query\ndescription: Load BEFORE querying Better Stack exception or error-pattern data with SQL - exception counts, trends, first/last occurrence, affected users, raw stack traces. Contains instructions for querying errors/exceptions.\n---\n\n# Querying exceptions (Errors sources)\n\n## Where the query runs\n\nBetter Stack runs SQL in two places, and the query text differs:\n\n- **Dashboard charts and chart alerts** (`add_chart_to_dashboard`, `edit_chart`, `create_chart_alert`): write the query as this skill shows it, with the template variables `{{source}}`, `{{time}}`, `{{start_time}}` and `{{end_time}}`. The dashboard resolves them. Chart queries always read the source's metrics collection.\n- **Ad-hoc queries** (`query`, `render_chart`): there are no template variables. First call the help tool for the data type with the source ID (`query_help` for logs and spans, `metrics_query_help` for metrics, `errors_query_help` for errors): it names the source's collections and the table to pass. Put the collection where `{{source}}` stands (e.g. `remote(t123_my_app_logs)` for the last ~30 minutes, `s3Cluster(primary, t123_my_app_s3)` with its row-type filter for older rows), a bucket such as `toStartOfInterval(dt, INTERVAL 5 MINUTE)` where `{{time}}` stands, and concrete bounds such as `dt > now() - INTERVAL 3 HOUR` for `{{start_time}}` and `{{end_time}}`. Add a `LIMIT`, and call `query_windows` before an `s3Cluster(...)` query over more than a few hours.\n\nError tracking has two data planes:\n\n- **Occurrences** (this skill): ClickHouse - pre-aggregated exception metrics and raw exception events\n- **State**: triage status (resolved/unresolved, who changed it, when) is returned ONLY by `errors` / `error` and changed with `update_error_state`. Never infer state from SQL.\n- **Issues**: Linear/Jira issues linked to an error are listed by `error`; attach or file one with `link_error_issue` / `create_error_issue` (through the team's Better Stack integration, so state changes post comments on the issue), detach with `unlink_error_issue`.\n\n## Exception metrics (counts, trends, first/last seen)\n\nQuery the application's metrics collection (`errors_query_help` names it). The schema is **fixed for all Errors sources** - query it directly, no field discovery needed:\n\n- **Count exceptions with `sum(exceptions_count)`.** `exceptions_count` is a plain `UInt64` per-row column: the number of exceptions in that row. Aggregate it with `sum(...)`, **never** `countMerge(...)` (it is not an aggregate-state column). It self-scopes - it is `0` on non-exception rows - so you do **not** need a `_row_type` filter to isolate exceptions.\n- **Never count exceptions with `countMerge(events_count)`.** `events_count` totals _every_ row type (spans, logs, web events, exceptions) and double-counts span event vs. duration rows, so it over-counts exceptions. Reach for it only when you deliberately want all row types at once.\n- `pattern` - plain column holding the error-group hash: the same hash `errors` returns and `error` takes. Filter on it to scope any query to one error group\n- `environment` - plain column (`production`, `staging`, ...)\n- Aggregate-state columns (use their Merge function): `uniqMerge(user_uniq)` affected users, `minMerge(seen_at_min)` / `maxMerge(seen_at_max)` exact first/last occurrence, `anyLastMerge(type_last)` / `anyLastMerge(message_last)` / `anyLastMerge(call_site_file_last)` / `anyLastMerge(call_site_function_last)` group metadata\n\nExceptions over time:\n\n```sql\nSELECT {{time}} AS time,\n sum(exceptions_count) AS \"Exceptions\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\nGROUP BY time\nORDER BY time\n```\n\nPer-pattern trend with readable labels (\"errors by pattern\"): there is no plain `message` column - group by `pattern` (the stable identity) and label the series with the message merge column. No hash-to-message mapping needed:\n\n```sql\nSELECT {{time}} AS time,\n anyLastMerge(message_last) AS series,\n sum(exceptions_count) AS \"Errors\"\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\nGROUP BY time, pattern\nORDER BY time\n```\n\n`series` resolves per (time, pattern) group, so each pattern renders as one line labeled by its message. Prefix with the type when helpful: `concat(anyLastMerge(type_last), ': ', anyLastMerge(message_last)) AS series`.\n\nGroup metadata / first & last occurrence of one error pattern - pass a `start_time` spanning the source's retention (e.g. `now-30d`), otherwise `first_seen` is clipped to the query window:\n\n```sql\nSELECT\n anyLastMerge(type_last) AS type,\n anyLastMerge(message_last) AS message,\n minMerge(seen_at_min) AS first_seen,\n maxMerge(seen_at_max) AS last_seen,\n sum(exceptions_count) AS occurrences,\n uniqMerge(user_uniq) AS users,\n groupUniqArray(environment) AS environments\nFROM {{source}}\nWHERE {{time}} BETWEEN {{start_time}} AND {{end_time}}\n AND pattern = '<hash>'\nGROUP BY pattern\n```\n\nAdd `{{time}} AS time, ... GROUP BY time` bucketing to trend any of these per error pattern.\n\n## Raw exception events (stack traces, payloads)\n\n`query` over the application's raw exception rows (`errors_query_help` names the collection and its row-type filter). Raw-JSON dialect like logs: event payload in the `raw` column read with `JSONExtractCaseInsensitive(raw, ...)`, the same `pattern` column for filtering, `dt` timestamps. Use a narrow time window around a known occurrence (e.g. `maxMerge(seen_at_max)` from the metrics query) - full-range scans over raw exceptions are slow.\n\nBuild exception trend charts from the metrics collection (queries above). Raw exceptions are for `query` drill-downs: stack traces, payload inspection, sample events.\n\n## Related skills\n\n- `metrics-query` - merge functions, template variables, and the general metrics dialect; load it when writing metrics queries beyond the canonical ones above\n- `logs-query` - the raw-JSON extraction dialect used by raw exception events\n"
}SHA-256 of public snapshot: 0e9cc0446f5508386cddd4e22b7bb215212adb61f51e02841bf772bb41369737