Public: anyone can read this; the crew can change it.
Migrated from github.com/Trevato/SO-ARM100
workbenchthis machine
src/live-metrics.ts: rolling timings with p50/p95, counters and gauges, rendered as Prometheus text - one new module and its test #205
Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.
smith/arm:smith/189-src-live-metrics-ts-rolling-timings-with → main 8 commits fork 1 thread · 1 unresolved
2 files
changed +234
−0
Software/so101/src/live-metrics.test.ts added +80
| @@ -0,0 +1,80 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { LiveMetrics, WINDOW_S } from "./live-metrics.ts"; | |
| 3 | ||
| 4 | test("10 and 200 ms timings give p50 and p95", () => { | |
| 5 | const m = new LiveMetrics(); | |
| 6 | for (let i = 0; i < 90; i++) m.observe("move_ms", 10); | |
| 7 | for (let i = 0; i < 10; i++) m.observe("move_ms", 200); | |
| 8 | const t = m.snapshot().timings[0]!; | |
| 9 | expect(t.p50).toBe(10); | |
| 10 | expect(t.p95).toBe(200); | |
| 11 | expect(t.count).toBe(100); | |
| 12 | }); | |
| 13 | ||
| 14 | test("the ring keeps only the latest samples", () => { | |
| 15 | const m = new LiveMetrics(); | |
| 16 | for (let i = 0; i < 256; i++) m.observe("a", 200); | |
| 17 | for (let i = 0; i < 256; i++) m.observe("a", 10); | |
| 18 | expect(m.snapshot().timings[0]!.p95).toBe(10); | |
| 19 | }); | |
| 20 | ||
| 21 | test("counters roll off after the window", () => { | |
| 22 | let t = 1_000_000; | |
| 23 | const m = new LiveMetrics(() => t); | |
| 24 | m.count("frames", 120); | |
| 25 | expect(m.snapshot().counters[0]!.perSecond).toBe(120 / WINDOW_S); | |
| 26 | t += (WINDOW_S - 1) * 1000; | |
| 27 | expect(m.snapshot().counters[0]!.perSecond).toBe(120 / WINDOW_S); | |
| 28 | t += 1000; | |
| 29 | expect(m.snapshot().counters[0]!.perSecond).toBe(0); | |
| 30 | }); | |
| 31 | ||
| 32 | test("bad names and values throw", () => { | |
| 33 | const m = new LiveMetrics(); | |
| 34 | for (const n of ["", "Bad", "1a", "a-b", "a b", "a{"]) expect(() => m.observe(n, 1)).toThrow(); | |
| 35 | expect(() => m.count("x y")).toThrow(); | |
| 36 | expect(() => m.gauge("ok", NaN)).toThrow(); | |
| 37 | expect(() => m.gauge("ok", 1, { "bad-label": "x" })).toThrow(); | |
| 38 | }); | |
| 39 | ||
| 40 | test("prometheus lines are name{labels} value and labels are escaped", () => { | |
| 41 | const m = new LiveMetrics(); | |
| 42 | m.observe("move_ms", 10, { route: 'a"b\\c\nd' }); | |
| 43 | m.count("frames", 3); | |
| 44 | m.gauge("clients", 2, { room: "x" }); | |
| 45 | const text = m.prometheus(); | |
| 46 | const lines = text.trim().split("\n").filter((l) => !l.startsWith("#")); | |
| 47 | expect(lines.length).toBeGreaterThan(4); | |
| 48 | for (const l of lines) expect(l).toMatch(/^[a-z_][a-z0-9_]*\{([a-z_][a-z0-9_]*="([^"\\\n]|\\.)*",?)*\} -?[0-9]+(\.[0-9]+)?(e[+-]?[0-9]+)?$/); | |
| 49 | expect(text).toContain('route="a\\"b\\\\c\\nd"'); | |
| 50 | expect(m.summaryLine()).toContain("move_ms p50=10ms"); | |
| 51 | }); | |
| 52 | ||
| 53 | test("the label name quantile is reserved", () => { | |
| 54 | const m = new LiveMetrics(); | |
| 55 | expect(() => m.observe("t", 1, { quantile: "0.9" })).toThrow(); | |
| 56 | expect(() => m.count("c", 1, { quantile: "x" })).toThrow(); | |
| 57 | expect(() => m.gauge("g", 1, { quantile: "x" })).toThrow(); | |
| 58 | }); | |
| 59 | ||
| 60 | test("the same labels in a different order share one series", () => { | |
| 61 | const m = new LiveMetrics(); | |
| 62 | m.observe("t", 1, { a: "1", b: "2" }); | |
| 63 | m.observe("t", 3, { b: "2", a: "1" }); | |
| 64 | m.gauge("g", 1, { a: "1", b: "2" }); | |
| 65 | m.gauge("g", 5, { b: "2", a: "1" }); | |
| 66 | const s = m.snapshot(); | |
| 67 | expect(s.timings.length).toBe(1); | |
| 68 | expect(s.timings[0]!.count).toBe(2); | |
| 69 | expect(s.gauges).toHaveLength(1); | |
| 70 | expect(s.gauges[0]!.value).toBe(5); | |
| 71 | }); | |
| 72 | ||
| 73 | test("prometheus() counter rate rolls off after the window", () => { | |
| 74 | let t = 5_000_000; | |
| 75 | const m = new LiveMetrics(() => t); | |
| 76 | m.count("frames", 60); | |
| 77 | expect(m.prometheus()).toContain("frames_per_second{} 1\n"); | |
| 78 | t += WINDOW_S * 1000; | |
| 79 | expect(m.prometheus()).toContain("frames_per_second{} 0\n"); | |
| 80 | }); |
Software/so101/src/live-metrics.ts added +154
| @@ -0,0 +1,154 @@ | ||
| 1 | /** | |
| 2 | * Live numbers for the operator: rolling timings, counters and gauges, rendered as Prometheus text. | |
| 3 | * | |
| 4 | * `observe(name, ms)` keeps the last RING samples in a fixed ring and reports p50/p95 over them; `count(name, n)` adds | |
| 5 | * to per-second buckets and reports the rate over the last WINDOW_S seconds, so a burst rolls off; `gauge(name, v)` | |
| 6 | * keeps the last value. Names must match NAME (a bad one throws), the label name `quantile` is reserved for timing | |
| 7 | * lines and throws, and label values are escaped on output. Label order does not matter: the same labels share one | |
| 8 | * series. Series are never evicted, so every new name or label value allocates for the life of the process: labels must | |
| 9 | * come from a small fixed set in code, never from user text. Pure state: the clock is passed in, nothing is written | |
| 10 | * anywhere. | |
| 11 | */ | |
| 12 | ||
| 13 | export const RING = 256; | |
| 14 | export const WINDOW_S = 60; | |
| 15 | const NAME = /^[a-z_][a-z0-9_]*$/; | |
| 16 | ||
| 17 | type Labels = Record<string, string>; | |
| 18 | type Timing = { buf: number[]; next: number; total: number; sum: number }; | |
| 19 | type Counter = { name: string; labels: Labels; buckets: Map<number, number> }; | |
| 20 | ||
| 21 | export type Snapshot = { | |
| 22 | timings: { name: string; labels: Labels; count: number; sum: number; p50: number; p95: number }[]; | |
| 23 | counters: { name: string; labels: Labels; perSecond: number }[]; | |
| 24 | gauges: { name: string; labels: Labels; value: number }[]; | |
| 25 | }; | |
| 26 | ||
| 27 | function checkName(name: string): string { | |
| 28 | if (typeof name !== "string" || !NAME.test(name)) throw new Error(`bad metric name: ${JSON.stringify(name)}`); | |
| 29 | return name; | |
| 30 | } | |
| 31 | ||
| 32 | function finite(v: number, what: string): number { | |
| 33 | if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`${what} must be a finite number`); | |
| 34 | return v; | |
| 35 | } | |
| 36 | ||
| 37 | function keyOf(name: string, labels: Labels): string { | |
| 38 | checkName(name); | |
| 39 | for (const k of Object.keys(labels)) { | |
| 40 | checkName(k); | |
| 41 | if (k === "quantile") throw new Error("label name quantile is reserved"); | |
| 42 | } | |
| 43 | return name + JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : 1))); | |
| 44 | } | |
| 45 | ||
| 46 | export function escapeLabel(v: string): string { | |
| 47 | return String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n"); | |
| 48 | } | |
| 49 | ||
| 50 | function render(name: string, labels: Labels, value: number, extra: Labels = {}): string { | |
| 51 | const all = { ...labels, ...extra }; | |
| 52 | const body = Object.entries(all).map(([k, v]) => `${k}="${escapeLabel(v)}"`).join(","); | |
| 53 | return `${name}{${body}} ${value}`; | |
| 54 | } | |
| 55 | ||
| 56 | /** Nearest-rank percentile of an ascending array. */ | |
| 57 | function pct(sorted: number[], p: number): number { | |
| 58 | if (sorted.length === 0) return 0; | |
| 59 | return sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)]!; | |
| 60 | } | |
| 61 | ||
| 62 | export class LiveMetrics { | |
| 63 | private timings = new Map<string, Timing & { name: string; labels: Labels }>(); | |
| 64 | private counters = new Map<string, Counter>(); | |
| 65 | private gauges = new Map<string, { name: string; labels: Labels; value: number }>(); | |
| 66 | ||
| 67 | private now: () => number; | |
| 68 | ||
| 69 | constructor(now: () => number = Date.now) { | |
| 70 | this.now = now; | |
| 71 | } | |
| 72 | ||
| 73 | observe(name: string, ms: number, labels: Labels = {}): void { | |
| 74 | finite(ms, "ms"); | |
| 75 | const key = keyOf(name, labels); | |
| 76 | let t = this.timings.get(key); | |
| 77 | if (!t) this.timings.set(key, (t = { name, labels: { ...labels }, buf: [], next: 0, total: 0, sum: 0 })); | |
| 78 | if (t.buf.length < RING) t.buf.push(ms); | |
| 79 | else t.buf[t.next] = ms; | |
| 80 | t.next = (t.next + 1) % RING; | |
| 81 | t.total++; | |
| 82 | t.sum += ms; | |
| 83 | } | |
| 84 | ||
| 85 | count(name: string, n = 1, labels: Labels = {}): void { | |
| 86 | finite(n, "n"); | |
| 87 | const key = keyOf(name, labels); | |
| 88 | let c = this.counters.get(key); | |
| 89 | if (!c) this.counters.set(key, (c = { name, labels: { ...labels }, buckets: new Map() })); | |
| 90 | const sec = Math.floor(this.now() / 1000); | |
| 91 | c.buckets.set(sec, (c.buckets.get(sec) ?? 0) + n); | |
| 92 | this.prune(c, sec); | |
| 93 | } | |
| 94 | ||
| 95 | gauge(name: string, value: number, labels: Labels = {}): void { | |
| 96 | finite(value, "value"); | |
| 97 | this.gauges.set(keyOf(name, labels), { name, labels: { ...labels }, value }); | |
| 98 | } | |
| 99 | ||
| 100 | private prune(c: Counter, sec: number): void { | |
| 101 | for (const s of c.buckets.keys()) if (s <= sec - WINDOW_S) c.buckets.delete(s); | |
| 102 | } | |
| 103 | ||
| 104 | snapshot(): Snapshot { | |
| 105 | const sec = Math.floor(this.now() / 1000); | |
| 106 | const timings = [...this.timings.values()].map((t) => { | |
| 107 | const sorted = [...t.buf].sort((a, b) => a - b); | |
| 108 | return { name: t.name, labels: t.labels, count: t.total, sum: t.sum, p50: pct(sorted, 0.5), p95: pct(sorted, 0.95) }; | |
| 109 | }); | |
| 110 | const counters = [...this.counters.values()].map((c) => { | |
| 111 | this.prune(c, sec); | |
| 112 | let sum = 0; | |
| 113 | for (const v of c.buckets.values()) sum += v; | |
| 114 | return { name: c.name, labels: c.labels, perSecond: sum / WINDOW_S }; | |
| 115 | }); | |
| 116 | const gauges = [...this.gauges.values()].map((g) => ({ name: g.name, labels: g.labels, value: g.value })); | |
| 117 | return { timings, counters, gauges }; | |
| 118 | } | |
| 119 | ||
| 120 | prometheus(): string { | |
| 121 | const s = this.snapshot(); | |
| 122 | const out: string[] = []; | |
| 123 | const seen = new Set<string>(); | |
| 124 | const type = (name: string, kind: string) => { | |
| 125 | if (!seen.has(name)) out.push(`# TYPE ${name} ${kind}`), seen.add(name); | |
| 126 | }; | |
| 127 | for (const t of s.timings) { | |
| 128 | type(t.name, "summary"); | |
| 129 | out.push(render(t.name, t.labels, t.p50, { quantile: "0.5" })); | |
| 130 | out.push(render(t.name, t.labels, t.p95, { quantile: "0.95" })); | |
| 131 | out.push(render(`${t.name}_sum`, t.labels, t.sum)); | |
| 132 | out.push(render(`${t.name}_count`, t.labels, t.count)); | |
| 133 | } | |
| 134 | for (const c of s.counters) { | |
| 135 | type(`${c.name}_per_second`, "gauge"); | |
| 136 | out.push(render(`${c.name}_per_second`, c.labels, c.perSecond)); | |
| 137 | } | |
| 138 | for (const g of s.gauges) { | |
| 139 | type(g.name, "gauge"); | |
| 140 | out.push(render(g.name, g.labels, g.value)); | |
| 141 | } | |
| 142 | return out.join("\n") + (out.length ? "\n" : ""); | |
| 143 | } | |
| 144 | ||
| 145 | summaryLine(): string { | |
| 146 | const s = this.snapshot(); | |
| 147 | const parts = [ | |
| 148 | ...s.timings.map((t) => `${t.name} p50=${t.p50}ms p95=${t.p95}ms`), | |
| 149 | ...s.counters.map((c) => `${c.name}=${+c.perSecond.toFixed(2)}/s`), | |
| 150 | ...s.gauges.map((g) => `${g.name}=${g.value}`), | |
| 151 | ]; | |
| 152 | return parts.join(" "); | |
| 153 | } | |
| 154 | } |
new above
offline
count() accepts a negative n, so a counter rate can go below zero. Add a check that n >= 0.