@cad0p/pi-memory-budget 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +19 -0
- package/LICENSE +21 -0
- package/README.md +142 -2
- package/docs/consumer-verification-section.md +28 -0
- package/docs/verification.md +55 -0
- package/package.json +63 -4
- package/src/args.mjs +199 -0
- package/src/budget.mjs +546 -0
- package/src/cli.mjs +96 -0
- package/src/config.mjs +180 -0
- package/src/fixture.mjs +491 -0
- package/src/gc-harness.js +67 -0
- package/src/index.mjs +13 -0
- package/src/orchestrate.mjs +164 -0
- package/src/pi.mjs +107 -0
- package/src/report.mjs +188 -0
- package/src/runner.mjs +347 -0
- package/src/sampler.mjs +162 -0
- package/src/stats.mjs +163 -0
package/src/runner.mjs
ADDED
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
// Spawns pi in RPC mode, samples its RSS and pings it, and cleans up.
|
|
2
|
+
|
|
3
|
+
import { spawn } from "node:child_process";
|
|
4
|
+
import { buildPiArgs } from "./pi.mjs";
|
|
5
|
+
import { readRss } from "./sampler.mjs";
|
|
6
|
+
import { summarize } from "./stats.mjs";
|
|
7
|
+
|
|
8
|
+
/** @type {Set<import("node:child_process").ChildProcess>} */
|
|
9
|
+
const live = new Set();
|
|
10
|
+
let hooksInstalled = false;
|
|
11
|
+
|
|
12
|
+
/** @param {import("node:child_process").ChildProcess} child @param {NodeJS.Signals} sig */
|
|
13
|
+
function killGroup(child, sig) {
|
|
14
|
+
if (child.pid === undefined) return;
|
|
15
|
+
try {
|
|
16
|
+
process.kill(-child.pid, sig); // pi is spawned detached: its own process group
|
|
17
|
+
} catch {
|
|
18
|
+
try {
|
|
19
|
+
child.kill(sig);
|
|
20
|
+
} catch {
|
|
21
|
+
// already gone
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Kills every pi process still alive. Safe to call repeatedly. */
|
|
27
|
+
export function killAll() {
|
|
28
|
+
for (const c of live) killGroup(c, "SIGKILL");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Installs exit and signal hooks once, so no pi process is orphaned. */
|
|
32
|
+
export function installCleanupHooks() {
|
|
33
|
+
if (hooksInstalled) return;
|
|
34
|
+
hooksInstalled = true;
|
|
35
|
+
process.on("exit", killAll);
|
|
36
|
+
for (const sig of /** @type {const} */ (["SIGINT", "SIGTERM", "SIGHUP"])) {
|
|
37
|
+
process.on(sig, () => {
|
|
38
|
+
killAll();
|
|
39
|
+
process.exit(sig === "SIGINT" ? 130 : 143);
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Env that keeps pi off the network, set for every configuration alike. */
|
|
45
|
+
export const PI_QUIET_ENV = Object.freeze({
|
|
46
|
+
PI_OFFLINE: "1",
|
|
47
|
+
PI_SKIP_VERSION_CHECK: "1",
|
|
48
|
+
PI_TELEMETRY: "0",
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Last "pmb-gc: diag {json}" line the harness wrote (post-GC heap numbers).
|
|
53
|
+
* @param {string} stderr
|
|
54
|
+
*/
|
|
55
|
+
export function parseGcDiag(stderr) {
|
|
56
|
+
const all = [...stderr.matchAll(/pmb-gc: diag (\{[^\n]*\})/g)];
|
|
57
|
+
if (!all.length) return null;
|
|
58
|
+
try {
|
|
59
|
+
const d = JSON.parse(all[all.length - 1][1]);
|
|
60
|
+
return {
|
|
61
|
+
heapUsedMb: d.heapUsed / 1048576,
|
|
62
|
+
externalMb: d.external / 1048576,
|
|
63
|
+
arrayBuffersMb: d.arrayBuffers / 1048576,
|
|
64
|
+
};
|
|
65
|
+
} catch {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** @param {number} ms */
|
|
71
|
+
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
72
|
+
|
|
73
|
+
/** Cap on how far past --window a run extends to make a pending release observable. */
|
|
74
|
+
export const RELEASE_EXTEND_CAP_SEC = 60;
|
|
75
|
+
|
|
76
|
+
/** Total-RSS range (MB) under which a steady window counts as quiet. */
|
|
77
|
+
const SETTLE_RANGE_MB = 5;
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* @typedef {object} MeasureSpec
|
|
81
|
+
* @property {{ command: string, args: string[] }} pi
|
|
82
|
+
* @property {string[]} extensions
|
|
83
|
+
* @property {string[]} [harnessExtensions] extensions loaded in every configuration alike (GC harness)
|
|
84
|
+
* @property {boolean} [gc] start pi with --expose-gc via NODE_OPTIONS and load the GC harness (default true)
|
|
85
|
+
* @property {string | null} sessionFile
|
|
86
|
+
* @property {string} cwd
|
|
87
|
+
* @property {NodeJS.ProcessEnv} env
|
|
88
|
+
* @property {number} windowSec minimum sampling window
|
|
89
|
+
* @property {number} steadySec settled-window length for steady RSS
|
|
90
|
+
* @property {number} [settleMaxSec] cap on the quiescence wait (default 120)
|
|
91
|
+
* @property {number} [settleMinSec] no settle before this (default 0 here, 30 from the CLI)
|
|
92
|
+
* @property {number} [releaseSec] keep sampling until peak + this (bounded) so a release is observable
|
|
93
|
+
* @property {string[]} [extraArgs]
|
|
94
|
+
* @property {number} [sampleMs]
|
|
95
|
+
* @property {number} [pingMs]
|
|
96
|
+
*/
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* @typedef {import("./stats.mjs").RunSummary & {
|
|
100
|
+
* samples: import("./stats.mjs").Sample[],
|
|
101
|
+
* maxGapMs: number,
|
|
102
|
+
* readyMs: number | null,
|
|
103
|
+
* pings: number,
|
|
104
|
+
* stderrTail: string,
|
|
105
|
+
* exitT: number | null,
|
|
106
|
+
* windowEndSec: number,
|
|
107
|
+
* gcReady: boolean | null,
|
|
108
|
+
* gcDiag: { heapUsedMb: number, externalMb: number, arrayBuffersMb: number } | null,
|
|
109
|
+
* }} RunResult
|
|
110
|
+
*/
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Runs one pi process for the window and measures it.
|
|
114
|
+
* @param {MeasureSpec} spec
|
|
115
|
+
* @returns {Promise<RunResult>}
|
|
116
|
+
*/
|
|
117
|
+
export async function measureRun(spec) {
|
|
118
|
+
installCleanupHooks();
|
|
119
|
+
const sampleMs = spec.sampleMs ?? 200;
|
|
120
|
+
const pingMs = spec.pingMs ?? 100;
|
|
121
|
+
const settleMaxSec = spec.settleMaxSec ?? 120;
|
|
122
|
+
const settleMinSec = spec.settleMinSec ?? 0;
|
|
123
|
+
const releaseSec = spec.releaseSec ?? 0;
|
|
124
|
+
const useGc = spec.gc !== false;
|
|
125
|
+
const args = [
|
|
126
|
+
...spec.pi.args,
|
|
127
|
+
...buildPiArgs({
|
|
128
|
+
extensions: spec.extensions,
|
|
129
|
+
harnessExtensions: useGc ? spec.harnessExtensions : undefined,
|
|
130
|
+
sessionFile: spec.sessionFile,
|
|
131
|
+
extraArgs: spec.extraArgs,
|
|
132
|
+
}),
|
|
133
|
+
];
|
|
134
|
+
// --expose-gc through NODE_OPTIONS reaches the node runtime whichever way pi
|
|
135
|
+
// is launched: a global shell-script launcher, a node_modules/.bin shim, or
|
|
136
|
+
// a plain "node cli.js" --pi value. gc() only ever runs inside the pi pid;
|
|
137
|
+
// children are measured as before.
|
|
138
|
+
// pi's startup network work (model catalog refresh, version check, telemetry)
|
|
139
|
+
// allocates ~40 MB at an unpredictable time and made vanilla settle at 120,
|
|
140
|
+
// 150 or 178 MB. Switched off identically for every config; spec.env wins.
|
|
141
|
+
const base = { ...PI_QUIET_ENV, ...spec.env };
|
|
142
|
+
const env = useGc
|
|
143
|
+
? {
|
|
144
|
+
...base,
|
|
145
|
+
NODE_OPTIONS: [spec.env?.NODE_OPTIONS, "--expose-gc"]
|
|
146
|
+
.filter(Boolean)
|
|
147
|
+
.join(" "),
|
|
148
|
+
}
|
|
149
|
+
: base;
|
|
150
|
+
const child = spawn(spec.pi.command, args, {
|
|
151
|
+
cwd: spec.cwd,
|
|
152
|
+
env,
|
|
153
|
+
stdio: ["pipe", "pipe", "pipe"],
|
|
154
|
+
detached: true,
|
|
155
|
+
});
|
|
156
|
+
live.add(child);
|
|
157
|
+
const t0 = performance.now();
|
|
158
|
+
let exited = false;
|
|
159
|
+
/** @type {number | null} */
|
|
160
|
+
let exitT = null;
|
|
161
|
+
/** @type {{ code: number | null, signal: string | null } | null} */
|
|
162
|
+
let exitInfo = null;
|
|
163
|
+
child.on("exit", (code, signal) => {
|
|
164
|
+
exited = true;
|
|
165
|
+
exitT = (performance.now() - t0) / 1000;
|
|
166
|
+
exitInfo = { code, signal };
|
|
167
|
+
});
|
|
168
|
+
/** @type {Error | null} */
|
|
169
|
+
let spawnError = null;
|
|
170
|
+
child.on("error", (e) => {
|
|
171
|
+
spawnError = e;
|
|
172
|
+
exited = true;
|
|
173
|
+
exitT = (performance.now() - t0) / 1000;
|
|
174
|
+
});
|
|
175
|
+
child.stdin?.on("error", () => {});
|
|
176
|
+
let stderrTail = "";
|
|
177
|
+
child.stderr?.on("data", (d) => {
|
|
178
|
+
stderrTail = (stderrTail + d).slice(-4000);
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
/** @type {Map<string, number>} */
|
|
182
|
+
const pending = new Map();
|
|
183
|
+
let seq = 0;
|
|
184
|
+
let maxGap = 0;
|
|
185
|
+
let pings = 0;
|
|
186
|
+
/** @type {number | null} */
|
|
187
|
+
let readyMs = null;
|
|
188
|
+
let buf = "";
|
|
189
|
+
child.stdout?.on("data", (d) => {
|
|
190
|
+
buf += d;
|
|
191
|
+
let i = buf.indexOf("\n");
|
|
192
|
+
while (i >= 0) {
|
|
193
|
+
const line = buf.slice(0, i);
|
|
194
|
+
buf = buf.slice(i + 1);
|
|
195
|
+
i = buf.indexOf("\n");
|
|
196
|
+
if (!line.includes('"response"')) continue;
|
|
197
|
+
try {
|
|
198
|
+
const m = JSON.parse(line);
|
|
199
|
+
const sent = m.type === "response" ? pending.get(m.id) : undefined;
|
|
200
|
+
if (sent !== undefined) {
|
|
201
|
+
pending.delete(m.id);
|
|
202
|
+
const now = performance.now();
|
|
203
|
+
maxGap = Math.max(maxGap, now - sent);
|
|
204
|
+
pings++;
|
|
205
|
+
if (readyMs === null) readyMs = now - t0;
|
|
206
|
+
}
|
|
207
|
+
} catch {
|
|
208
|
+
// not JSON: ignore
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
});
|
|
212
|
+
|
|
213
|
+
const pinger = setInterval(() => {
|
|
214
|
+
if (exited) return;
|
|
215
|
+
const id = `pmb-${++seq}`;
|
|
216
|
+
pending.set(id, performance.now());
|
|
217
|
+
child.stdin?.write(`${JSON.stringify({ id, type: "get_state" })}\n`);
|
|
218
|
+
}, pingMs);
|
|
219
|
+
|
|
220
|
+
/** @type {import("./stats.mjs").Sample[]} */
|
|
221
|
+
const samples = [];
|
|
222
|
+
try {
|
|
223
|
+
// The loop extends past windowSec when needed: until the peak's release is
|
|
224
|
+
// observable (peak + releaseSec), capped.
|
|
225
|
+
while (true) {
|
|
226
|
+
const now = performance.now();
|
|
227
|
+
if (spawnError) throw spawnError;
|
|
228
|
+
if (exited && samples.length === 0) break;
|
|
229
|
+
if (exited) {
|
|
230
|
+
// Died before the steady window is covered: hard error. During the
|
|
231
|
+
// release-observation extension: measurement cut short, exitT < end.
|
|
232
|
+
if ((now - t0) / 1000 < spec.windowSec) {
|
|
233
|
+
throw new Error(
|
|
234
|
+
`pi exited after ${(exitT ?? 0).toFixed(1)}s, before the ${spec.windowSec}s window ended ${JSON.stringify(exitInfo)}\n${stderrTail}`,
|
|
235
|
+
);
|
|
236
|
+
}
|
|
237
|
+
break;
|
|
238
|
+
}
|
|
239
|
+
const r = await readRss(/** @type {number} */ (child.pid));
|
|
240
|
+
if (r.rssMb !== null) {
|
|
241
|
+
samples.push({
|
|
242
|
+
t: (performance.now() - t0) / 1000,
|
|
243
|
+
rss: r.rssMb,
|
|
244
|
+
main: r.mainMb ?? 0,
|
|
245
|
+
kids: r.kidsMb,
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
const lastT = (performance.now() - t0) / 1000;
|
|
249
|
+
if (lastT < spec.windowSec) {
|
|
250
|
+
await sleep(Math.max(0, sampleMs - (performance.now() - now)));
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
// Past the minimum window: two reasons to keep sampling.
|
|
254
|
+
// (a) Quiescence: the process has not been quiet for a full steady
|
|
255
|
+
// window yet (and the run must not stop right before it would settle).
|
|
256
|
+
let quiet = samples.length > 0;
|
|
257
|
+
if (quiet) {
|
|
258
|
+
const last = samples[samples.length - 1];
|
|
259
|
+
if (last.t < spec.steadySec) quiet = false;
|
|
260
|
+
else {
|
|
261
|
+
let lo = Number.POSITIVE_INFINITY;
|
|
262
|
+
let hi = Number.NEGATIVE_INFINITY;
|
|
263
|
+
for (let k = samples.length - 1; k >= 0; k--) {
|
|
264
|
+
const s = samples[k];
|
|
265
|
+
if (last.t - s.t > spec.steadySec) break;
|
|
266
|
+
if (s.rss < lo) lo = s.rss;
|
|
267
|
+
if (s.rss > hi) hi = s.rss;
|
|
268
|
+
}
|
|
269
|
+
quiet = hi - lo < SETTLE_RANGE_MB;
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
const waitForSettle =
|
|
273
|
+
(!quiet || lastT < settleMinSec) && lastT < settleMaxSec;
|
|
274
|
+
// (b) Release not yet observable AND RSS still at the peak: keep sampling
|
|
275
|
+
// so the check never has to fail on an unobserved release.
|
|
276
|
+
let waitForRelease = false;
|
|
277
|
+
if (releaseSec > 0 && samples.length) {
|
|
278
|
+
const peak = samples.reduce((a, b) => (b.rss > a.rss ? b : a));
|
|
279
|
+
waitForRelease =
|
|
280
|
+
samples[samples.length - 1].rss >= peak.rss - 0.5 &&
|
|
281
|
+
lastT < peak.t + releaseSec &&
|
|
282
|
+
lastT < spec.windowSec + RELEASE_EXTEND_CAP_SEC;
|
|
283
|
+
}
|
|
284
|
+
if (!waitForSettle && !waitForRelease) break;
|
|
285
|
+
await sleep(Math.max(0, sampleMs - (performance.now() - now)));
|
|
286
|
+
}
|
|
287
|
+
if (spawnError) throw spawnError;
|
|
288
|
+
if (samples.length === 0) {
|
|
289
|
+
throw new Error(`pi produced no RSS samples: ${stderrTail}`);
|
|
290
|
+
}
|
|
291
|
+
for (const sent of pending.values())
|
|
292
|
+
maxGap = Math.max(maxGap, performance.now() - sent);
|
|
293
|
+
return {
|
|
294
|
+
...summarize(samples, {
|
|
295
|
+
settleMax: settleMaxSec,
|
|
296
|
+
quietSec: spec.steadySec,
|
|
297
|
+
settleMin: settleMinSec,
|
|
298
|
+
}),
|
|
299
|
+
samples,
|
|
300
|
+
maxGapMs: maxGap,
|
|
301
|
+
readyMs,
|
|
302
|
+
pings,
|
|
303
|
+
stderrTail,
|
|
304
|
+
exitT,
|
|
305
|
+
windowEndSec: samples[samples.length - 1].t,
|
|
306
|
+
gcDiag: parseGcDiag(stderrTail),
|
|
307
|
+
gcReady: !useGc
|
|
308
|
+
? null
|
|
309
|
+
: spec.harnessExtensions?.length
|
|
310
|
+
? /pmb-gc: ready/.test(stderrTail)
|
|
311
|
+
: null,
|
|
312
|
+
};
|
|
313
|
+
} finally {
|
|
314
|
+
clearInterval(pinger);
|
|
315
|
+
await stop(child);
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/** @param {import("node:child_process").ChildProcess} child */
|
|
320
|
+
async function stop(child) {
|
|
321
|
+
try {
|
|
322
|
+
child.stdin?.end();
|
|
323
|
+
} catch {
|
|
324
|
+
// ignore
|
|
325
|
+
}
|
|
326
|
+
killGroup(child, "SIGTERM");
|
|
327
|
+
const deadline = Date.now() + 5000;
|
|
328
|
+
while (
|
|
329
|
+
child.exitCode === null &&
|
|
330
|
+
child.signalCode === null &&
|
|
331
|
+
Date.now() < deadline
|
|
332
|
+
)
|
|
333
|
+
await sleep(50);
|
|
334
|
+
if (child.exitCode === null && child.signalCode === null) {
|
|
335
|
+
killGroup(child, "SIGKILL");
|
|
336
|
+
const d2 = Date.now() + 3000;
|
|
337
|
+
while (
|
|
338
|
+
child.exitCode === null &&
|
|
339
|
+
child.signalCode === null &&
|
|
340
|
+
Date.now() < d2
|
|
341
|
+
)
|
|
342
|
+
await sleep(50);
|
|
343
|
+
}
|
|
344
|
+
// also take down any straggler in the group (extension child processes)
|
|
345
|
+
killGroup(child, "SIGKILL");
|
|
346
|
+
live.delete(child);
|
|
347
|
+
}
|
package/src/sampler.mjs
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
// RSS sampling of a process and its descendants (recursive).
|
|
2
|
+
// Linux: /proc/<pid>/status VmRSS plus /proc/<pid>/task/*/children for the
|
|
3
|
+
// descendant walk (cheap: only the subtree, not all of /proc). macOS: ps.
|
|
4
|
+
|
|
5
|
+
import { execFile } from "node:child_process";
|
|
6
|
+
import fs from "node:fs";
|
|
7
|
+
|
|
8
|
+
const KB_PER_MB = 1024;
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* @param {string} text contents of /proc/<pid>/status
|
|
12
|
+
* @returns {number | null} VmRSS in KB
|
|
13
|
+
*/
|
|
14
|
+
export function parseVmRss(text) {
|
|
15
|
+
const m = /^VmRSS:\s+(\d+)\s*kB/m.exec(text);
|
|
16
|
+
return m ? Number(m[1]) : null;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* @param {string} text output of `ps -A -o pid=,ppid=,rss=`
|
|
21
|
+
* @returns {{ pid: number, ppid: number, rssKb: number }[]}
|
|
22
|
+
*/
|
|
23
|
+
export function parsePsTable(text) {
|
|
24
|
+
/** @type {{ pid: number, ppid: number, rssKb: number }[]} */
|
|
25
|
+
const rows = [];
|
|
26
|
+
for (const line of text.split("\n")) {
|
|
27
|
+
const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s*$/.exec(line);
|
|
28
|
+
if (m)
|
|
29
|
+
rows.push({ pid: Number(m[1]), ppid: Number(m[2]), rssKb: Number(m[3]) });
|
|
30
|
+
}
|
|
31
|
+
return rows;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Sum of RSS (KB) of all descendants of root in a process table.
|
|
36
|
+
* @param {{ pid: number, ppid: number, rssKb: number }[]} rows
|
|
37
|
+
* @param {number} root
|
|
38
|
+
*/
|
|
39
|
+
export function descendantsRssKb(rows, root) {
|
|
40
|
+
/** @type {Map<number, number[]>} */
|
|
41
|
+
const kids = new Map();
|
|
42
|
+
for (const r of rows) {
|
|
43
|
+
const list = kids.get(r.ppid);
|
|
44
|
+
if (list) list.push(r.pid);
|
|
45
|
+
else kids.set(r.ppid, [r.pid]);
|
|
46
|
+
}
|
|
47
|
+
const rss = new Map(rows.map((r) => [r.pid, r.rssKb]));
|
|
48
|
+
let total = 0;
|
|
49
|
+
const stack = [...(kids.get(root) ?? [])];
|
|
50
|
+
const seen = new Set();
|
|
51
|
+
while (stack.length) {
|
|
52
|
+
const pid = /** @type {number} */ (stack.pop());
|
|
53
|
+
if (seen.has(pid)) continue;
|
|
54
|
+
seen.add(pid);
|
|
55
|
+
total += rss.get(pid) ?? 0;
|
|
56
|
+
stack.push(...(kids.get(pid) ?? []));
|
|
57
|
+
}
|
|
58
|
+
return total;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** @param {number} pid @returns {number | null} VmRSS in KB */
|
|
62
|
+
function procRssKb(pid) {
|
|
63
|
+
try {
|
|
64
|
+
return parseVmRss(fs.readFileSync(`/proc/${pid}/status`, "utf8"));
|
|
65
|
+
} catch {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Pids of all descendants of pid, via /proc/<pid>/task/<tid>/children (each task
|
|
72
|
+
* lists the same child pids). BFS over the subtree only: cheap enough to run
|
|
73
|
+
* every sample tick without stalling the harness event loop.
|
|
74
|
+
* @param {number} pid
|
|
75
|
+
* @returns {Set<number>}
|
|
76
|
+
*/
|
|
77
|
+
export function linuxDescendants(pid) {
|
|
78
|
+
/** @type {Set<number>} */
|
|
79
|
+
const out = new Set();
|
|
80
|
+
const queue = [pid];
|
|
81
|
+
/** @type {Set<number>} */
|
|
82
|
+
const seen = new Set([pid]);
|
|
83
|
+
while (queue.length) {
|
|
84
|
+
const p = /** @type {number} */ (queue.pop());
|
|
85
|
+
let tasks;
|
|
86
|
+
try {
|
|
87
|
+
tasks = fs.readdirSync(`/proc/${p}/task`);
|
|
88
|
+
} catch {
|
|
89
|
+
continue; // process gone
|
|
90
|
+
}
|
|
91
|
+
for (const t of tasks) {
|
|
92
|
+
let children;
|
|
93
|
+
try {
|
|
94
|
+
children = fs.readFileSync(`/proc/${p}/task/${t}/children`, "utf8");
|
|
95
|
+
} catch {
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
for (const c of children.trim().split(/\s+/)) {
|
|
99
|
+
const cp = Number(c);
|
|
100
|
+
if (cp > 0 && !seen.has(cp)) {
|
|
101
|
+
seen.add(cp);
|
|
102
|
+
out.add(cp);
|
|
103
|
+
queue.push(cp);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return out;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** @param {string[]} args @returns {Promise<string>} */
|
|
112
|
+
function run(args) {
|
|
113
|
+
return new Promise((resolve) => {
|
|
114
|
+
execFile("ps", args, { encoding: "utf8" }, (err, stdout) =>
|
|
115
|
+
resolve(err ? "" : stdout),
|
|
116
|
+
);
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Total RSS of pid plus all descendants, and the split for diagnosis.
|
|
122
|
+
* @param {number} pid
|
|
123
|
+
* @param {{ withChildren?: boolean }} [opts]
|
|
124
|
+
* @returns {Promise<{ rssMb: number | null, mainMb: number | null, kidsMb: number }>}
|
|
125
|
+
* rssMb null when the process is gone (kidsMb is still the last read: descendants may outlive it)
|
|
126
|
+
*/
|
|
127
|
+
export async function readRss(pid, opts = {}) {
|
|
128
|
+
const withChildren = opts.withChildren ?? true;
|
|
129
|
+
if (process.platform === "linux") {
|
|
130
|
+
const mainKb = procRssKb(pid);
|
|
131
|
+
let kidsKb = 0;
|
|
132
|
+
if (withChildren) {
|
|
133
|
+
for (const d of linuxDescendants(pid)) kidsKb += procRssKb(d) ?? 0;
|
|
134
|
+
}
|
|
135
|
+
return {
|
|
136
|
+
rssMb:
|
|
137
|
+
mainKb === null
|
|
138
|
+
? kidsKb > 0
|
|
139
|
+
? kidsKb / KB_PER_MB
|
|
140
|
+
: null
|
|
141
|
+
: (mainKb + kidsKb) / KB_PER_MB,
|
|
142
|
+
mainMb: mainKb === null ? null : mainKb / KB_PER_MB,
|
|
143
|
+
kidsMb: kidsKb / KB_PER_MB,
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
// macOS / other unix: one ps call for the whole table (main row included).
|
|
147
|
+
const table = parsePsTable(await run(["-A", "-o", "pid=,ppid=,rss="]));
|
|
148
|
+
const self = table.find((r) => r.pid === pid);
|
|
149
|
+
const kidsKb = withChildren ? descendantsRssKb(table, pid) : 0;
|
|
150
|
+
if (!self)
|
|
151
|
+
return {
|
|
152
|
+
rssMb: kidsKb > 0 ? kidsKb / KB_PER_MB : null,
|
|
153
|
+
mainMb: null,
|
|
154
|
+
kidsMb: kidsKb / KB_PER_MB,
|
|
155
|
+
};
|
|
156
|
+
const kids = withChildren ? kidsKb : 0;
|
|
157
|
+
return {
|
|
158
|
+
rssMb: (self.rssKb + kids) / KB_PER_MB,
|
|
159
|
+
mainMb: self.rssKb / KB_PER_MB,
|
|
160
|
+
kidsMb: kids / KB_PER_MB,
|
|
161
|
+
};
|
|
162
|
+
}
|
package/src/stats.mjs
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
// Pure statistics helpers (no I/O).
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* @param {number[]} values
|
|
5
|
+
* @returns {number} median, NaN for an empty list (Infinity sorts last)
|
|
6
|
+
*/
|
|
7
|
+
export function median(values) {
|
|
8
|
+
if (values.length === 0) return Number.NaN;
|
|
9
|
+
const s = [...values].sort((a, b) => a - b);
|
|
10
|
+
const mid = s.length >> 1;
|
|
11
|
+
const lo = s[mid - 1];
|
|
12
|
+
const hi = s[mid];
|
|
13
|
+
if (s.length % 2) return hi;
|
|
14
|
+
return lo === hi ? hi : (lo + hi) / 2;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* @param {number[]} values
|
|
19
|
+
* @returns {number} max, -Infinity for an empty list
|
|
20
|
+
*/
|
|
21
|
+
export function max(values) {
|
|
22
|
+
let m = Number.NEGATIVE_INFINITY;
|
|
23
|
+
for (const v of values) if (v > m) m = v;
|
|
24
|
+
return m;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* One RSS sample. t is seconds since spawn. rss is the TOTAL memory of the pi
|
|
29
|
+
* process: main pid plus every descendant, in MB. main and kids split it for
|
|
30
|
+
* diagnosis.
|
|
31
|
+
* @typedef {{ t: number, rss: number, main: number, kids: number }} Sample
|
|
32
|
+
*/
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* The first quiescent point: the earliest T, at least quietSec after spawn,
|
|
36
|
+
* whose trailing quietSec window has a total-RSS range under maxRangeMb and
|
|
37
|
+
* whose level then holds for the rest of the run. Settling late is a real
|
|
38
|
+
* signal (still-loading process, deferred work), so the caller caps it with
|
|
39
|
+
* settleMax.
|
|
40
|
+
* @param {Sample[]} samples
|
|
41
|
+
* @param {{ quietSec?: number, maxRangeMb?: number, settleMax?: number, settleMin?: number }} [o]
|
|
42
|
+
* @returns {{ settled: boolean, t: number | null, quietSec: number }}
|
|
43
|
+
*/
|
|
44
|
+
export function findSettle(samples, o = {}) {
|
|
45
|
+
const quietSec = o.quietSec ?? 10;
|
|
46
|
+
const maxRangeMb = o.maxRangeMb ?? 5;
|
|
47
|
+
const settleMax = o.settleMax ?? Number.POSITIVE_INFINITY;
|
|
48
|
+
const settleMin = o.settleMin ?? 0; // no settle before this many seconds (late startup work)
|
|
49
|
+
const slack = 0.5;
|
|
50
|
+
// The settled point is the earliest T, at least quietSec after the start,
|
|
51
|
+
// where the last quietSec form a quiet window AND the whole suffix after T
|
|
52
|
+
// stays at that level. Requiring the suffix to hold is what keeps a flat
|
|
53
|
+
// spike plateau, a process that ramps again after T, or a still-loading
|
|
54
|
+
// process from counting as steady.
|
|
55
|
+
for (let i = 0; i < samples.length; i++) {
|
|
56
|
+
const T = samples[i].t;
|
|
57
|
+
if (T > settleMax) break;
|
|
58
|
+
if (T < settleMin) continue;
|
|
59
|
+
if (T - samples[0].t < quietSec - slack) continue; // window not long enough yet
|
|
60
|
+
if (i > 0 && T - samples[i - 1].t > 1) continue; // sampling gap: do not guess
|
|
61
|
+
let lo = Number.POSITIVE_INFINITY;
|
|
62
|
+
let hi = Number.NEGATIVE_INFINITY;
|
|
63
|
+
for (let j = i; j >= 0; j--) {
|
|
64
|
+
const s = samples[j];
|
|
65
|
+
if (T - s.t > quietSec) break;
|
|
66
|
+
if (s.rss < lo) lo = s.rss;
|
|
67
|
+
if (s.rss > hi) hi = s.rss;
|
|
68
|
+
}
|
|
69
|
+
if (!Number.isFinite(lo) || hi - lo >= maxRangeMb) continue;
|
|
70
|
+
let holds = true;
|
|
71
|
+
for (let j = i + 1; j < samples.length; j++) {
|
|
72
|
+
if (samples[j].rss > hi + slack || samples[j].rss < lo - slack) {
|
|
73
|
+
holds = false;
|
|
74
|
+
break;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
if (holds) return { settled: true, t: T, quietSec };
|
|
78
|
+
}
|
|
79
|
+
return { settled: false, t: null, quietSec };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* @typedef {object} RunSummary
|
|
84
|
+
* @property {boolean} settled whether quiescence was found before settleMax
|
|
85
|
+
* @property {number | null} settleT seconds since spawn at which the process settled
|
|
86
|
+
* @property {number | null} steadyMb median total RSS of the settled 10 s window; null when not settled
|
|
87
|
+
* @property {number} spikeMb max total RSS over the whole run
|
|
88
|
+
* @property {number | null} releasedMb total RSS of the last sample
|
|
89
|
+
* @property {number} peakT seconds since spawn at which the spike happened
|
|
90
|
+
* @property {number | null} mainSteadyMb median main-pid RSS of the settled window
|
|
91
|
+
* @property {number | null} childrenSteadyMb median descendant RSS of the settled window
|
|
92
|
+
* @property {number} childrenSpikeMb max descendant RSS
|
|
93
|
+
*/
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* @param {Sample[]} samples
|
|
97
|
+
* @param {{ settleMax?: number, quietSec?: number, settleMin?: number }} [o]
|
|
98
|
+
* @returns {RunSummary}
|
|
99
|
+
*/
|
|
100
|
+
export function summarize(samples, o = {}) {
|
|
101
|
+
if (samples.length === 0) throw new Error("no RSS samples collected");
|
|
102
|
+
const last = samples[samples.length - 1];
|
|
103
|
+
const settle = findSettle(samples, {
|
|
104
|
+
quietSec: o.quietSec,
|
|
105
|
+
settleMax: o.settleMax,
|
|
106
|
+
settleMin: o.settleMin,
|
|
107
|
+
});
|
|
108
|
+
let peak = samples[0];
|
|
109
|
+
for (const s of samples) if (s.rss > peak.rss) peak = s;
|
|
110
|
+
const tail =
|
|
111
|
+
settle.t === null
|
|
112
|
+
? []
|
|
113
|
+
: samples.filter(
|
|
114
|
+
(s) => s.t >= /** @type {number} */ (settle.t) - settle.quietSec,
|
|
115
|
+
);
|
|
116
|
+
return {
|
|
117
|
+
settled: settle.settled,
|
|
118
|
+
settleT: settle.t,
|
|
119
|
+
steadyMb: tail.length ? median(tail.map((s) => s.rss)) : null,
|
|
120
|
+
spikeMb: peak.rss,
|
|
121
|
+
releasedMb: last.rss,
|
|
122
|
+
peakT: peak.t,
|
|
123
|
+
mainSteadyMb: tail.length ? median(tail.map((s) => s.main)) : null,
|
|
124
|
+
childrenSteadyMb: tail.length ? median(tail.map((s) => s.kids)) : null,
|
|
125
|
+
childrenSpikeMb: max(samples.map((s) => s.kids)),
|
|
126
|
+
};
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Seconds from the RSS peak until the delta over the vanilla steady RSS first
|
|
131
|
+
* holds at or below the steady budget for `hold` consecutive samples (one dip
|
|
132
|
+
* does not count: RSS rebounds all the time). 0 when the peak itself is within
|
|
133
|
+
* the budget, null when it never releases within the samples.
|
|
134
|
+
* @param {Sample[]} samples
|
|
135
|
+
* @param {number} vanillaSteadyMb
|
|
136
|
+
* @param {number} steadyBudgetMb
|
|
137
|
+
* @param {number} [hold]
|
|
138
|
+
* @returns {number | null}
|
|
139
|
+
*/
|
|
140
|
+
export function releaseSeconds(
|
|
141
|
+
samples,
|
|
142
|
+
vanillaSteadyMb,
|
|
143
|
+
steadyBudgetMb,
|
|
144
|
+
hold = 3,
|
|
145
|
+
) {
|
|
146
|
+
if (samples.length === 0) return null;
|
|
147
|
+
let peakIdx = 0;
|
|
148
|
+
for (let i = 0; i < samples.length; i++) {
|
|
149
|
+
if (samples[i].rss > samples[peakIdx].rss) peakIdx = i;
|
|
150
|
+
}
|
|
151
|
+
const peak = samples[peakIdx];
|
|
152
|
+
if (peak.rss - vanillaSteadyMb <= steadyBudgetMb) return 0;
|
|
153
|
+
let streak = 0;
|
|
154
|
+
for (let i = peakIdx + 1; i < samples.length; i++) {
|
|
155
|
+
if (samples[i].rss - vanillaSteadyMb <= steadyBudgetMb) {
|
|
156
|
+
streak++;
|
|
157
|
+
if (streak >= hold) return samples[i - streak + 1].t - peak.t;
|
|
158
|
+
} else {
|
|
159
|
+
streak = 0;
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return null;
|
|
163
|
+
}
|