rules/lifecycle.md
GitHubLifecycle: snapshot, diff, subtract, export/import, workers
Classes
RecordableHistogramcomes fromcreateHistogram()orimportHistogram(). It hasrecord,recordDelta,recordCorrected,addandsubtract.ELDHistogramcomes frommonitorEventLoopDelay(). It hasenable,disableand[Symbol.dispose](v24.2.0). Over a MessagePort it is cloned as a plainHistogram.Histogramis read-only.snapshot(),diff()andslidingWindow.snapshot()return it.
snapshot() / diff(older) / resetCount (v26.11.0 only)
snapshot()is an independent copy that includes the configuration,exceedsand the EWMA state. Laterrecord()/reset()calls do not change it. Its cost scales withlowest/highest/figures, not with the count.newer.diff(older)returns the values recorded in between (count,exceedsand the buckets are differences). It has no EWMA state and itsresetCountis0. Errors (verified):ERR_INVALID_ARG_VALUE: a differentlowest/highest/figures, or the wrong order (older.diff(newer)).ERR_INVALID_STATE: theresetCountdiffers because there was areset()orsubtract()in between.
resetCountis incremented byreset()and, on a recordable histogram, bysubtract().
Periodic reporting without resetting:
let prev = h.snapshot();
setInterval(() => {
const cur = h.snapshot();
const d = cur.resetCount === prev.resetCount ? cur.diff(prev) : cur;
emit(d.percentile(99));
prev = cur;
}, 10_000).unref();
add / subtract
add(other)(v17.4.0) accepts only aRecordableHistogram. Passing a snapshot throwsERR_INVALID_ARG_TYPE. Observed: a differentfiguressetting is accepted silently, so keep configurations identical yourself.subtract(other)(v26.8.0, v24.21.0) mutates the histogram. Negative bucket counts clamp to 0, andresetCountgoes up by one.
export() (v26.9.0; format v2 since v26.11.0) / importHistogram(bytes) (v26.9.0, v24.22.0)
export()returns aUint8Arraywith a CBOR map of integer keys: 0 version (2), 1 lowest, 2 highest, 3 figures, 4 count, 5 min, 6 max, 7 normalizing offset, 8 conversion ratio, 9 counts length, 10 sparse delta counts, and 11 EWMA state (omitted when disabled). The size scales with the number of distinct values.importHistogram()returns a RecordableHistogram with the buckets, configuration and EWMA restored. It accepts v1 (v26.9.0 output, strict keys) and v2 (unknown keys are ignored). Other versions are rejected.- The YAML lists
export()only for v26.9.0, whileimportHistogramalso lists v24.22.0. Feature-detecttypeof h.export === 'function'on v24.
Merging from workers
Histograms are cloneable over postMessage. Verified: a
RecordableHistogram arrives as a RecordableHistogram, so you can post it
directly. To send it across processes or store it, post h.export() and call
total.add(importHistogram(bytes)) on the receiving side. Use one shared
{ lowest, highest, figures } configuration on every worker.
bigint variants
countBigInt, minBigInt, maxBigInt, exceedsBigInt,
percentileBigInt(p) and percentilesBigInt exist (v17.4.0). record() and
recordCorrected() accept bigint. The new statistics methods take and return
numbers only. qrde().count is a bigint.