diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 69a4d6613b9b..b3adac992f46 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -1777,6 +1777,11 @@ console.log(snapshot.percentile(99)); * `data` {Uint8Array} A CBOR-encoded histogram previously produced by @@ -1787,6 +1792,9 @@ Reconstructs a histogram from a CBOR-encoded `Uint8Array`. The returned histogram is a full {RecordableHistogram} with all bucket data, configuration, and EWMA state restored. New values can be recorded into it. +Data in any format version produced by [`histogram.export()`][] can be +imported. See [histogram export format compatibility][] for details. + ```js const { createHistogram, importHistogram } = require('node:perf_hooks'); @@ -2180,6 +2188,10 @@ loop delay threshold. * Returns: {Uint8Array} @@ -2198,7 +2210,7 @@ The CBOR payload is a map with integer keys: | Key | Type | Field | | --- | ------- | --------------------------------------------- | -| 0 | uint | Format version (currently 1) | +| 0 | uint | Format version (currently 2) | | 1 | uint | Lowest discernible value | | 2 | uint | Highest trackable value | | 3 | uint | Significant figures | @@ -2213,6 +2225,23 @@ The CBOR payload is a map with integer keys: Any standard CBOR decoder can parse the output. +#### Histogram export format compatibility + +[`perf_hooks.importHistogram()`][] accepts every format version that +`histogram.export()` has produced: + +* Version 1 was produced by Node.js v26.9.0. Data with a version 1 key, or + without a version key, is imported with the original semantics: keys + that are not listed above are rejected. +* Version 2 has the same layout as version 1. Keys that are not recognized + are ignored, so later versions of Node.js can add fields to version 2 + data without changing the version, and the data remains importable. + +Data with any other version is rejected. + +When the total count, min, or max value is absent, it is derived from the +bucket counts. A total count that is present must match the bucket counts. + ### `histogram.ewmaMean`