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 #119
smith/arm:smith/109-src-live-metrics-ts-rolling-counters-and → main 1 commit fork
2 files
changed +194
−0
Software/so101/src/live-metrics.test.ts added +62
| @@ -0,0 +1,62 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { LiveMetrics, escapeLabel } from "./live-metrics.ts"; | |
| 3 | ||
| 4 | function make() { | |
| 5 | let t = 1_000_000; | |
| 6 | const m = new LiveMetrics(() => t); | |
| 7 | return { m, tick: (ms: number) => (t += ms) }; | |
| 8 | } | |
| 9 | ||
| 10 | test("p50/p95 from 10 and 200 ms timings", () => { | |
| 11 | const { m } = make(); | |
| 12 | for (let i = 0; i < 90; i++) m.observe("tick", 10); | |
| 13 | for (let i = 0; i < 10; i++) m.observe("tick", 200); | |
| 14 | const t = m.snapshot().timings.tick!; | |
| 15 | expect(t.p50).toBe(10); | |
| 16 | expect(t.p95).toBe(200); | |
| 17 | expect(t.count).toBe(100); | |
| 18 | }); | |
| 19 | ||
| 20 | test("timing window keeps only the latest samples", () => { | |
| 21 | const { m } = make(); | |
| 22 | for (let i = 0; i < 256; i++) m.observe("x", 200); | |
| 23 | for (let i = 0; i < 256; i++) m.observe("x", 10); | |
| 24 | expect(m.snapshot().timings.x!.p95).toBe(10); | |
| 25 | }); | |
| 26 | ||
| 27 | test("counters roll off after the window", () => { | |
| 28 | const { m, tick } = make(); | |
| 29 | m.count("req", 30); | |
| 30 | expect(m.snapshot().counters.req!.rate).toBe(0.5); | |
| 31 | tick(30_000); | |
| 32 | m.count("req", 30); | |
| 33 | expect(m.snapshot().counters.req!.rate).toBe(1); | |
| 34 | tick(31_000); | |
| 35 | expect(m.snapshot().counters.req!.rate).toBe(0.5); | |
| 36 | tick(60_000); | |
| 37 | const c = m.snapshot().counters.req!; | |
| 38 | expect(c.rate).toBe(0); | |
| 39 | expect(c.total).toBe(60); | |
| 40 | }); | |
| 41 | ||
| 42 | test("prometheus lines all parse", () => { | |
| 43 | const { m } = make(); | |
| 44 | m.observe("tick", 12.5); | |
| 45 | m.count("req"); | |
| 46 | m.gauge("queue_depth", 3); | |
| 47 | const lines = m.prometheus().trim().split("\n").filter((l) => !l.startsWith("#")); | |
| 48 | expect(lines.length).toBeGreaterThan(5); | |
| 49 | for (const l of lines) expect(l).toMatch(/^[a-z_][a-z0-9_]*(\{[a-z_]+="[^"]*"\})? -?[0-9.e+-]+$/); | |
| 50 | expect(m.summaryLine()).toContain("queue_depth=3"); | |
| 51 | }); | |
| 52 | ||
| 53 | test("bad names and values are refused", () => { | |
| 54 | const { m } = make(); | |
| 55 | for (const bad of ["", "Bad", "1x", "a-b", 'a"b', "a\nb"]) { | |
| 56 | expect(() => m.observe(bad, 1)).toThrow(); | |
| 57 | expect(() => m.count(bad)).toThrow(); | |
| 58 | expect(() => m.gauge(bad, 1)).toThrow(); | |
| 59 | } | |
| 60 | expect(() => m.observe("ok", NaN)).toThrow(); | |
| 61 | expect(escapeLabel('a"b\\c\nd')).toBe('a\\"b\\\\c\\nd'); | |
| 62 | }); |
Software/so101/src/live-metrics.ts added +132
| @@ -0,0 +1,132 @@ | ||
| 1 | // Rolling counters, timings and gauges, rendered as Prometheus text. Pure: no I/O, clock injected. | |
| 2 | ||
| 3 | const NAME = /^[a-z_][a-z0-9_]*$/; | |
| 4 | const SAMPLES = 256; // timing window: the last 256 observations | |
| 5 | const SECONDS = 60; // counter window | |
| 6 | ||
| 7 | class Timing { | |
| 8 | ring = new Float64Array(SAMPLES); | |
| 9 | n = 0; // total observed | |
| 10 | sum = 0; | |
| 11 | } | |
| 12 | class Counter { | |
| 13 | buckets = new Float64Array(SECONDS); | |
| 14 | stamps = new Float64Array(SECONDS).fill(-1); | |
| 15 | total = 0; | |
| 16 | } | |
| 17 | ||
| 18 | export type TimingSnapshot = { count: number; sum: number; p50: number; p95: number }; | |
| 19 | export type CounterSnapshot = { total: number; rate: number }; | |
| 20 | export type Snapshot = { | |
| 21 | timings: Record<string, TimingSnapshot>; | |
| 22 | counters: Record<string, CounterSnapshot>; | |
| 23 | gauges: Record<string, number>; | |
| 24 | }; | |
| 25 | ||
| 26 | export function checkName(name: string): string { | |
| 27 | if (typeof name !== "string" || name.length > 64 || !NAME.test(name)) { | |
| 28 | throw new Error(`bad metric name: ${JSON.stringify(String(name).slice(0, 40))}`); | |
| 29 | } | |
| 30 | return name; | |
| 31 | } | |
| 32 | ||
| 33 | export function escapeLabel(v: string): string { | |
| 34 | return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n"); | |
| 35 | } | |
| 36 | ||
| 37 | function finite(v: number, what: string): number { | |
| 38 | if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`${what} must be a finite number`); | |
| 39 | return v; | |
| 40 | } | |
| 41 | ||
| 42 | function quantile(sorted: Float64Array, q: number): number { | |
| 43 | if (sorted.length === 0) return 0; | |
| 44 | return sorted[Math.max(0, Math.ceil(q * sorted.length) - 1)]!; | |
| 45 | } | |
| 46 | ||
| 47 | export class LiveMetrics { | |
| 48 | = new Map<string, Timing>(); | |
| 49 | = new Map<string, Counter>(); | |
| 50 | = new Map<string, number>(); | |
| 51 | : () => number; | |
| 52 | ||
| 53 | constructor(now: () => number = Date.now) { | |
| 54 | this. = now; | |
| 55 | } | |
| 56 | ||
| 57 | observe(name: string, ms: number): void { | |
| 58 | finite(ms, "ms"); | |
| 59 | let t = this..get(checkName(name)); | |
| 60 | if (!t) this..set(name, (t = new Timing())); | |
| 61 | t.ring[t.n % SAMPLES] = ms; | |
| 62 | t.n++; | |
| 63 | t.sum += ms; | |
| 64 | } | |
| 65 | ||
| 66 | count(name: string, n = 1): void { | |
| 67 | finite(n, "n"); | |
| 68 | let c = this..get(checkName(name)); | |
| 69 | if (!c) this..set(name, (c = new Counter())); | |
| 70 | const sec = Math.floor(this.() / 1000); | |
| 71 | const i = sec % SECONDS; | |
| 72 | if (c.stamps[i] !== sec) { | |
| 73 | c.stamps[i] = sec; | |
| 74 | c.buckets[i] = 0; | |
| 75 | } | |
| 76 | c.buckets[i]! += n; | |
| 77 | c.total += n; | |
| 78 | } | |
| 79 | ||
| 80 | gauge(name: string, value: number): void { | |
| 81 | finite(value, "value"); | |
| 82 | this..set(checkName(name), value); | |
| 83 | } | |
| 84 | ||
| 85 | snapshot(): Snapshot { | |
| 86 | const sec = Math.floor(this.() / 1000); | |
| 87 | const out: Snapshot = { timings: {}, counters: {}, gauges: {} }; | |
| 88 | for (const [name, t] of this.) { | |
| 89 | const sorted = t.ring.slice(0, Math.min(t.n, SAMPLES)).sort(); | |
| 90 | out.timings[name] = { count: t.n, sum: t.sum, p50: quantile(sorted, 0.5), p95: quantile(sorted, 0.95) }; | |
| 91 | } | |
| 92 | for (const [name, c] of this.) { | |
| 93 | let sum = 0; | |
| 94 | for (let i = 0; i < SECONDS; i++) if (sec - c.stamps[i]! < SECONDS && c.stamps[i]! <= sec) sum += c.buckets[i]!; | |
| 95 | out.counters[name] = { total: c.total, rate: sum / SECONDS }; | |
| 96 | } | |
| 97 | for (const [name, v] of this.) out.gauges[name] = v; | |
| 98 | return out; | |
| 99 | } | |
| 100 | ||
| 101 | prometheus(): string { | |
| 102 | const s = this.snapshot(); | |
| 103 | const lines: string[] = []; | |
| 104 | for (const [name, t] of Object.entries(s.timings)) { | |
| 105 | lines.push(`# TYPE ${name}_ms summary`); | |
| 106 | lines.push(`${name}_ms{quantile="${escapeLabel("0.5")}"} ${t.p50}`); | |
| 107 | lines.push(`${name}_ms{quantile="${escapeLabel("0.95")}"} ${t.p95}`); | |
| 108 | lines.push(`${name}_ms_sum ${t.sum}`); | |
| 109 | lines.push(`${name}_ms_count ${t.count}`); | |
| 110 | } | |
| 111 | for (const [name, c] of Object.entries(s.counters)) { | |
| 112 | lines.push(`# TYPE ${name}_total counter`); | |
| 113 | lines.push(`${name}_total ${c.total}`); | |
| 114 | lines.push(`# TYPE ${name}_rate gauge`); | |
| 115 | lines.push(`${name}_rate ${c.rate}`); | |
| 116 | } | |
| 117 | for (const [name, v] of Object.entries(s.gauges)) { | |
| 118 | lines.push(`# TYPE ${name} gauge`); | |
| 119 | lines.push(`${name} ${v}`); | |
| 120 | } | |
| 121 | return lines.join("\n") + "\n"; | |
| 122 | } | |
| 123 | ||
| 124 | summaryLine(): string { | |
| 125 | const s = this.snapshot(); | |
| 126 | const parts: string[] = []; | |
| 127 | for (const [n, t] of Object.entries(s.timings)) parts.push(`${n}=p50:${t.p50}ms/p95:${t.p95}ms`); | |
| 128 | for (const [n, c] of Object.entries(s.counters)) parts.push(`${n}=${c.rate.toFixed(2)}/s`); | |
| 129 | for (const [n, v] of Object.entries(s.gauges)) parts.push(`${n}=${v}`); | |
| 130 | return `metrics ${parts.join(" ")}`.trimEnd(); | |
| 131 | } | |
| 132 | } |
new above
offline