perf_hooks: add binary export/import to Histogram

doc/api/perf_hooks.md

@@ -1639,6 +1639,34 @@ added:
 
 Returns a {RecordableHistogram}.
 
+## `perf_hooks.importHistogram(data)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `data` {Uint8Array} A CBOR-encoded histogram previously produced by
+  [`histogram.export()`][].
+* Returns: {RecordableHistogram}
+
+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.
+
+```js
+const { createHistogram, importHistogram } = require('node:perf_hooks');
+
+const h = createHistogram();
+for (let i = 1; i <= 1000; i++) h.record(i);
+
+// Serialize and reconstruct
+const data = h.export();
+const h2 = importHistogram(data);
+
+console.log(h2.count);          // 1000
+console.log(h2.percentile(99)); // Same as h.percentile(99)
+```
+
 ## `perf_hooks.eventLoopUtilization([utilization1[, utilization2]])`
 
 <!-- YAML
@@ -1854,6 +1882,37 @@ invoked.
 added: v11.10.0
 -->
 
+### `histogram.burnRate(sloTarget)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sloTarget` {number} The SLO target as a fraction between 0 and 1
+  (exclusive). For example, `0.999` for a 99.9% SLO.
+* Returns: {number}
+
+Returns the SLO burn rate: `ewmaErrorRate / (1 - sloTarget)`. A burn rate
+of 1 means the error budget will be exactly exhausted over the SLO window.
+A burn rate greater than 1 means it is being consumed faster than allowed.
+Requires the histogram to have been created with both `halfLife` and
+`threshold` options.
+
+```js
+const { createHistogram } = require('node:perf_hooks');
+
+// Track latency with a 200ms SLO threshold, half-life of 100 samples
+const h = createHistogram({ halfLife: 100, threshold: 200_000_000 });
+
+// ... record latency values ...
+
+// Check burn rate against a 99.9% SLO
+const rate = h.burnRate(0.999);
+if (rate > 1) {
+  console.log(`SLO burn rate: ${rate.toFixed(2)}x — error budget depleting`);
+}
+```
+
 ### `histogram.count`
 
 <!-- YAML
@@ -1971,6 +2030,43 @@ added:
 The number of times the event loop delay exceeded the maximum 1 hour event
 loop delay threshold.
 
+### `histogram.export()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Uint8Array}
+
+Serializes the histogram to a [CBOR][]-encoded (RFC 8949) `Uint8Array`
+suitable for transmission or persistent storage. The encoding uses a
+delta-encoded sparse representation of the bucket counts, so the output size
+scales with the number of distinct recorded values rather than the total
+bucket count.
+
+The output includes all histogram configuration, bucket data, and EWMA
+state (when enabled). It can be reconstructed into a new histogram using
+[`perf_hooks.importHistogram()`][].
+
+The CBOR payload is a map with integer keys:
+
+| Key | Type    | Field                                         |
+| --- | ------- | --------------------------------------------- |
+| 0   | uint    | Format version (currently 1)                  |
+| 1   | uint    | Lowest discernible value                      |
+| 2   | uint    | Highest trackable value                       |
+| 3   | uint    | Significant figures                           |
+| 4   | uint    | Total count                                   |
+| 5   | uint    | Min value                                     |
+| 6   | uint    | Max value                                     |
+| 7   | uint    | Normalizing index offset                      |
+| 8   | float64 | Conversion ratio                              |
+| 9   | uint    | Counts array length                           |
+| 10  | array   | Delta-encoded sparse counts `[delta, c, ...]` |
+| 11  | map     | EWMA state (omitted when disabled)            |
+
+Any standard CBOR decoder can parse the output.
+
 ### `histogram.ewmaMean`
 
 <!-- YAML
@@ -2008,37 +2104,6 @@ The EWMA-smoothed probability of a recorded value exceeding the configured
 and `threshold` options. Returns `0` when not enabled or no values have been
 recorded.
 
-### `histogram.burnRate(sloTarget)`
-
-<!-- YAML
-added: REPLACEME
--->
-
-* `sloTarget` {number} The SLO target as a fraction between 0 and 1
-  (exclusive). For example, `0.999` for a 99.9% SLO.
-* Returns: {number}
-
-Returns the SLO burn rate: `ewmaErrorRate / (1 - sloTarget)`. A burn rate
-of 1 means the error budget will be exactly exhausted over the SLO window.
-A burn rate greater than 1 means it is being consumed faster than allowed.
-Requires the histogram to have been created with both `halfLife` and
-`threshold` options.
-
-```js
-const { createHistogram } = require('node:perf_hooks');
-
-// Track latency with a 200ms SLO threshold, half-life of 100 samples
-const h = createHistogram({ halfLife: 100, threshold: 200_000_000 });
-
-// ... record latency values ...
-
-// Check burn rate against a 99.9% SLO
-const rate = h.burnRate(0.999);
-if (rate > 1) {
-  console.log(`SLO burn rate: ${rate.toFixed(2)}x — error budget depleting`);
-}
-```
-
 ### `histogram.ksTest(other)`
 
 <!-- YAML
@@ -2846,6 +2911,7 @@ dns.promises.resolve('localhost');
 ```
 
 [Async Hooks]: async_hooks.md
+[CBOR]: https://www.rfc-editor.org/rfc/rfc8949
 [Cliff's delta]: https://en.wikipedia.org/wiki/Effect_size#Cliff's_delta
 [Cohen's d]: https://en.wikipedia.org/wiki/Effect_size#Cohen's_d
 [Fetch Response Body Info]: https://fetch.spec.whatwg.org/#response-body-info
@@ -2860,7 +2926,9 @@ dns.promises.resolve('localhost');
 [Worker threads]: worker_threads.md#worker-threads
 [`'exit'`]: process.md#event-exit
 [`child_process.spawnSync()`]: child_process.md#child_processspawnsynccommand-args-options
+[`histogram.export()`]: #histogramexport
 [`perf_hooks.eventLoopUtilization()`]: #perf_hookseventlooputilizationutilization1-utilization2
+[`perf_hooks.importHistogram()`]: #perf_hooksimporthistogramdata
 [`perf_hooks.monitorEventLoopDelay()`]: #perf_hooksmonitoreventloopdelayoptions
 [`perf_hooks.timerify()`]: #perf_hookstimerifyfn-options
 [`process.hrtime()`]: process.md#processhrtimetime

lib/internal/histogram.js

@@ -38,6 +38,10 @@ const {
   validateObject,
 } = require('internal/validators');
 
+const {
+  isUint8Array,
+} = require('internal/util/types');
+
 const kDestroy = Symbol('kDestroy');
 const kHandle = Symbol('kHandle');
 const kRecordable = Symbol('kRecordable');
@@ -213,6 +217,18 @@ class Histogram {
     return this[kHandle]?.exceedsBigInt();
   }
 
+  /**
+   * Serializes the histogram to a CBOR-encoded Uint8Array suitable for
+   * transmission or storage. The data can be reconstructed into a new
+   * histogram using `importHistogram()`.
+   * @returns {Uint8Array}
+   */
+  export() {
+    if (!isHistogram(this))
+      throw new ERR_INVALID_THIS('Histogram');
+    return this[kHandle]?.export();
+  }
+
   /**
    * Returns the exponentially weighted moving average of recorded values.
    * Only active when the histogram was created with a `halfLife` option.
@@ -756,6 +772,18 @@ function createHistogram(options = kEmptyObject) {
     new _Histogram(lowest, highest, figures, halfLife, threshold));
 }
 
+/**
+ * Reconstructs a histogram from a CBOR-encoded Uint8Array previously
+ * produced by `histogram.export()`.
+ * @param {Uint8Array} data
+ * @returns {RecordableHistogram}
+ */
+function importHistogram(data) {
+  if (!isUint8Array(data))
+    throw new ERR_INVALID_ARG_TYPE('data', 'Uint8Array', data);
+  return createRecordableHistogram(_Histogram.import(data));
+}
+
 module.exports = {
   Histogram,
   RecordableHistogram,
@@ -766,4 +794,5 @@ module.exports = {
   kHandle,
   kSkipThrow,
   createHistogram,
+  importHistogram,
 };

lib/perf_hooks.js

@@ -25,6 +25,7 @@ const {
 
 const {
   createHistogram,
+  importHistogram,
 } = require('internal/histogram');
 
 const monitorEventLoopDelay = require('internal/perf/event_loop_delay');
@@ -43,6 +44,7 @@ module.exports = {
   eventLoopUtilization,
   timerify,
   createHistogram,
+  importHistogram,
   performance,
 };