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

Parked opened this
Closed without merging

smith/arm:smith/109-src-live-metrics-ts-rolling-counters-and → main 1 commit fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
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 #timings = new Map<string, Timing>();
49 #counters = new Map<string, Counter>();
50 #gauges = new Map<string, number>();
51 #now: () => number;
52
53 constructor(now: () => number = Date.now) {
54 this.#now = now;
55 }
56
57 observe(name: string, ms: number): void {
58 finite(ms, "ms");
59 let t = this.#timings.get(checkName(name));
60 if (!t) this.#timings.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.#counters.get(checkName(name));
69 if (!c) this.#counters.set(name, (c = new Counter()));
70 const sec = Math.floor(this.#now() / 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.#gauges.set(checkName(name), value);
83 }
84
85 snapshot(): Snapshot {
86 const sec = Math.floor(this.#now() / 1000);
87 const out: Snapshot = { timings: {}, counters: {}, gauges: {} };
88 for (const [name, t] of this.#timings) {
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.#counters) {
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.#gauges) 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 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs