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 #200

Parked opened this
Closed without merging

smith/arm:smith/189-src-live-metrics-ts-rolling-timings-with → main 4 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
2 files changed +199 −0
Software/so101/src/live-metrics.test.ts added +51
@@ -0,0 +1,51 @@
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.e+-]+$/);
49 expect(text).toContain('route="a\\"b\\\\c\\nd"');
50 expect(m.summaryLine()).toContain("move_ms p50=10ms");
51 });
Software/so101/src/live-metrics.ts added +148
@@ -0,0 +1,148 @@
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) and label values are escaped on output. Pure state:
7 * the clock is passed in, nothing is written anywhere.
8 */
9
10 export const RING = 256;
11 export const WINDOW_S = 60;
12 const NAME = /^[a-z_][a-z0-9_]*$/;
13
14 type Labels = Record<string, string>;
15 type Timing = { buf: number[]; next: number; total: number; sum: number };
16 type Counter = { name: string; labels: Labels; buckets: Map<number, number> };
17
18 export type Snapshot = {
19 timings: { name: string; labels: Labels; count: number; sum: number; p50: number; p95: number }[];
20 counters: { name: string; labels: Labels; perSecond: number }[];
21 gauges: { name: string; labels: Labels; value: number }[];
22 };
23
24 function checkName(name: string): string {
25 if (typeof name !== "string" || !NAME.test(name)) throw new Error(`bad metric name: ${JSON.stringify(name)}`);
26 return name;
27 }
28
29 function finite(v: number, what: string): number {
30 if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`${what} must be a finite number`);
31 return v;
32 }
33
34 function keyOf(name: string, labels: Labels): string {
35 checkName(name);
36 for (const k of Object.keys(labels)) checkName(k);
37 return name + JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : 1)));
38 }
39
40 export function escapeLabel(v: string): string {
41 return String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
42 }
43
44 function render(name: string, labels: Labels, value: number, extra: Labels = {}): string {
45 const all = { ...labels, ...extra };
46 const body = Object.entries(all).map(([k, v]) => `${k}="${escapeLabel(v)}"`).join(",");
47 return `${name}{${body}} ${value}`;
48 }
49
50 /** Nearest-rank percentile of an ascending array. */
51 function pct(sorted: number[], p: number): number {
52 if (sorted.length === 0) return 0;
53 return sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)]!;
54 }
55
56 export class LiveMetrics {
57 private timings = new Map<string, Timing & { name: string; labels: Labels }>();
58 private counters = new Map<string, Counter>();
59 private gauges = new Map<string, { name: string; labels: Labels; value: number }>();
60
61 private now: () => number;
62
63 constructor(now: () => number = Date.now) {
64 this.now = now;
65 }
66
67 observe(name: string, ms: number, labels: Labels = {}): void {
68 finite(ms, "ms");
69 const key = keyOf(name, labels);
70 let t = this.timings.get(key);
71 if (!t) this.timings.set(key, (t = { name, labels: { ...labels }, buf: [], next: 0, total: 0, sum: 0 }));
72 if (t.buf.length < RING) t.buf.push(ms);
73 else t.buf[t.next] = ms;
74 t.next = (t.next + 1) % RING;
75 t.total++;
76 t.sum += ms;
77 }
78
79 count(name: string, n = 1, labels: Labels = {}): void {
80 finite(n, "n");
81 const key = keyOf(name, labels);
82 let c = this.counters.get(key);
83 if (!c) this.counters.set(key, (c = { name, labels: { ...labels }, buckets: new Map() }));
84 const sec = Math.floor(this.now() / 1000);
85 c.buckets.set(sec, (c.buckets.get(sec) ?? 0) + n);
86 this.prune(c, sec);
87 }
88
89 gauge(name: string, value: number, labels: Labels = {}): void {
90 finite(value, "value");
91 this.gauges.set(keyOf(name, labels), { name, labels: { ...labels }, value });
92 }
93
94 private prune(c: Counter, sec: number): void {
95 for (const s of c.buckets.keys()) if (s <= sec - WINDOW_S) c.buckets.delete(s);
96 }
97
98 snapshot(): Snapshot {
99 const sec = Math.floor(this.now() / 1000);
100 const timings = [...this.timings.values()].map((t) => {
101 const sorted = [...t.buf].sort((a, b) => a - b);
102 return { name: t.name, labels: t.labels, count: t.total, sum: t.sum, p50: pct(sorted, 0.5), p95: pct(sorted, 0.95) };
103 });
104 const counters = [...this.counters.values()].map((c) => {
105 this.prune(c, sec);
106 let sum = 0;
107 for (const v of c.buckets.values()) sum += v;
108 return { name: c.name, labels: c.labels, perSecond: sum / WINDOW_S };
109 });
110 const gauges = [...this.gauges.values()].map((g) => ({ name: g.name, labels: g.labels, value: g.value }));
111 return { timings, counters, gauges };
112 }
113
114 prometheus(): string {
115 const s = this.snapshot();
116 const out: string[] = [];
117 const seen = new Set<string>();
118 const type = (name: string, kind: string) => {
119 if (!seen.has(name)) out.push(`# TYPE ${name} ${kind}`), seen.add(name);
120 };
121 for (const t of s.timings) {
122 type(t.name, "summary");
123 out.push(render(t.name, t.labels, t.p50, { quantile: "0.5" }));
124 out.push(render(t.name, t.labels, t.p95, { quantile: "0.95" }));
125 out.push(render(`${t.name}_sum`, t.labels, t.sum));
126 out.push(render(`${t.name}_count`, t.labels, t.count));
127 }
128 for (const c of s.counters) {
129 type(`${c.name}_per_second`, "gauge");
130 out.push(render(`${c.name}_per_second`, c.labels, c.perSecond));
131 }
132 for (const g of s.gauges) {
133 type(g.name, "gauge");
134 out.push(render(g.name, g.labels, g.value));
135 }
136 return out.join("\n") + (out.length ? "\n" : "");
137 }
138
139 summaryLine(): string {
140 const s = this.snapshot();
141 const parts = [
142 ...s.timings.map((t) => `${t.name} p50=${t.p50}ms p95=${t.p95}ms`),
143 ...s.counters.map((c) => `${c.name}=${+c.perSecond.toFixed(2)}/s`),
144 ...s.gauges.map((g) => `${g.name}=${g.value}`),
145 ];
146 return parts.join(" ");
147 }
148 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs