@indigoai-us/hq-cloud 6.16.4 → 6.16.5
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/dist/bin/sync-runner-events.d.ts +10 -0
- package/dist/bin/sync-runner-events.d.ts.map +1 -1
- package/dist/bin/sync-runner-events.js +34 -0
- package/dist/bin/sync-runner-events.js.map +1 -1
- package/dist/bin/sync-runner-events.test.js +65 -1
- package/dist/bin/sync-runner-events.test.js.map +1 -1
- package/dist/bin/sync-runner-heap-telemetry.d.ts +313 -45
- package/dist/bin/sync-runner-heap-telemetry.d.ts.map +1 -1
- package/dist/bin/sync-runner-heap-telemetry.js +503 -114
- package/dist/bin/sync-runner-heap-telemetry.js.map +1 -1
- package/dist/bin/sync-runner-heap-telemetry.test.js +436 -11
- package/dist/bin/sync-runner-heap-telemetry.test.js.map +1 -1
- package/dist/bin/sync-runner-watch-loop.d.ts.map +1 -1
- package/dist/bin/sync-runner-watch-loop.js +69 -9
- package/dist/bin/sync-runner-watch-loop.js.map +1 -1
- package/dist/bin/sync-runner-watch-loop.test.js +13 -1
- package/dist/bin/sync-runner-watch-loop.test.js.map +1 -1
- package/dist/bin/sync-runner.d.ts +27 -1
- package/dist/bin/sync-runner.d.ts.map +1 -1
- package/dist/bin/sync-runner.js +10 -1
- package/dist/bin/sync-runner.js.map +1 -1
- package/dist/watcher.d.ts.map +1 -1
- package/dist/watcher.js +7 -1
- package/dist/watcher.js.map +1 -1
- package/dist/watcher.test.js +54 -0
- package/dist/watcher.test.js.map +1 -1
- package/package.json +1 -1
|
@@ -107,6 +107,15 @@ export function sampleRunnerHeap(deps) {
|
|
|
107
107
|
function finiteNumber(value) {
|
|
108
108
|
return typeof value === "number" && Number.isFinite(value) ? value : 0;
|
|
109
109
|
}
|
|
110
|
+
/** Fold the four cadence counters into a property bag, ahead of per-site keys. */
|
|
111
|
+
function appendCounters(props, counters) {
|
|
112
|
+
if (!counters)
|
|
113
|
+
return;
|
|
114
|
+
props.heap_observations_count = counters.heapObservationsCount;
|
|
115
|
+
props.heap_interval_observations_count = counters.heapIntervalObservationsCount;
|
|
116
|
+
props.heap_checkpoint_observations_count = counters.heapCheckpointObservationsCount;
|
|
117
|
+
props.ms_since_previous_observation_ms = counters.msSincePreviousObservationMs;
|
|
118
|
+
}
|
|
110
119
|
/** Parts-per-thousand, the integer spelling every fraction is emitted as. */
|
|
111
120
|
function toPermille(fraction) {
|
|
112
121
|
return Math.round(fraction * 1000);
|
|
@@ -120,7 +129,7 @@ function toPermille(fraction) {
|
|
|
120
129
|
* actually STORED by ingest (unlike the pre-fix `census_<token>` spelling,
|
|
121
130
|
* which ingest silently dropped, so the attribution never reached the store).
|
|
122
131
|
*/
|
|
123
|
-
export function heapSampleCloudProperties(sample) {
|
|
132
|
+
export function heapSampleCloudProperties(sample, counters) {
|
|
124
133
|
const props = {
|
|
125
134
|
heap_used_bytes: sample.usedHeapBytes,
|
|
126
135
|
heap_total_bytes: sample.totalHeapBytes,
|
|
@@ -132,22 +141,26 @@ export function heapSampleCloudProperties(sample) {
|
|
|
132
141
|
uptime_ms: sample.uptimeMs,
|
|
133
142
|
census_total_count: sample.censusTotal,
|
|
134
143
|
};
|
|
144
|
+
appendCounters(props, counters);
|
|
135
145
|
for (const { site, count } of sample.census) {
|
|
136
146
|
props[`census_${site}_count`] = count;
|
|
137
147
|
}
|
|
138
148
|
return props;
|
|
139
149
|
}
|
|
140
150
|
/** Flatten a pressure record into numeric-only telemetry properties. */
|
|
141
|
-
export function heapPressureCloudProperties(record) {
|
|
151
|
+
export function heapPressureCloudProperties(record, counters) {
|
|
142
152
|
const props = {
|
|
143
153
|
pressure_used_permille_count: toPermille(record.usedFraction),
|
|
144
154
|
pressure_threshold_permille_count: toPermille(record.thresholdFraction),
|
|
145
155
|
heap_used_bytes: record.usedHeapBytes,
|
|
146
156
|
heap_limit_bytes: record.heapLimitBytes,
|
|
157
|
+
heap_effective_limit_bytes: record.effectiveLimitBytes,
|
|
158
|
+
heap_declared_limit_bytes: record.declaredCeilingBytes,
|
|
147
159
|
rss_bytes: record.rssBytes,
|
|
148
160
|
external_bytes: record.externalBytes,
|
|
149
161
|
uptime_ms: record.uptimeMs,
|
|
150
162
|
};
|
|
163
|
+
appendCounters(props, counters);
|
|
151
164
|
for (const { site, count, growth } of record.topSites) {
|
|
152
165
|
props[`${site}_count`] = count;
|
|
153
166
|
props[`${site}_growth_count`] = growth;
|
|
@@ -161,23 +174,32 @@ export function heapPressureStderrLine(record) {
|
|
|
161
174
|
.join(",");
|
|
162
175
|
return ("hq-sync-runner: heap-pressure " +
|
|
163
176
|
`used=${record.usedHeapBytes} limit=${record.heapLimitBytes} ` +
|
|
177
|
+
`eff=${record.effectiveLimitBytes} ` +
|
|
164
178
|
`permille=${toPermille(record.usedFraction)} rss=${record.rssBytes} ` +
|
|
165
179
|
`uptime_ms=${record.uptimeMs} top=${top}`);
|
|
166
180
|
}
|
|
167
181
|
/** Flatten a recycle record into numeric-only telemetry properties. */
|
|
168
|
-
export function heapRecycleCloudProperties(record) {
|
|
182
|
+
export function heapRecycleCloudProperties(record, counters) {
|
|
169
183
|
const props = {
|
|
170
184
|
recycle_used_permille_count: toPermille(record.usedFraction),
|
|
171
185
|
recycle_live_permille_count: toPermille(record.liveFraction),
|
|
172
186
|
recycle_live_floor_permille_count: toPermille(record.recycleLiveFraction),
|
|
187
|
+
recycle_pinned_floor_permille_count: toPermille(record.pinnedFraction),
|
|
173
188
|
recycle_emergency_floor_permille_count: toPermille(record.emergencyFraction),
|
|
189
|
+
recycle_hard_exit_floor_permille_count: toPermille(record.hardExitFraction),
|
|
174
190
|
recycle_emergency_trigger_count: record.trigger === "emergency" ? 1 : 0,
|
|
191
|
+
recycle_pinned_trigger_count: record.trigger === "pinned" ? 1 : 0,
|
|
192
|
+
recycle_latch_timeout_count: record.reason === "latch_timeout" ? 1 : 0,
|
|
193
|
+
recycle_hard_fraction_count: record.reason === "hard_fraction" ? 1 : 0,
|
|
194
|
+
recycle_post_latch_observations_count: record.postLatchObservations,
|
|
175
195
|
recycle_sustain_window_ms: record.sustainWindowMs,
|
|
176
196
|
recycle_observed_sustain_ms: record.observedSustainMs,
|
|
177
197
|
recycle_min_uptime_ms: record.minUptimeMs,
|
|
178
198
|
heap_used_bytes: record.usedHeapBytes,
|
|
179
199
|
heap_live_bytes: record.liveHeapBytes,
|
|
180
200
|
heap_limit_bytes: record.heapLimitBytes,
|
|
201
|
+
heap_effective_limit_bytes: record.effectiveLimitBytes,
|
|
202
|
+
heap_declared_limit_bytes: record.declaredCeilingBytes,
|
|
181
203
|
rss_bytes: record.rssBytes,
|
|
182
204
|
external_bytes: record.externalBytes,
|
|
183
205
|
array_buffers_bytes: record.arrayBuffersBytes,
|
|
@@ -187,6 +209,7 @@ export function heapRecycleCloudProperties(record) {
|
|
|
187
209
|
uptime_ms: record.uptimeMs,
|
|
188
210
|
census_total_count: record.censusTotal,
|
|
189
211
|
};
|
|
212
|
+
appendCounters(props, counters);
|
|
190
213
|
for (const { site, count, growth } of record.topSites) {
|
|
191
214
|
props[`${site}_count`] = count;
|
|
192
215
|
props[`${site}_growth_count`] = growth;
|
|
@@ -207,8 +230,9 @@ export function heapRecycleStderrLine(record) {
|
|
|
207
230
|
.map((entry) => `${entry.site}:${entry.growth}`)
|
|
208
231
|
.join(",");
|
|
209
232
|
return ("hq-sync-runner: heap-recycle " +
|
|
210
|
-
`trigger=${record.trigger} ` +
|
|
233
|
+
`trigger=${record.trigger} reason=${record.reason} ` +
|
|
211
234
|
`used=${record.usedHeapBytes} live=${record.liveHeapBytes} limit=${record.heapLimitBytes} ` +
|
|
235
|
+
`eff=${record.effectiveLimitBytes} ` +
|
|
212
236
|
`live_permille=${toPermille(record.liveFraction)} rss=${record.rssBytes} ` +
|
|
213
237
|
`uptime_ms=${record.uptimeMs} sustain_ms=${record.observedSustainMs} top=${top}`);
|
|
214
238
|
}
|
|
@@ -218,18 +242,12 @@ const DEFAULT_RECYCLE_LIVE_FRACTION = 0.6;
|
|
|
218
242
|
const DEFAULT_RECYCLE_SUSTAIN_WINDOW_MS = 120_000;
|
|
219
243
|
const DEFAULT_RECYCLE_EMERGENCY_FRACTION = 0.9;
|
|
220
244
|
const DEFAULT_RECYCLE_MIN_UPTIME_MS = 35 * 60_000;
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
* - {@link evaluate} and the emergency arm of {@link sample}, the instantaneous
|
|
228
|
-
* BACKSTOP: they recycle on a single sample at/above the emergency fraction
|
|
229
|
-
* even if the GC signal never arrives or the sampler timer is starved.
|
|
230
|
-
* Every fraction is derived from the injected `heap_size_limit`, so the governor
|
|
231
|
-
* self-calibrates to whatever `--max-old-space-size` the desktop supplied.
|
|
232
|
-
*/
|
|
245
|
+
const DEFAULT_RECYCLE_PINNED_FRACTION = 0.84;
|
|
246
|
+
const DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS = 20_000;
|
|
247
|
+
const DEFAULT_HARD_EXIT_FRACTION = 0.955;
|
|
248
|
+
const DEFAULT_LATCH_HARD_EXIT_MS = 60_000;
|
|
249
|
+
const DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS = 240;
|
|
250
|
+
const NO_VERDICT = Object.freeze({ recycle: null, hardExit: null });
|
|
233
251
|
export class RunnerHeapTelemetry {
|
|
234
252
|
readers;
|
|
235
253
|
census;
|
|
@@ -237,17 +255,35 @@ export class RunnerHeapTelemetry {
|
|
|
237
255
|
threshold;
|
|
238
256
|
topSiteCount;
|
|
239
257
|
recycleEnabled;
|
|
258
|
+
declaredCeilingBytes;
|
|
240
259
|
recycleLiveFraction;
|
|
241
260
|
recycleSustainWindowMs;
|
|
242
261
|
recycleEmergencyFraction;
|
|
243
262
|
recycleMinUptimeMs;
|
|
263
|
+
pinnedFraction;
|
|
264
|
+
pinnedSustainWindowMs;
|
|
265
|
+
hardExitFraction;
|
|
266
|
+
latchHardExitMs;
|
|
267
|
+
latchHardExitObservations;
|
|
244
268
|
baseline = null;
|
|
245
269
|
latest = null;
|
|
246
270
|
pressureSignalled = false;
|
|
247
271
|
recycleSignalled = false;
|
|
272
|
+
hardExitSignalled = false;
|
|
248
273
|
/** Uptime (ms) of the first live observation at/above the floor in the
|
|
249
274
|
* current consecutive run; null when the last live reading dipped below it. */
|
|
250
275
|
liveAnchorUptimeMs = null;
|
|
276
|
+
/** Uptime (ms) of the first instantaneous observation at/above the pinned
|
|
277
|
+
* floor in the current consecutive run; null when a reading dipped below it. */
|
|
278
|
+
pinnedAnchorUptimeMs = null;
|
|
279
|
+
/** Consecutive instantaneous observations at/above the pinned floor. */
|
|
280
|
+
pinnedObservationCount = 0;
|
|
281
|
+
/** Uptime (ms) at which the FIRST cooperative latch (any tier) armed. */
|
|
282
|
+
latchedAtUptimeMs = null;
|
|
283
|
+
/** The tier that produced the cooperative latch, carried onto a hard exit. */
|
|
284
|
+
latchedTrigger = null;
|
|
285
|
+
/** Observations seen since the cooperative latch armed (drives latch_timeout). */
|
|
286
|
+
postLatchObservations = 0;
|
|
251
287
|
constructor(options) {
|
|
252
288
|
this.readers = options.readers;
|
|
253
289
|
this.census = options.census;
|
|
@@ -260,6 +296,11 @@ export class RunnerHeapTelemetry {
|
|
|
260
296
|
const count = options.topSiteCount ?? DEFAULT_TOP_SITE_COUNT;
|
|
261
297
|
this.topSiteCount = Number.isFinite(count) && count > 0 ? Math.trunc(count) : DEFAULT_TOP_SITE_COUNT;
|
|
262
298
|
this.recycleEnabled = options.recycleEnabled ?? true;
|
|
299
|
+
const declared = options.declaredCeilingBytes;
|
|
300
|
+
this.declaredCeilingBytes =
|
|
301
|
+
typeof declared === "number" && Number.isFinite(declared) && declared > 0
|
|
302
|
+
? Math.trunc(declared)
|
|
303
|
+
: null;
|
|
263
304
|
this.recycleLiveFraction = fractionOrDefault(options.recycleLiveFraction, DEFAULT_RECYCLE_LIVE_FRACTION);
|
|
264
305
|
const window = options.recycleSustainWindowMs ?? DEFAULT_RECYCLE_SUSTAIN_WINDOW_MS;
|
|
265
306
|
this.recycleSustainWindowMs =
|
|
@@ -270,6 +311,34 @@ export class RunnerHeapTelemetry {
|
|
|
270
311
|
Number.isFinite(minUptime) && minUptime >= 0
|
|
271
312
|
? Math.trunc(minUptime)
|
|
272
313
|
: DEFAULT_RECYCLE_MIN_UPTIME_MS;
|
|
314
|
+
this.pinnedFraction = fractionOrDefault(options.recyclePinnedFraction, DEFAULT_RECYCLE_PINNED_FRACTION);
|
|
315
|
+
const pinnedWindow = options.recyclePinnedSustainWindowMs ?? DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
|
|
316
|
+
this.pinnedSustainWindowMs =
|
|
317
|
+
Number.isFinite(pinnedWindow) && pinnedWindow >= 0
|
|
318
|
+
? Math.trunc(pinnedWindow)
|
|
319
|
+
: DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
|
|
320
|
+
this.hardExitFraction = fractionOrDefault(options.hardExitFraction, DEFAULT_HARD_EXIT_FRACTION);
|
|
321
|
+
const latchMs = options.latchHardExitMs ?? DEFAULT_LATCH_HARD_EXIT_MS;
|
|
322
|
+
this.latchHardExitMs =
|
|
323
|
+
Number.isFinite(latchMs) && latchMs >= 0 ? Math.trunc(latchMs) : DEFAULT_LATCH_HARD_EXIT_MS;
|
|
324
|
+
const latchObs = options.latchHardExitObservations ?? DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS;
|
|
325
|
+
this.latchHardExitObservations =
|
|
326
|
+
Number.isFinite(latchObs) && latchObs >= 1
|
|
327
|
+
? Math.trunc(latchObs)
|
|
328
|
+
: DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS;
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* The one denominator every fraction is computed against: the declared
|
|
332
|
+
* `--max-old-space-size` when known (it is the real V8 ceiling the aborts
|
|
333
|
+
* respect), else V8's reported `heap_size_limit`. Never larger than reported.
|
|
334
|
+
*/
|
|
335
|
+
effectiveLimit(heapLimitBytes) {
|
|
336
|
+
if (this.declaredCeilingBytes === null)
|
|
337
|
+
return heapLimitBytes;
|
|
338
|
+
return Math.min(this.declaredCeilingBytes, heapLimitBytes);
|
|
339
|
+
}
|
|
340
|
+
uptimeNow() {
|
|
341
|
+
return Math.max(0, Math.trunc(this.readers.monotonicNowMs() - this.sessionStartedAtMs));
|
|
273
342
|
}
|
|
274
343
|
/**
|
|
275
344
|
* Capture the growth baseline when sampling starts, before the first interval,
|
|
@@ -283,16 +352,16 @@ export class RunnerHeapTelemetry {
|
|
|
283
352
|
}
|
|
284
353
|
/**
|
|
285
354
|
* The interval sampler tick. Emits a sample and (at most once per rising
|
|
286
|
-
* crossing) a pressure record
|
|
287
|
-
*
|
|
355
|
+
* crossing) a pressure record, then runs the instantaneous tiers (pinned,
|
|
356
|
+
* emergency, hard). The primary post-GC live verdict comes from
|
|
357
|
+
* {@link observeMajorGc}; this instantaneous path catches the starved
|
|
358
|
+
* synchronous stretch where no post-GC reading is ever taken.
|
|
288
359
|
*/
|
|
289
360
|
sample() {
|
|
290
361
|
const sample = this.buildSample();
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
recycle: this.detectEmergency(sample),
|
|
295
|
-
};
|
|
362
|
+
const pressure = this.detectPressure(sample);
|
|
363
|
+
const { recycle, hardExit } = this.observeInstant(sample.usedHeapBytes, sample.heapLimitBytes, sample.uptimeMs, () => sample);
|
|
364
|
+
return { sample, pressure, recycle, hardExit };
|
|
296
365
|
}
|
|
297
366
|
/**
|
|
298
367
|
* The PRIMARY governor path, driven by an observed MAJOR GC. The caller
|
|
@@ -307,58 +376,142 @@ export class RunnerHeapTelemetry {
|
|
|
307
376
|
* below the floor ALWAYS invalidates the sustain run — a throttle that skipped
|
|
308
377
|
* such a reading would let a stale anchor fake a continuous run. The fuller
|
|
309
378
|
* sample (census snapshot + memory deltas) is taken only at the verdict, so a
|
|
310
|
-
* GC storm never costs more than the O(1) statistics read here.
|
|
379
|
+
* GC storm never costs more than the O(1) statistics read here. The fraction
|
|
380
|
+
* is denominated in the EFFECTIVE limit (min(declared, reported)) — the only
|
|
381
|
+
* change from the shipped live-tier logic.
|
|
311
382
|
*/
|
|
312
383
|
observeMajorGc() {
|
|
313
|
-
if (!this.recycleEnabled
|
|
314
|
-
return
|
|
384
|
+
if (!this.recycleEnabled)
|
|
385
|
+
return NO_VERDICT;
|
|
315
386
|
const stats = this.readers.getHeapStatistics();
|
|
316
387
|
const heapLimitBytes = finiteNumber(stats.heap_size_limit);
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
const
|
|
321
|
-
|
|
322
|
-
//
|
|
388
|
+
const effective = this.effectiveLimit(heapLimitBytes);
|
|
389
|
+
if (effective <= 0)
|
|
390
|
+
return NO_VERDICT;
|
|
391
|
+
const liveFraction = finiteNumber(stats.used_heap_size) / effective;
|
|
392
|
+
const uptimeMs = this.uptimeNow();
|
|
393
|
+
// T4 hard: a post-GC reading is the cleanest instantaneous value, so the
|
|
394
|
+
// hard-fraction and the aged-latch backstops are evaluated here too.
|
|
395
|
+
const hardExit = this.checkHardExit(liveFraction, uptimeMs);
|
|
396
|
+
if (hardExit)
|
|
397
|
+
return { recycle: null, hardExit };
|
|
398
|
+
if (this.recycleSignalled)
|
|
399
|
+
return NO_VERDICT;
|
|
400
|
+
// T3 emergency: a genuine post-GC reading already abort-adjacent — cooperative
|
|
401
|
+
// recycle now, bypassing both the sustain window and the uptime floor.
|
|
323
402
|
if (liveFraction >= this.recycleEmergencyFraction) {
|
|
324
|
-
return this.
|
|
403
|
+
return { recycle: this.armCooperativeLatch("emergency", 0), hardExit: null };
|
|
325
404
|
}
|
|
405
|
+
// T1 live: the post-GC live floor held across the sustain window.
|
|
326
406
|
if (liveFraction < this.recycleLiveFraction) {
|
|
327
407
|
// The live floor dipped: reset the anchor so the window only ever measures
|
|
328
408
|
// a genuinely continuous run at/above the floor.
|
|
329
409
|
this.liveAnchorUptimeMs = null;
|
|
330
|
-
return
|
|
410
|
+
return NO_VERDICT;
|
|
331
411
|
}
|
|
332
412
|
if (this.liveAnchorUptimeMs === null) {
|
|
333
413
|
// First qualifying observation. A second, at least a window later, confirms.
|
|
334
414
|
this.liveAnchorUptimeMs = uptimeMs;
|
|
335
|
-
return
|
|
415
|
+
return NO_VERDICT;
|
|
336
416
|
}
|
|
337
417
|
const observedSustainMs = Math.max(0, uptimeMs - this.liveAnchorUptimeMs);
|
|
338
418
|
if (observedSustainMs < this.recycleSustainWindowMs)
|
|
339
|
-
return
|
|
419
|
+
return NO_VERDICT;
|
|
340
420
|
if (uptimeMs < this.recycleMinUptimeMs)
|
|
341
|
-
return
|
|
342
|
-
return this.
|
|
421
|
+
return NO_VERDICT;
|
|
422
|
+
return { recycle: this.armCooperativeLatch("live", observedSustainMs), hardExit: null };
|
|
343
423
|
}
|
|
344
424
|
/**
|
|
345
|
-
* The loop-top BACKSTOP against timer starvation (the observed
|
|
346
|
-
* sampler hole). Reads the instantaneous heap and runs the
|
|
347
|
-
*
|
|
348
|
-
*
|
|
349
|
-
* statistics read, sampling the census only if
|
|
425
|
+
* The loop-top / work-driven BACKSTOP against timer starvation (the observed
|
|
426
|
+
* 11-minute sampler hole). Reads the instantaneous heap and runs the
|
|
427
|
+
* instantaneous tiers (hard, emergency, pinned). An instantaneous reading can
|
|
428
|
+
* never confirm the post-GC live floor, so it never feeds the live tier's
|
|
429
|
+
* sustain window. Cheap: an O(1) statistics read, sampling the census only if
|
|
430
|
+
* a verdict actually fires.
|
|
350
431
|
*/
|
|
351
432
|
evaluate() {
|
|
352
|
-
if (!this.recycleEnabled
|
|
353
|
-
return
|
|
433
|
+
if (!this.recycleEnabled)
|
|
434
|
+
return NO_VERDICT;
|
|
354
435
|
const stats = this.readers.getHeapStatistics();
|
|
355
436
|
const heapLimitBytes = finiteNumber(stats.heap_size_limit);
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
437
|
+
const usedHeapBytes = finiteNumber(stats.used_heap_size);
|
|
438
|
+
const uptimeMs = this.uptimeNow();
|
|
439
|
+
return this.observeInstant(usedHeapBytes, heapLimitBytes, uptimeMs, () => this.buildSample());
|
|
440
|
+
}
|
|
441
|
+
/**
|
|
442
|
+
* The shared instantaneous tier pipeline (interval tick, loop-top, and the
|
|
443
|
+
* work-driven checkpoint all reach it). Order: T4 hard (hard-fraction, then an
|
|
444
|
+
* aged-out latch) → T3 emergency (single observation, bypasses window+floor) →
|
|
445
|
+
* T2 pinned (instantaneous fraction sustained across the pinned window past the
|
|
446
|
+
* uptime floor, with any dip resetting the anchor). The full sample is built
|
|
447
|
+
* only at a verdict, via `buildVerdictSample`.
|
|
448
|
+
*/
|
|
449
|
+
observeInstant(usedHeapBytes, heapLimitBytes, uptimeMs, buildVerdictSample) {
|
|
450
|
+
if (!this.recycleEnabled)
|
|
451
|
+
return NO_VERDICT;
|
|
452
|
+
const effective = this.effectiveLimit(heapLimitBytes);
|
|
453
|
+
if (effective <= 0)
|
|
454
|
+
return NO_VERDICT;
|
|
455
|
+
const usedFraction = usedHeapBytes / effective;
|
|
456
|
+
const hardExit = this.checkHardExit(usedFraction, uptimeMs, buildVerdictSample);
|
|
457
|
+
if (hardExit)
|
|
458
|
+
return { recycle: null, hardExit };
|
|
459
|
+
if (this.recycleSignalled)
|
|
460
|
+
return NO_VERDICT;
|
|
461
|
+
// T3 emergency: single instantaneous observation, bypasses window + floor.
|
|
462
|
+
if (usedFraction >= this.recycleEmergencyFraction) {
|
|
463
|
+
return { recycle: this.armCooperativeLatch("emergency", 0, buildVerdictSample), hardExit: null };
|
|
464
|
+
}
|
|
465
|
+
// T2 pinned: instantaneous fraction held across the pinned window.
|
|
466
|
+
if (usedFraction < this.pinnedFraction) {
|
|
467
|
+
this.pinnedAnchorUptimeMs = null;
|
|
468
|
+
this.pinnedObservationCount = 0;
|
|
469
|
+
return NO_VERDICT;
|
|
470
|
+
}
|
|
471
|
+
if (this.pinnedAnchorUptimeMs === null) {
|
|
472
|
+
this.pinnedAnchorUptimeMs = uptimeMs;
|
|
473
|
+
this.pinnedObservationCount = 1;
|
|
474
|
+
return NO_VERDICT;
|
|
475
|
+
}
|
|
476
|
+
this.pinnedObservationCount += 1;
|
|
477
|
+
const observedSustainMs = Math.max(0, uptimeMs - this.pinnedAnchorUptimeMs);
|
|
478
|
+
if (observedSustainMs < this.pinnedSustainWindowMs)
|
|
479
|
+
return NO_VERDICT;
|
|
480
|
+
if (this.pinnedObservationCount < 2)
|
|
481
|
+
return NO_VERDICT;
|
|
482
|
+
if (uptimeMs < this.recycleMinUptimeMs)
|
|
483
|
+
return NO_VERDICT;
|
|
484
|
+
return {
|
|
485
|
+
recycle: this.armCooperativeLatch("pinned", observedSustainMs, buildVerdictSample),
|
|
486
|
+
hardExit: null,
|
|
487
|
+
};
|
|
488
|
+
}
|
|
489
|
+
/**
|
|
490
|
+
* T4 hard-exit evaluation, run at EVERY observation point. Fires at most once
|
|
491
|
+
* per session (independent of the cooperative latch), on either arm:
|
|
492
|
+
* (a) `hard_fraction` — the instantaneous fraction is at/above the hard line;
|
|
493
|
+
* (b) `latch_timeout` — a cooperative latch aged past its time OR observation
|
|
494
|
+
* deadline without the loop honouring it.
|
|
495
|
+
* The `latch_timeout` observation counter advances on every later observation,
|
|
496
|
+
* never on the observation that armed the latch (that call sees a still-false
|
|
497
|
+
* `recycleSignalled` before the cooperative tier runs).
|
|
498
|
+
*/
|
|
499
|
+
checkHardExit(fraction, uptimeMs, buildVerdictSample) {
|
|
500
|
+
if (!this.recycleEnabled || this.hardExitSignalled)
|
|
360
501
|
return null;
|
|
361
|
-
|
|
502
|
+
const build = buildVerdictSample ?? (() => this.buildSample());
|
|
503
|
+
if (Number.isFinite(fraction) && fraction >= this.hardExitFraction) {
|
|
504
|
+
return this.armHardExit(build(), "hard_fraction");
|
|
505
|
+
}
|
|
506
|
+
if (this.recycleSignalled && this.latchedAtUptimeMs !== null) {
|
|
507
|
+
this.postLatchObservations += 1;
|
|
508
|
+
const agedMs = uptimeMs - this.latchedAtUptimeMs;
|
|
509
|
+
if (agedMs >= this.latchHardExitMs ||
|
|
510
|
+
this.postLatchObservations >= this.latchHardExitObservations) {
|
|
511
|
+
return this.armHardExit(build(), "latch_timeout");
|
|
512
|
+
}
|
|
513
|
+
}
|
|
514
|
+
return null;
|
|
362
515
|
}
|
|
363
516
|
buildSample() {
|
|
364
517
|
const sample = sampleRunnerHeap({
|
|
@@ -372,44 +525,45 @@ export class RunnerHeapTelemetry {
|
|
|
372
525
|
this.latest = sample;
|
|
373
526
|
return sample;
|
|
374
527
|
}
|
|
375
|
-
/**
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
return this.produceRecycle(sample, "emergency", usedFraction, 0);
|
|
528
|
+
/** Arm the one cooperative latch (from any tier) and build its verdict. */
|
|
529
|
+
armCooperativeLatch(trigger, observedSustainMs, buildVerdictSample) {
|
|
530
|
+
this.recycleSignalled = true;
|
|
531
|
+
const sample = (buildVerdictSample ?? (() => this.buildSample()))();
|
|
532
|
+
if (this.latchedAtUptimeMs === null) {
|
|
533
|
+
this.latchedAtUptimeMs = sample.uptimeMs;
|
|
534
|
+
this.latchedTrigger = trigger;
|
|
535
|
+
this.postLatchObservations = 0;
|
|
536
|
+
}
|
|
537
|
+
return this.buildRecord(sample, trigger, "cooperative", observedSustainMs);
|
|
386
538
|
}
|
|
387
|
-
/**
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
produceRecycleFromCurrent(trigger, observedSustainMs) {
|
|
393
|
-
const sample = this.buildSample();
|
|
394
|
-
const liveFraction = sample.heapLimitBytes > 0 ? sample.usedHeapBytes / sample.heapLimitBytes : 0;
|
|
395
|
-
return this.produceRecycle(sample, trigger, liveFraction, observedSustainMs);
|
|
539
|
+
/** Arm the one hard exit and build its verdict (`hard_fraction`/`latch_timeout`). */
|
|
540
|
+
armHardExit(sample, reason) {
|
|
541
|
+
this.hardExitSignalled = true;
|
|
542
|
+
const trigger = this.latchedTrigger ?? "emergency";
|
|
543
|
+
return this.buildRecord(sample, trigger, reason, 0);
|
|
396
544
|
}
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
const usedFraction =
|
|
545
|
+
buildRecord(sample, trigger, reason, observedSustainMs) {
|
|
546
|
+
const effective = this.effectiveLimit(sample.heapLimitBytes);
|
|
547
|
+
const usedFraction = effective > 0 ? sample.usedHeapBytes / effective : 0;
|
|
400
548
|
const baseline = this.baseline;
|
|
401
549
|
return {
|
|
402
550
|
trigger,
|
|
551
|
+
reason,
|
|
403
552
|
usedHeapBytes: sample.usedHeapBytes,
|
|
404
553
|
liveHeapBytes: sample.usedHeapBytes,
|
|
405
554
|
heapLimitBytes: sample.heapLimitBytes,
|
|
555
|
+
effectiveLimitBytes: effective,
|
|
556
|
+
declaredCeilingBytes: this.declaredCeilingBytes ?? 0,
|
|
406
557
|
usedFraction,
|
|
407
|
-
liveFraction,
|
|
558
|
+
liveFraction: usedFraction,
|
|
408
559
|
recycleLiveFraction: this.recycleLiveFraction,
|
|
560
|
+
pinnedFraction: this.pinnedFraction,
|
|
409
561
|
emergencyFraction: this.recycleEmergencyFraction,
|
|
562
|
+
hardExitFraction: this.hardExitFraction,
|
|
410
563
|
sustainWindowMs: this.recycleSustainWindowMs,
|
|
411
564
|
observedSustainMs,
|
|
412
565
|
minUptimeMs: this.recycleMinUptimeMs,
|
|
566
|
+
postLatchObservations: reason === "latch_timeout" ? this.postLatchObservations : 0,
|
|
413
567
|
uptimeMs: sample.uptimeMs,
|
|
414
568
|
rssBytes: sample.rssBytes,
|
|
415
569
|
externalBytes: sample.externalBytes,
|
|
@@ -422,9 +576,10 @@ export class RunnerHeapTelemetry {
|
|
|
422
576
|
};
|
|
423
577
|
}
|
|
424
578
|
detectPressure(sample) {
|
|
425
|
-
|
|
579
|
+
const effective = this.effectiveLimit(sample.heapLimitBytes);
|
|
580
|
+
if (effective <= 0)
|
|
426
581
|
return null;
|
|
427
|
-
const usedFraction = sample.usedHeapBytes /
|
|
582
|
+
const usedFraction = sample.usedHeapBytes / effective;
|
|
428
583
|
if (usedFraction < this.threshold) {
|
|
429
584
|
// Re-arm below the threshold so a genuine later crossing escalates again.
|
|
430
585
|
this.pressureSignalled = false;
|
|
@@ -436,6 +591,8 @@ export class RunnerHeapTelemetry {
|
|
|
436
591
|
return {
|
|
437
592
|
usedHeapBytes: sample.usedHeapBytes,
|
|
438
593
|
heapLimitBytes: sample.heapLimitBytes,
|
|
594
|
+
effectiveLimitBytes: effective,
|
|
595
|
+
declaredCeilingBytes: this.declaredCeilingBytes ?? 0,
|
|
439
596
|
usedFraction,
|
|
440
597
|
thresholdFraction: this.threshold,
|
|
441
598
|
rssBytes: sample.rssBytes,
|
|
@@ -549,13 +706,16 @@ export function nodeMajorGcObserver() {
|
|
|
549
706
|
};
|
|
550
707
|
}
|
|
551
708
|
const DEFAULT_SAMPLE_INTERVAL_MS = 60_000;
|
|
709
|
+
const DEFAULT_CHECKPOINT_MS = 250;
|
|
552
710
|
/**
|
|
553
711
|
* Start periodic sampling and, when a GC observer is supplied, the primary
|
|
554
712
|
* live-heap path. The interval timer is `unref`'d so it can never hold the
|
|
555
713
|
* process open, and `stop()` clears it and disconnects the GC observer on every
|
|
556
|
-
* shutdown path.
|
|
557
|
-
* `evaluate()`
|
|
558
|
-
*
|
|
714
|
+
* shutdown path. The interval tick, the work-driven checkpoint, and the loop-top
|
|
715
|
+
* `evaluate()` share ONE observation pipeline, one last-observation timestamp,
|
|
716
|
+
* and one set of cadence counters. Each observation — and every emit callback it
|
|
717
|
+
* drives — is wrapped so a fault degrades to silence and never affects the watch
|
|
718
|
+
* cycle.
|
|
559
719
|
*/
|
|
560
720
|
export function startRunnerHeapSampling(options) {
|
|
561
721
|
const telemetry = new RunnerHeapTelemetry(options);
|
|
@@ -572,46 +732,104 @@ export function startRunnerHeapSampling(options) {
|
|
|
572
732
|
const intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0
|
|
573
733
|
? Math.trunc(options.intervalMs)
|
|
574
734
|
: DEFAULT_SAMPLE_INTERVAL_MS;
|
|
735
|
+
const checkpointMs = options.checkpointMs === undefined
|
|
736
|
+
? DEFAULT_CHECKPOINT_MS
|
|
737
|
+
: Number.isFinite(options.checkpointMs) && options.checkpointMs >= 0
|
|
738
|
+
? Math.trunc(options.checkpointMs)
|
|
739
|
+
: DEFAULT_CHECKPOINT_MS;
|
|
575
740
|
let stopped = false;
|
|
576
|
-
//
|
|
577
|
-
//
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
741
|
+
// Shared observation state — interval, checkpoint, and loop-top feed the SAME
|
|
742
|
+
// pipeline, one last-observation timestamp, and one set of cadence counters.
|
|
743
|
+
let lastObservationAtMs = null;
|
|
744
|
+
let observationCount = 0;
|
|
745
|
+
let intervalObservationCount = 0;
|
|
746
|
+
let checkpointObservationCount = 0;
|
|
747
|
+
const snapshotCounters = (msSincePrev) => ({
|
|
748
|
+
heapObservationsCount: observationCount,
|
|
749
|
+
heapIntervalObservationsCount: intervalObservationCount,
|
|
750
|
+
heapCheckpointObservationsCount: checkpointObservationCount,
|
|
751
|
+
msSincePreviousObservationMs: msSincePrev,
|
|
752
|
+
});
|
|
753
|
+
// Deliver at most one verdict: a hard exit preempts the cooperative recycle on
|
|
754
|
+
// the same observation (the process is leaving now); both callbacks are wrapped
|
|
755
|
+
// so a fault degrades to silence and never disturbs a watch cycle.
|
|
756
|
+
const deliver = (recycle, hardExit, counters) => {
|
|
757
|
+
if (hardExit && options.onHardExit) {
|
|
758
|
+
try {
|
|
759
|
+
options.onHardExit(hardExit, counters);
|
|
760
|
+
}
|
|
761
|
+
catch (err) {
|
|
762
|
+
warn(options.log, err);
|
|
763
|
+
}
|
|
581
764
|
}
|
|
582
|
-
|
|
583
|
-
|
|
765
|
+
else if (recycle) {
|
|
766
|
+
try {
|
|
767
|
+
options.onRecycle?.(recycle, counters);
|
|
768
|
+
}
|
|
769
|
+
catch (err) {
|
|
770
|
+
warn(options.log, err);
|
|
771
|
+
}
|
|
584
772
|
}
|
|
585
773
|
};
|
|
586
|
-
|
|
774
|
+
// The one observation pipeline. `source` distinguishes the 60 s interval tick
|
|
775
|
+
// (which emits a cloud sample) from a checkpoint/loop-top (which never does).
|
|
776
|
+
// `gated` is true only for the work-driven checkpoint: it is throttled to
|
|
777
|
+
// `checkpointMs` and disabled entirely when `checkpointMs <= 0`. The loop-top
|
|
778
|
+
// `evaluate()` passes gated=false so it keeps working with checkpoints off,
|
|
779
|
+
// preserving the shipped behaviour exactly.
|
|
780
|
+
const runObservation = (source, gated) => {
|
|
587
781
|
if (stopped)
|
|
588
782
|
return;
|
|
589
783
|
try {
|
|
590
|
-
const
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
784
|
+
const now = options.readers.monotonicNowMs();
|
|
785
|
+
if (gated) {
|
|
786
|
+
if (checkpointMs <= 0)
|
|
787
|
+
return; // checkpoints disabled
|
|
788
|
+
if (lastObservationAtMs !== null && now - lastObservationAtMs < checkpointMs) {
|
|
789
|
+
return; // below the gate: one clock compare and out
|
|
790
|
+
}
|
|
596
791
|
}
|
|
597
|
-
|
|
792
|
+
const msSincePrev = lastObservationAtMs === null ? 0 : Math.max(0, Math.trunc(now - lastObservationAtMs));
|
|
793
|
+
lastObservationAtMs = now;
|
|
794
|
+
observationCount += 1;
|
|
795
|
+
if (source === "interval")
|
|
796
|
+
intervalObservationCount += 1;
|
|
797
|
+
else
|
|
798
|
+
checkpointObservationCount += 1;
|
|
799
|
+
const counters = snapshotCounters(msSincePrev);
|
|
800
|
+
if (source === "interval") {
|
|
801
|
+
const { sample, pressure, recycle, hardExit } = telemetry.sample();
|
|
598
802
|
try {
|
|
599
|
-
options.
|
|
803
|
+
options.onSample(sample, counters);
|
|
600
804
|
}
|
|
601
805
|
catch (err) {
|
|
602
806
|
warn(options.log, err);
|
|
603
807
|
}
|
|
808
|
+
if (pressure) {
|
|
809
|
+
try {
|
|
810
|
+
options.onPressure(pressure, counters);
|
|
811
|
+
}
|
|
812
|
+
catch (err) {
|
|
813
|
+
warn(options.log, err);
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
deliver(recycle, hardExit, counters);
|
|
817
|
+
}
|
|
818
|
+
else {
|
|
819
|
+
const { recycle, hardExit } = telemetry.evaluate();
|
|
820
|
+
deliver(recycle, hardExit, counters);
|
|
604
821
|
}
|
|
605
|
-
if (recycle)
|
|
606
|
-
fireRecycle(recycle);
|
|
607
822
|
}
|
|
608
823
|
catch (err) {
|
|
609
824
|
warn(options.log, err);
|
|
610
825
|
}
|
|
611
826
|
};
|
|
612
|
-
const handle = scheduler.setInterval(
|
|
827
|
+
const handle = scheduler.setInterval(() => runObservation("interval", false), intervalMs);
|
|
613
828
|
handle.unref?.();
|
|
614
|
-
// The primary path: a major GC drives one
|
|
829
|
+
// The primary path: a major GC drives one post-GC live evaluation. It also
|
|
830
|
+
// evaluates the hard tiers (a post-GC reading is the cleanest instantaneous
|
|
831
|
+
// value), so a latch that aged out or a hard-fraction crossing hard-exits here
|
|
832
|
+
// too. It is orthogonal to the cadence gate, so it never touches its counters.
|
|
615
833
|
const gcObserver = options.gcObserver;
|
|
616
834
|
if (gcObserver) {
|
|
617
835
|
try {
|
|
@@ -619,9 +837,9 @@ export function startRunnerHeapSampling(options) {
|
|
|
619
837
|
if (stopped)
|
|
620
838
|
return;
|
|
621
839
|
try {
|
|
622
|
-
const recycle = telemetry.observeMajorGc();
|
|
623
|
-
if (recycle)
|
|
624
|
-
|
|
840
|
+
const { recycle, hardExit } = telemetry.observeMajorGc();
|
|
841
|
+
if (recycle || hardExit)
|
|
842
|
+
deliver(recycle, hardExit, snapshotCounters(0));
|
|
625
843
|
}
|
|
626
844
|
catch (err) {
|
|
627
845
|
warn(options.log, err);
|
|
@@ -634,18 +852,8 @@ export function startRunnerHeapSampling(options) {
|
|
|
634
852
|
}
|
|
635
853
|
return {
|
|
636
854
|
telemetry,
|
|
637
|
-
evaluate: () =>
|
|
638
|
-
|
|
639
|
-
return;
|
|
640
|
-
try {
|
|
641
|
-
const recycle = telemetry.evaluate();
|
|
642
|
-
if (recycle)
|
|
643
|
-
fireRecycle(recycle);
|
|
644
|
-
}
|
|
645
|
-
catch (err) {
|
|
646
|
-
warn(options.log, err);
|
|
647
|
-
}
|
|
648
|
-
},
|
|
855
|
+
evaluate: () => runObservation("checkpoint", false),
|
|
856
|
+
maybeObserve: () => runObservation("checkpoint", true),
|
|
649
857
|
stop: () => {
|
|
650
858
|
if (stopped)
|
|
651
859
|
return;
|
|
@@ -665,6 +873,34 @@ export function startRunnerHeapSampling(options) {
|
|
|
665
873
|
},
|
|
666
874
|
};
|
|
667
875
|
}
|
|
876
|
+
/**
|
|
877
|
+
* Perform a deliberate hard exit for a `hard_fraction`/`latch_timeout` verdict.
|
|
878
|
+
* Writes the additive `heap-recycle` NDJSON record to stdout and the compact
|
|
879
|
+
* numeric stderr line — through SYNCHRONOUS injected writers, so both records
|
|
880
|
+
* land even when the streams are buffered or blocked — and only THEN exits. The
|
|
881
|
+
* exit code and the writers are injected so the exact write-before-exit ordering
|
|
882
|
+
* is unit-testable and the code stays the runner's single benign-exit constant.
|
|
883
|
+
*/
|
|
884
|
+
export function performHeapHardExit(record, io, exitCode) {
|
|
885
|
+
// Both diagnostic writes are BEST-EFFORT: if the supervisor or a pipeline has
|
|
886
|
+
// closed stdout/stderr, a synchronous write can throw — but the exit is the
|
|
887
|
+
// whole point of this path (it replaces the V8 abort), so it must still run.
|
|
888
|
+
// The verdict is already latched one-shot, so a swallowed write with no exit
|
|
889
|
+
// would let the process climb on to the OOM this path exists to prevent.
|
|
890
|
+
try {
|
|
891
|
+
io.writeStdout(`${JSON.stringify({ type: "heap-recycle", ...record })}\n`);
|
|
892
|
+
}
|
|
893
|
+
catch {
|
|
894
|
+
/* stream closed — the fd-1 record is lost, but the exit still happens */
|
|
895
|
+
}
|
|
896
|
+
try {
|
|
897
|
+
io.writeStderr(`${heapRecycleStderrLine(record)}\n`);
|
|
898
|
+
}
|
|
899
|
+
catch {
|
|
900
|
+
/* stream closed — the stderr line is lost, but the exit still happens */
|
|
901
|
+
}
|
|
902
|
+
io.exit(exitCode);
|
|
903
|
+
}
|
|
668
904
|
const defaultScheduler = {
|
|
669
905
|
setInterval: (handler, ms) => setInterval(handler, ms),
|
|
670
906
|
clearInterval: (handle) => clearInterval(handle),
|
|
@@ -685,12 +921,23 @@ export const HEAP_RECYCLE_LIVE_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_LIVE_
|
|
|
685
921
|
export const HEAP_RECYCLE_SUSTAIN_WINDOW_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_SUSTAIN_WINDOW_MS";
|
|
686
922
|
export const HEAP_RECYCLE_EMERGENCY_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_EMERGENCY_FRACTION";
|
|
687
923
|
export const HEAP_RECYCLE_MIN_UPTIME_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_MIN_UPTIME_MS";
|
|
924
|
+
export const HEAP_CHECKPOINT_MS_ENV = "HQ_SYNC_RUNNER_HEAP_CHECKPOINT_MS";
|
|
925
|
+
export const HEAP_PINNED_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_PINNED_FRACTION";
|
|
926
|
+
export const HEAP_PINNED_SUSTAIN_MS_ENV = "HQ_SYNC_RUNNER_HEAP_PINNED_SUSTAIN_MS";
|
|
927
|
+
export const HEAP_HARD_EXIT_FRACTION_ENV = "HQ_SYNC_RUNNER_HEAP_HARD_EXIT_FRACTION";
|
|
928
|
+
export const HEAP_RECYCLE_LATCH_HARD_EXIT_MS_ENV = "HQ_SYNC_RUNNER_HEAP_RECYCLE_LATCH_HARD_EXIT_MS";
|
|
688
929
|
export const DEFAULT_HEAP_SAMPLE_INTERVAL_MS = DEFAULT_SAMPLE_INTERVAL_MS;
|
|
689
930
|
export const DEFAULT_HEAP_PRESSURE_FRACTION = DEFAULT_PRESSURE_THRESHOLD;
|
|
690
931
|
export const DEFAULT_HEAP_RECYCLE_LIVE_FRACTION = DEFAULT_RECYCLE_LIVE_FRACTION;
|
|
691
932
|
export const DEFAULT_HEAP_RECYCLE_SUSTAIN_WINDOW_MS = DEFAULT_RECYCLE_SUSTAIN_WINDOW_MS;
|
|
692
933
|
export const DEFAULT_HEAP_RECYCLE_EMERGENCY_FRACTION = DEFAULT_RECYCLE_EMERGENCY_FRACTION;
|
|
693
934
|
export const DEFAULT_HEAP_RECYCLE_MIN_UPTIME_MS = DEFAULT_RECYCLE_MIN_UPTIME_MS;
|
|
935
|
+
export const DEFAULT_HEAP_CHECKPOINT_MS = DEFAULT_CHECKPOINT_MS;
|
|
936
|
+
export const DEFAULT_HEAP_PINNED_FRACTION = DEFAULT_RECYCLE_PINNED_FRACTION;
|
|
937
|
+
export const DEFAULT_HEAP_PINNED_SUSTAIN_MS = DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
|
|
938
|
+
export const DEFAULT_HEAP_HARD_EXIT_FRACTION = DEFAULT_HARD_EXIT_FRACTION;
|
|
939
|
+
export const DEFAULT_HEAP_RECYCLE_LATCH_HARD_EXIT_MS = DEFAULT_LATCH_HARD_EXIT_MS;
|
|
940
|
+
export const DEFAULT_HEAP_RECYCLE_LATCH_HARD_EXIT_OBSERVATIONS = DEFAULT_LATCH_HARD_EXIT_OBSERVATIONS;
|
|
694
941
|
/**
|
|
695
942
|
* Parse the sampling-interval env knob (whole milliseconds). Rejects the ENTIRE
|
|
696
943
|
* string: a value like "60s" must fall back to the default, not silently parse
|
|
@@ -790,6 +1037,148 @@ export function resolveHeapRecycleMinUptimeMs(raw) {
|
|
|
790
1037
|
const value = Number.parseInt(trimmed, 10);
|
|
791
1038
|
return Number.isFinite(value) && value >= 0 ? value : DEFAULT_RECYCLE_MIN_UPTIME_MS;
|
|
792
1039
|
}
|
|
1040
|
+
/**
|
|
1041
|
+
* Parse the checkpoint-gate knob (whole milliseconds, >= 0). 0 is a VALID value
|
|
1042
|
+
* — it disables the work-driven checkpoints, leaving the interval timer and the
|
|
1043
|
+
* loop-top backstop as the only observers (exact base behaviour) — so only a
|
|
1044
|
+
* non-integer or negative value falls back to the 250 ms default.
|
|
1045
|
+
*/
|
|
1046
|
+
export function resolveHeapCheckpointMs(raw) {
|
|
1047
|
+
if (raw === undefined)
|
|
1048
|
+
return DEFAULT_CHECKPOINT_MS;
|
|
1049
|
+
const trimmed = raw.trim();
|
|
1050
|
+
if (!/^\d+$/.test(trimmed))
|
|
1051
|
+
return DEFAULT_CHECKPOINT_MS;
|
|
1052
|
+
const value = Number.parseInt(trimmed, 10);
|
|
1053
|
+
return Number.isFinite(value) && value >= 0 ? value : DEFAULT_CHECKPOINT_MS;
|
|
1054
|
+
}
|
|
1055
|
+
/**
|
|
1056
|
+
* Parse the pinned-fraction knob; falls back to the default (0.84) on garbage or
|
|
1057
|
+
* out-of-range input. Rejects the entire string rather than a numeric prefix.
|
|
1058
|
+
*/
|
|
1059
|
+
export function resolveHeapPinnedFraction(raw) {
|
|
1060
|
+
if (raw === undefined)
|
|
1061
|
+
return DEFAULT_RECYCLE_PINNED_FRACTION;
|
|
1062
|
+
const trimmed = raw.trim();
|
|
1063
|
+
if (!/^\d*\.?\d+$/.test(trimmed))
|
|
1064
|
+
return DEFAULT_RECYCLE_PINNED_FRACTION;
|
|
1065
|
+
const value = Number.parseFloat(trimmed);
|
|
1066
|
+
return Number.isFinite(value) && value > 0 && value <= 1
|
|
1067
|
+
? value
|
|
1068
|
+
: DEFAULT_RECYCLE_PINNED_FRACTION;
|
|
1069
|
+
}
|
|
1070
|
+
/**
|
|
1071
|
+
* Parse the pinned-sustain-window knob (whole milliseconds, >= 0). 0 is a VALID
|
|
1072
|
+
* value — it removes the window so two qualifying observations at the same uptime
|
|
1073
|
+
* suffice, which the deterministic tests rely on — so only a non-integer or
|
|
1074
|
+
* negative value falls back to the 20-second default.
|
|
1075
|
+
*/
|
|
1076
|
+
export function resolveHeapPinnedSustainMs(raw) {
|
|
1077
|
+
if (raw === undefined)
|
|
1078
|
+
return DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
|
|
1079
|
+
const trimmed = raw.trim();
|
|
1080
|
+
if (!/^\d+$/.test(trimmed))
|
|
1081
|
+
return DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
|
|
1082
|
+
const value = Number.parseInt(trimmed, 10);
|
|
1083
|
+
return Number.isFinite(value) && value >= 0
|
|
1084
|
+
? value
|
|
1085
|
+
: DEFAULT_RECYCLE_PINNED_SUSTAIN_WINDOW_MS;
|
|
1086
|
+
}
|
|
1087
|
+
/**
|
|
1088
|
+
* Parse the hard-exit-fraction knob; falls back to the default (0.955) on garbage
|
|
1089
|
+
* or out-of-range input. Rejects the entire string rather than a numeric prefix.
|
|
1090
|
+
*/
|
|
1091
|
+
export function resolveHeapHardExitFraction(raw) {
|
|
1092
|
+
if (raw === undefined)
|
|
1093
|
+
return DEFAULT_HARD_EXIT_FRACTION;
|
|
1094
|
+
const trimmed = raw.trim();
|
|
1095
|
+
if (!/^\d*\.?\d+$/.test(trimmed))
|
|
1096
|
+
return DEFAULT_HARD_EXIT_FRACTION;
|
|
1097
|
+
const value = Number.parseFloat(trimmed);
|
|
1098
|
+
return Number.isFinite(value) && value > 0 && value <= 1 ? value : DEFAULT_HARD_EXIT_FRACTION;
|
|
1099
|
+
}
|
|
1100
|
+
/**
|
|
1101
|
+
* Parse the latch-hard-exit knob (whole milliseconds, >= 0). 0 is a VALID value
|
|
1102
|
+
* — it makes the first post-latch observation hard-exit — so only a non-integer
|
|
1103
|
+
* or negative value falls back to the 60-second default.
|
|
1104
|
+
*/
|
|
1105
|
+
export function resolveHeapRecycleLatchHardExitMs(raw) {
|
|
1106
|
+
if (raw === undefined)
|
|
1107
|
+
return DEFAULT_LATCH_HARD_EXIT_MS;
|
|
1108
|
+
const trimmed = raw.trim();
|
|
1109
|
+
if (!/^\d+$/.test(trimmed))
|
|
1110
|
+
return DEFAULT_LATCH_HARD_EXIT_MS;
|
|
1111
|
+
const value = Number.parseInt(trimmed, 10);
|
|
1112
|
+
return Number.isFinite(value) && value >= 0 ? value : DEFAULT_LATCH_HARD_EXIT_MS;
|
|
1113
|
+
}
|
|
1114
|
+
const MAX_OLD_SPACE_FLAG = /^--max[-_]old[-_]space[-_]size$/;
|
|
1115
|
+
/** A whole positive integer of MB → bytes, else null (whole-string only). */
|
|
1116
|
+
function wholeMbToBytes(raw) {
|
|
1117
|
+
const trimmed = raw.trim();
|
|
1118
|
+
if (!/^\d+$/.test(trimmed))
|
|
1119
|
+
return null;
|
|
1120
|
+
const mb = Number.parseInt(trimmed, 10);
|
|
1121
|
+
return Number.isFinite(mb) && mb > 0 ? mb * 1024 * 1024 : null;
|
|
1122
|
+
}
|
|
1123
|
+
/** Strip exactly one pair of surrounding single/double quotes, if present. */
|
|
1124
|
+
function unquoteOptionValue(value) {
|
|
1125
|
+
if (value.length >= 2) {
|
|
1126
|
+
const first = value[0];
|
|
1127
|
+
const last = value[value.length - 1];
|
|
1128
|
+
if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
|
|
1129
|
+
return value.slice(1, -1);
|
|
1130
|
+
}
|
|
1131
|
+
}
|
|
1132
|
+
return value;
|
|
1133
|
+
}
|
|
1134
|
+
/** Last valid `--max-old-space-size` value in a token list, or null. */
|
|
1135
|
+
function declaredCeilingFromTokens(tokens) {
|
|
1136
|
+
let last = null;
|
|
1137
|
+
for (let i = 0; i < tokens.length; i += 1) {
|
|
1138
|
+
const token = tokens[i];
|
|
1139
|
+
const eq = token.indexOf("=");
|
|
1140
|
+
if (eq >= 0) {
|
|
1141
|
+
if (MAX_OLD_SPACE_FLAG.test(token.slice(0, eq))) {
|
|
1142
|
+
const bytes = wholeMbToBytes(unquoteOptionValue(token.slice(eq + 1)));
|
|
1143
|
+
if (bytes !== null)
|
|
1144
|
+
last = bytes;
|
|
1145
|
+
}
|
|
1146
|
+
}
|
|
1147
|
+
else if (MAX_OLD_SPACE_FLAG.test(token)) {
|
|
1148
|
+
const next = tokens[i + 1];
|
|
1149
|
+
if (next !== undefined) {
|
|
1150
|
+
const bytes = wholeMbToBytes(unquoteOptionValue(next));
|
|
1151
|
+
if (bytes !== null)
|
|
1152
|
+
last = bytes;
|
|
1153
|
+
}
|
|
1154
|
+
}
|
|
1155
|
+
}
|
|
1156
|
+
return last;
|
|
1157
|
+
}
|
|
1158
|
+
/**
|
|
1159
|
+
* Resolve the declared V8 old-space ceiling (bytes) the runner is actually
|
|
1160
|
+
* running under, mirroring how hq-desktop-app hands it to the npx-spawned
|
|
1161
|
+
* runner: a `--max-old-space-size` flag on `process.execArgv` wins over one in
|
|
1162
|
+
* `NODE_OPTIONS`, and within each source the LAST occurrence wins (V8's own
|
|
1163
|
+
* precedence). Both the `=value` and adjacent-arg forms are accepted, values may
|
|
1164
|
+
* carry one pair of surrounding quotes, and only a whole positive integer of MB
|
|
1165
|
+
* is honoured — anything else yields null, so the governor falls back to V8's
|
|
1166
|
+
* reported `heap_size_limit`. Never throws.
|
|
1167
|
+
*/
|
|
1168
|
+
export function resolveDeclaredHeapCeilingBytes(execArgv, nodeOptions) {
|
|
1169
|
+
try {
|
|
1170
|
+
const fromArgv = declaredCeilingFromTokens(execArgv ?? []);
|
|
1171
|
+
if (fromArgv !== null)
|
|
1172
|
+
return fromArgv;
|
|
1173
|
+
if (nodeOptions === undefined)
|
|
1174
|
+
return null;
|
|
1175
|
+
const tokens = nodeOptions.trim().split(/\s+/).filter(Boolean);
|
|
1176
|
+
return declaredCeilingFromTokens(tokens);
|
|
1177
|
+
}
|
|
1178
|
+
catch {
|
|
1179
|
+
return null;
|
|
1180
|
+
}
|
|
1181
|
+
}
|
|
793
1182
|
/**
|
|
794
1183
|
* Production readers over the real runtime. Kept here so the wiring site stays
|
|
795
1184
|
* a one-liner and the `v8` import lives in exactly one place.
|