1# tools/events
2
3`nix run .#events`: the Worker's telemetry, read back from Workers
4Analytics Engine. The Worker writes an event with `event()`
5(`worker/src/events.ts`); what each event's columns mean is
6`worker/src/events-schema.ts`, which this reads too, so a query names the
7same fields the Worker wrote.
8
9    nix run .#events                                  every event and its columns
10    nix run .#events -- jev.relay                     its last 50 rows, last day
11    nix run .#events -- jev.relay --since 7d --limit 500
12    nix run .#events -- --sql "SELECT … FORMAT JSON"  any query, sent as is
13
14An event's rows come one JSON object a line, newest first, ready for `jq`.
15`weight` is how many events a row stands for (Analytics Engine samples a
16busy event): count and average with it, e.g.
17
18    nix run .#events -- --sql "SELECT blob1 AS outcome, SUM(_sample_interval) AS calls,
19      SUM(_sample_interval * double3) / SUM(_sample_interval) AS avg_upstream_ms
20      FROM jevstrudel_events WHERE index1 = 'jev.relay'
21      AND bitAnd(toUInt32(double1), 2) > 0 AND timestamp > NOW() - INTERVAL '1' DAY
22      GROUP BY outcome FORMAT JSON"
23
24(`bitAnd(toUInt32(double1), 2)`: only rows where double3, upstreamMs, is
25known; see the layout in `events-schema.ts`.)
26
27It needs the Cloudflare account (from nix-facts, set by the flake) and the
28same 1Password item as the deploy, whose token must carry Account
29Analytics: Read. The token is read per run and never printed. Local
30development writes nowhere: `wrangler dev` keeps Analytics Engine local, so
31only the deployed Worker's events are here, kept for three months.
32
33| File | What it is |
34|---|---|
35| `events.mjs` | The command. |
36| `events.test.mjs` | Its queries and decoding, against the Worker's own writer. |