Public: anyone can read this; the crew can change it.
Migrated from github.com/Trevato/SO-ARM100
workbenchthis machine
src/live-metrics.ts: rolling counters and p50/p95, rendered as Prometheus text - a pure module with unit tests (re-run on today's main) #155
smith/arm:smith/127-src-live-metrics-ts-rolling-counters-and → main 2 commits fork
3 files
changed +196
−0
Software/so101/src/live-metrics.test.ts added +61
| @@ -0,0 +1,61 @@ | ||
| 1 | import { describe, expect, test } from "bun:test"; | |
| 2 | import { LiveMetrics } from "./live-metrics.ts"; | |
| 3 | ||
| 4 | describe("live metrics", () => { | |
| 5 | test("p50 and p95 of injected 10/200 ms timings", () => { | |
| 6 | const m = new LiveMetrics(); | |
| 7 | for (let i = 0; i < 90; i++) m.observe("frame", 10); | |
| 8 | for (let i = 0; i < 10; i++) m.observe("frame", 200); | |
| 9 | const t = m.snapshot().timings.frame!; | |
| 10 | expect(t.p50).toBe(10); | |
| 11 | expect(t.p95).toBe(200); | |
| 12 | expect(t.count).toBe(100); | |
| 13 | }); | |
| 14 | ||
| 15 | test("the sample window rolls", () => { | |
| 16 | const m = new LiveMetrics(); | |
| 17 | for (let i = 0; i < 600; i++) m.observe("x", 200); | |
| 18 | for (let i = 0; i < 512; i++) m.observe("x", 10); | |
| 19 | expect(m.snapshot().timings.x!.p95).toBe(10); | |
| 20 | }); | |
| 21 | ||
| 22 | test("counters roll off after the window", () => { | |
| 23 | let now = 1_000_000; | |
| 24 | const m = new LiveMetrics(() => now); | |
| 25 | m.count("moves", 120); | |
| 26 | expect(m.snapshot().rates.moves).toBe(2); | |
| 27 | now += 30_000; | |
| 28 | m.count("moves", 60); | |
| 29 | expect(m.snapshot().rates.moves).toBe(3); | |
| 30 | now += 31_000; | |
| 31 | expect(m.snapshot().rates.moves).toBe(1); | |
| 32 | now += 60_000; | |
| 33 | expect(m.snapshot().rates.moves).toBe(0); | |
| 34 | }); | |
| 35 | ||
| 36 | test("bad names are refused", () => { | |
| 37 | const m = new LiveMetrics(); | |
| 38 | for (const bad of ["", "9a", "A", "a-b", 'a"b', "a b\n"]) { | |
| 39 | expect(() => m.observe(bad, 1)).toThrow(); | |
| 40 | expect(() => m.count(bad)).toThrow(); | |
| 41 | expect(() => m.gauge(bad, 1)).toThrow(); | |
| 42 | } | |
| 43 | expect(() => new LiveMetrics(Date.now, { arm: 'x"y' })).toThrow(); | |
| 44 | expect(() => new LiveMetrics(Date.now, { "Bad": "x" })).toThrow(); | |
| 45 | }); | |
| 46 | ||
| 47 | test("prometheus lines all parse", () => { | |
| 48 | const m = new LiveMetrics(Date.now, { arm: "so101" }); | |
| 49 | m.observe("frame", 10); | |
| 50 | m.observe("frame", 200); | |
| 51 | m.count("moves", 3); | |
| 52 | m.gauge("clients", 2.5); | |
| 53 | const text = m.prometheus(); | |
| 54 | const line = /^[a-z_][a-z0-9_]*(\{[a-z_][a-z0-9_]*="[^"\\\n]*"(,[a-z_][a-z0-9_]*="[^"\\\n]*")*\})? -?\d+(\.\d+)?$/; | |
| 55 | const body = text.split("\n").filter((l) => l && !l.startsWith("#")); | |
| 56 | expect(body.length).toBe(5); | |
| 57 | for (const l of body) expect(l).toMatch(line); | |
| 58 | expect(text).toContain('frame_ms{arm="so101",quantile="0.95"} 200'); | |
| 59 | expect(m.summaryLine()).toContain("frame p50=10ms p95=200ms"); | |
| 60 | }); | |
| 61 | }); |
Software/so101/src/live-metrics.ts added +134
| @@ -0,0 +1,134 @@ | ||
| 1 | /** | |
| 2 | * Live numbers for the running app: timings with rolling p50/p95, counters as a per-second rate over | |
| 3 | * the last minute, and gauges. Pure: plain data in, plain data out, the clock injected. Updates write | |
| 4 | * into fixed buffers made when a series is first seen; nothing is allocated per call. | |
| 5 | */ | |
| 6 | ||
| 7 | const NAME = /^[a-z_][a-z0-9_]*$/; | |
| 8 | const SAMPLES = 512; | |
| 9 | const WINDOW_S = 60; | |
| 10 | const MAX_SERIES = 256; | |
| 11 | ||
| 12 | export interface TimingSnapshot { count: number; p50: number; p95: number } | |
| 13 | export interface LiveSnapshot { | |
| 14 | timings: Record<string, TimingSnapshot>; | |
| 15 | rates: Record<string, number>; | |
| 16 | gauges: Record<string, number>; | |
| 17 | } | |
| 18 | ||
| 19 | class Timing { | |
| 20 | readonly ring = new Float64Array(SAMPLES); | |
| 21 | next = 0; | |
| 22 | filled = 0; | |
| 23 | } | |
| 24 | ||
| 25 | class Rate { | |
| 26 | readonly sums = new Float64Array(WINDOW_S); | |
| 27 | readonly stamps = new Float64Array(WINDOW_S).fill(-1); | |
| 28 | } | |
| 29 | ||
| 30 | function checkName(kind: string, s: string): string { | |
| 31 | if (typeof s !== "string" || !NAME.test(s)) throw new Error(`bad ${kind}: ${JSON.stringify(String(s).slice(0, 40))}`); | |
| 32 | return s; | |
| 33 | } | |
| 34 | ||
| 35 | function escapeLabel(v: string): string { | |
| 36 | return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n"); | |
| 37 | } | |
| 38 | ||
| 39 | function rank(sorted: Float64Array, q: number): number { | |
| 40 | return sorted.length === 0 ? 0 : sorted[Math.max(0, Math.ceil(q * sorted.length) - 1)]!; | |
| 41 | } | |
| 42 | ||
| 43 | export class LiveMetrics { | |
| 44 | private readonly timings = new Map<string, Timing>(); | |
| 45 | private readonly rates = new Map<string, Rate>(); | |
| 46 | private readonly gauges = new Map<string, number>(); | |
| 47 | private readonly labels: readonly [string, string][]; | |
| 48 | ||
| 49 | constructor(private readonly now: () => number = Date.now, labels: Record<string, string> = {}) { | |
| 50 | this.labels = Object.entries(labels).map(([k, v]) => [checkName("label name", k), checkName("label value", v)]); | |
| 51 | } | |
| 52 | ||
| 53 | private series<T>(map: Map<string, T>, name: string, make: () => T): T { | |
| 54 | let s = map.get(name); | |
| 55 | if (s) return s; | |
| 56 | checkName("metric name", name); | |
| 57 | if (this.timings.size + this.rates.size + this.gauges.size >= MAX_SERIES) throw new Error("too many metrics"); | |
| 58 | s = make(); | |
| 59 | map.set(name, s); | |
| 60 | return s; | |
| 61 | } | |
| 62 | ||
| 63 | observe(name: string, ms: number): void { | |
| 64 | if (!Number.isFinite(ms)) return; | |
| 65 | const t = this.series(this.timings, name, () => new Timing()); | |
| 66 | t.ring[t.next] = ms; | |
| 67 | t.next = (t.next + 1) % SAMPLES; | |
| 68 | if (t.filled < SAMPLES) t.filled++; | |
| 69 | } | |
| 70 | ||
| 71 | count(name: string, n = 1): void { | |
| 72 | if (!Number.isFinite(n)) return; | |
| 73 | const r = this.series(this.rates, name, () => new Rate()); | |
| 74 | const sec = Math.floor(this.now() / 1000); | |
| 75 | const i = ((sec % WINDOW_S) + WINDOW_S) % WINDOW_S; | |
| 76 | if (r.stamps[i] !== sec) { r.stamps[i] = sec; r.sums[i] = 0; } | |
| 77 | r.sums[i]! += n; | |
| 78 | } | |
| 79 | ||
| 80 | gauge(name: string, value: number): void { | |
| 81 | if (!Number.isFinite(value)) return; | |
| 82 | if (!this.gauges.has(name)) this.series(this.gauges, name, () => 0); | |
| 83 | this.gauges.set(name, value); | |
| 84 | } | |
| 85 | ||
| 86 | private rate(r: Rate, sec: number): number { | |
| 87 | let total = 0; | |
| 88 | for (let i = 0; i < WINDOW_S; i++) if (sec - r.stamps[i]! >= 0 && sec - r.stamps[i]! < WINDOW_S) total += r.sums[i]!; | |
| 89 | return total / WINDOW_S; | |
| 90 | } | |
| 91 | ||
| 92 | snapshot(): LiveSnapshot { | |
| 93 | const sec = Math.floor(this.now() / 1000); | |
| 94 | const out: LiveSnapshot = { timings: {}, rates: {}, gauges: {} }; | |
| 95 | for (const [name, t] of this.timings) { | |
| 96 | const sorted = t.ring.slice(0, t.filled).sort(); | |
| 97 | out.timings[name] = { count: t.filled, p50: rank(sorted, 0.5), p95: rank(sorted, 0.95) }; | |
| 98 | } | |
| 99 | for (const [name, r] of this.rates) out.rates[name] = this.rate(r, sec); | |
| 100 | for (const [name, v] of this.gauges) out.gauges[name] = v; | |
| 101 | return out; | |
| 102 | } | |
| 103 | ||
| 104 | prometheus(): string { | |
| 105 | const snap = this.snapshot(); | |
| 106 | const fmt = (extra: [string, string][]): string => { | |
| 107 | const all = [...this.labels, ...extra]; | |
| 108 | return all.length ? `{${all.map(([k, v]) => `${k}="${escapeLabel(v)}"`).join(",")}}` : ""; | |
| 109 | }; | |
| 110 | const lines: string[] = []; | |
| 111 | for (const [name, t] of Object.entries(snap.timings)) { | |
| 112 | lines.push(`# TYPE ${name}_ms summary`); | |
| 113 | lines.push(`${name}_ms${fmt([["quantile", "0.5"]])} ${t.p50}`); | |
| 114 | lines.push(`${name}_ms${fmt([["quantile", "0.95"]])} ${t.p95}`); | |
| 115 | lines.push(`${name}_ms_count${fmt([])} ${t.count}`); | |
| 116 | } | |
| 117 | for (const [name, v] of Object.entries(snap.rates)) { | |
| 118 | lines.push(`# TYPE ${name}_per_second gauge`, `${name}_per_second${fmt([])} ${v}`); | |
| 119 | } | |
| 120 | for (const [name, v] of Object.entries(snap.gauges)) { | |
| 121 | lines.push(`# TYPE ${name} gauge`, `${name}${fmt([])} ${v}`); | |
| 122 | } | |
| 123 | return lines.join("\n") + (lines.length ? "\n" : ""); | |
| 124 | } | |
| 125 | ||
| 126 | summaryLine(): string { | |
| 127 | const s = this.snapshot(); | |
| 128 | const parts: string[] = []; | |
| 129 | for (const [n, t] of Object.entries(s.timings)) parts.push(`${n} p50=${t.p50}ms p95=${t.p95}ms`); | |
| 130 | for (const [n, v] of Object.entries(s.rates)) parts.push(`${n}=${+v.toFixed(2)}/s`); | |
| 131 | for (const [n, v] of Object.entries(s.gauges)) parts.push(`${n}=${v}`); | |
| 132 | return parts.join(" "); | |
| 133 | } | |
| 134 | } |
forge.json +1
| @@ -16,6 +16,7 @@ | ||
| 16 | 16 | "100.89.95.68:8101" |
| 17 | 17 | ], |
| 18 | 18 | "check": { |
| 19 | "run": "bun install --cwd Software/so101 --frozen-lockfile && cd Software/so101 && bun x tsc --noEmit && bun test", | |
| 19 | 20 | "limits": { |
| 20 | 21 | "cpus": 6, |
| 21 | 22 | "memory": 6144 |
new above
offline