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) #131

Closed opened this
Closed without merging

smith/arm:smith/127-src-live-metrics-ts-rolling-counters-and → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
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 @@
1616 "100.89.95.68:8101"
1717 ],
1818 "check": {
19 "run": "bun install --cwd Software/so101 --frozen-lockfile && cd Software/so101 && bun x tsc --noEmit && bun test",
1920 "limits": {
2021 "cpus": 6,
2122 "memory": 6144

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs