From 1db3adde90f16be4487e3352f0e9b5af20cd6edb Mon Sep 17 00:00:00 2001 From: Hugh Kaznowski Date: Sat, 5 Sep 2026 18:37:47 +0100 Subject: [PATCH 1/2] Add worked examples to docs pages Add concrete, verified examples to the General idea, Filtering, Parameters, Metrics, Dashboards, and Settings docs sections, covering common tasks like declaring a value-role duration param, building a requests dashboard with line/bar/pie panels, and filter-bar syntax gotchas (quoted vs. unquoted values, metric-only [param] comparisons). Verified each example against the actual filter/PromQL parsers and engine behavior in src/filter_parser.rs, src/promql.rs, and src/engine.rs. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01XFUNZwCvz3kcod3352ZR2o --- webapp/src/components/Docs.tsx | 95 ++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/webapp/src/components/Docs.tsx b/webapp/src/components/Docs.tsx index 656a250..c12b610 100644 --- a/webapp/src/components/Docs.tsx +++ b/webapp/src/components/Docs.tsx @@ -62,6 +62,14 @@ const SECTIONS: DocSection[] = [ copy of the active one, and its "×" button deletes the active profile. Switching profiles hot-swaps the running engine's declared params/metrics immediately, with no restart.

+

Worked example

+

+ Piping a webserver's access log — {'tail -f access.log | ottyl'} — into a profile named{' '} + webserver: create the profile from the settings menu, declare params/metrics against it (see + the Parameters, Metrics, and Dashboards sections below), then next time you run + the same command, switch to webserver and everything you declared is already there — + no re-declaring params or rebuilding dashboards. +

), }, @@ -109,6 +117,26 @@ const SECTIONS: DocSection[] = [

The filter string is evaluated on the server. A parse error shows as inline text under the filter bar.

+

Worked examples

+ ), }, @@ -141,6 +169,15 @@ const SECTIONS: DocSection[] = [ requests[duration]>100), declare it as a param on a metric instead — see the Metrics section below.

+

Worked example

+

+ Given lines like {'request path=/checkout method=GET duration=182'}, declaring a param named{' '} + duration with regex {String.raw`duration=(?P\d+)`}, capture group{' '} + duration, and type number makes duration show up as a column in the + log table for every line that matched, and comparable in the filter bar once it's also declared as part of + a metric (see Filtering above — bare params aren't queryable by name on their own, only metric + labels/values are). +

), }, @@ -235,6 +272,26 @@ const SECTIONS: DocSection[] = [ latest reading. +

Worked example

+

+ To count requests per path and track their latency from lines like{' '} + {'request path=/checkout method=GET duration=182'}, declare a metric named{' '} + requests with message-match regex{' '} + {String.raw`request path=(?P\S+) method=(?P\S+) duration=(?P\d+)`}{' '} + and two params: path (capture group path, kind string, role{' '} + label) and duration (capture group duration, kind{' '} + number, role value — at most one param can be value). Selecting{' '} + requests in the panel then shows one row per distinct path with its occurrence + count and a trend sparkline. The same declaration also unlocks{' '} + {'histogram(requests[50])'} (duration distribution in 50ms-wide buckets) and{' '} + gauge(requests) (each path's most recent duration) as dashboard panel queries. +

+

+ A param of kind duration marked value is a special case: rather than parsing the + capture group as a number, its value is derived automatically as the elapsed time since the previous + matching event with the same labels — useful for measuring the gap between repeated events (e.g. time + between retries) without the log line itself reporting a duration. +

), }, @@ -314,6 +371,37 @@ const SECTIONS: DocSection[] = [ (default https://ntfy.sh). Configure the sink and send a test notification from the Settings panel — the Alerts panel only defines rule conditions.

+

Worked example: build a "requests" dashboard

+

+ Assuming a requests metric declared as in the Metrics example above (a path{' '} + label and a duration value param), a useful dashboard is three panels: +

+ +

+ Other query shapes worth knowing: {'sum(requests)'} collapses every path into one combined + count-over-time series, and {'rate(requests[5m])'} gives each path's occurrences-per-second + over a trailing 5-minute window — both work with any of the three chart types, since chart type is just how + the returned series get drawn, not part of the query itself. Add a panel, type a query, and it previews + live; a malformed query (e.g. mismatched braces, or histogram() missing its{' '} + [width]) shows its error inline in the panel instead of breaking the dashboard — a syntactically + valid query for a metric that doesn't exist just renders "No data in range." +

), }, @@ -327,6 +415,13 @@ const SECTIONS: DocSection[] = [ max number of logs kept in memory (blank means unlimited), and imported/linked CSS. Changes apply immediately and persist to the settings file on disk. There is no save button.

+

Worked example

+

+ Ingesting a very chatty process and only care about the last hour of activity: set{' '} + max logs in memory to something like 50000 so older lines are dropped as new ones + arrive rather than growing memory use unbounded for the life of the process. Leave it blank to keep + everything ingested — the default, and fine for shorter-lived commands. +

), }, From 049c4f8311ab6ee4231fad5342a0209179106f60 Mon Sep 17 00:00:00 2001 From: Hugh Kaznowski Date: Sat, 5 Sep 2026 18:38:56 +0100 Subject: [PATCH 2/2] Remove tickets/008-docs-add-worked-examples.md (implemented) Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01XFUNZwCvz3kcod3352ZR2o --- tickets/008-docs-add-worked-examples.md | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 tickets/008-docs-add-worked-examples.md diff --git a/tickets/008-docs-add-worked-examples.md b/tickets/008-docs-add-worked-examples.md deleted file mode 100644 index 462d9f8..0000000 --- a/tickets/008-docs-add-worked-examples.md +++ /dev/null @@ -1,8 +0,0 @@ -# Add worked examples to docs pages - -The docs pages should have examples of how to achieve something. Particularly the dashboards and panels section. But also metrics and params and the others. - -## Acceptance criteria -- Dashboards and panels docs include concrete, worked examples showing how to accomplish common tasks. -- Metrics and params docs (and other doc sections) get similar example treatment. -- Examples are accurate against current functionality (verified against the actual behavior, not just written speculatively).