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

Merged opened this

Check · Review · Land done · Live — Landed; nothing deploys from this branch, so this is the end of its path.

Merged

smith/arm:smith/189-src-live-metrics-ts-rolling-timings-with → main 8 commits fork 1 thread · 1 unresolved

  • Merged. smith/189-src-live-metrics-ts-rolling-timings-with was merged into main as 240fb37.

Review

Sign in to review this change.
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);

count() accepts a negative n, so a counter rate can go below zero. Add a check that n >= 0.

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 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs