From 129015887315e15aab88075c6f1e913ea3b89b0f Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Thu, 20 Aug 2026 07:22:45 -0700
Subject: [PATCH 1/2] perf_hooks: add CBOR export/import for histogram exchange

Provide a binary export/import mechanism for histograms.

Since there is no standard interchange format for histograms,
using CBOR is meant to make the format as platform/runtime
agnostic as possible while producing a compact/efficient
result. No new dependency is introduced, we just encode
the CBOR directly.

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode/Opus
---
 doc/api/perf_hooks.md                         |  68 +++
 lib/internal/histogram.js                     |  29 +
 lib/perf_hooks.js                             |   2 +
 src/histogram.cc                              | 537 +++++++++++++++++-
 src/histogram.h                               |  15 +-
 .../test-perf-hooks-histogram-stats.js        | 138 ++++-
 6 files changed, 769 insertions(+), 20 deletions(-)

diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md
index 1e5f059a3835..72d2b9c3b7f0 100644
--- a/doc/api/perf_hooks.md
+++ b/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
@@ -1971,6 +1999,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
@@ -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
diff --git a/lib/internal/histogram.js b/lib/internal/histogram.js
index 952f6058019f..99c2c1d87dac 100644
--- a/lib/internal/histogram.js
+++ b/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,
 };
diff --git a/lib/perf_hooks.js b/lib/perf_hooks.js
index 18e979630e0e..cc158e5c7625 100644
--- a/lib/perf_hooks.js
+++ b/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,
 };
 
diff --git a/src/histogram.cc b/src/histogram.cc
index 0997d3cb481c..1a852dcf3f88 100644
--- a/src/histogram.cc
+++ b/src/histogram.cc
@@ -46,14 +46,8 @@ void StopHandleHistogram(Local<Value> receiver) {
   histogram->OnStop();
 }
 
-Histogram::Histogram(const Options& options) {
-  hdr_histogram* histogram;
-  CHECK_EQ(0, hdr_init(options.lowest,
-                       options.highest,
-                       options.figures,
-                       &histogram));
-  histogram_.reset(histogram);
-
+Histogram::Histogram(HistogramPointer histogram, const Options& options)
+    : histogram_(std::move(histogram)) {
   // alpha = 1 - 2^(-1/halfLife). With halfLife <= 0, EWMA is disabled.
   if (options.half_life > 0) {
     ewma_alpha_ = 1.0 - std::exp(-std::log(2.0) / options.half_life);
@@ -61,6 +55,15 @@ Histogram::Histogram(const Options& options) {
   threshold_ = options.threshold;
 }
 
+std::shared_ptr<Histogram> Histogram::Create(const Options& options) {
+  hdr_histogram* histogram;
+  if (hdr_init(options.lowest, options.highest, options.figures, &histogram) !=
+      0) {
+    return {};
+  }
+  return std::make_shared<Histogram>(HistogramPointer(histogram), options);
+}
+
 void Histogram::MemoryInfo(MemoryTracker* tracker) const {
   tracker->TrackFieldWithSize("histogram", GetMemorySize());
 }
@@ -333,6 +336,150 @@ static double BinomialCdf(int64_t k, int64_t n, double p) {
   return RegularizedIncompleteBeta(
       static_cast<double>(n - k), static_cast<double>(k + 1), 1.0 - p);
 }
+
+// -----------------------------------------------------------------------
+// Minimal CBOR encoder/decoder (RFC 8949) -- just enough types for
+// histogram export/import: unsigned int, float64, array, and map.
+// -----------------------------------------------------------------------
+
+// CBOR major types (upper 3 bits of the initial byte).
+constexpr uint8_t kCborUint = 0 << 5;   // Major 0: unsigned integer
+constexpr uint8_t kCborArray = 4 << 5;  // Major 4: array
+constexpr uint8_t kCborMap = 5 << 5;    // Major 5: map
+constexpr uint8_t kCborFloat64 = 0xfb;  // Major 7, additional 27
+
+static void CborWriteUint(std::vector<uint8_t>& out,
+                          uint8_t major,
+                          uint64_t val) {
+  if (val <= 23) {
+    out.push_back(major | static_cast<uint8_t>(val));
+  } else if (val <= 0xff) {
+    out.push_back(major | 24);
+    out.push_back(static_cast<uint8_t>(val));
+  } else if (val <= 0xffff) {
+    out.push_back(major | 25);
+    out.push_back(static_cast<uint8_t>(val >> 8));
+    out.push_back(static_cast<uint8_t>(val));
+  } else if (val <= 0xffffffff) {
+    out.push_back(major | 26);
+    out.push_back(static_cast<uint8_t>(val >> 24));
+    out.push_back(static_cast<uint8_t>(val >> 16));
+    out.push_back(static_cast<uint8_t>(val >> 8));
+    out.push_back(static_cast<uint8_t>(val));
+  } else {
+    out.push_back(major | 27);
+    out.push_back(static_cast<uint8_t>(val >> 56));
+    out.push_back(static_cast<uint8_t>(val >> 48));
+    out.push_back(static_cast<uint8_t>(val >> 40));
+    out.push_back(static_cast<uint8_t>(val >> 32));
+    out.push_back(static_cast<uint8_t>(val >> 24));
+    out.push_back(static_cast<uint8_t>(val >> 16));
+    out.push_back(static_cast<uint8_t>(val >> 8));
+    out.push_back(static_cast<uint8_t>(val));
+  }
+}
+
+static void CborWriteFloat64(std::vector<uint8_t>& out, double val) {
+  out.push_back(kCborFloat64);
+  uint64_t bits;
+  memcpy(&bits, &val, sizeof(bits));
+  // Network byte order (big-endian).
+  out.push_back(static_cast<uint8_t>(bits >> 56));
+  out.push_back(static_cast<uint8_t>(bits >> 48));
+  out.push_back(static_cast<uint8_t>(bits >> 40));
+  out.push_back(static_cast<uint8_t>(bits >> 32));
+  out.push_back(static_cast<uint8_t>(bits >> 24));
+  out.push_back(static_cast<uint8_t>(bits >> 16));
+  out.push_back(static_cast<uint8_t>(bits >> 8));
+  out.push_back(static_cast<uint8_t>(bits));
+}
+
+static bool CborReadUint(const uint8_t*& p, const uint8_t* end, uint64_t* val) {
+  if (p >= end) return false;
+  uint8_t info = *p++ & 0x1f;
+  if (info <= 23) {
+    *val = info;
+  } else if (info == 24) {
+    if (p + 1 > end) return false;
+    *val = p[0];
+    p += 1;
+  } else if (info == 25) {
+    if (p + 2 > end) return false;
+    *val = (static_cast<uint64_t>(p[0]) << 8) | p[1];
+    p += 2;
+  } else if (info == 26) {
+    if (p + 4 > end) return false;
+    *val = (static_cast<uint64_t>(p[0]) << 24) |
+           (static_cast<uint64_t>(p[1]) << 16) |
+           (static_cast<uint64_t>(p[2]) << 8) | p[3];
+    p += 4;
+  } else if (info == 27) {
+    if (p + 8 > end) return false;
+    *val = (static_cast<uint64_t>(p[0]) << 56) |
+           (static_cast<uint64_t>(p[1]) << 48) |
+           (static_cast<uint64_t>(p[2]) << 40) |
+           (static_cast<uint64_t>(p[3]) << 32) |
+           (static_cast<uint64_t>(p[4]) << 24) |
+           (static_cast<uint64_t>(p[5]) << 16) |
+           (static_cast<uint64_t>(p[6]) << 8) | p[7];
+    p += 8;
+  } else {
+    return false;  // Indefinite length or reserved -- not supported.
+  }
+  return true;
+}
+
+static bool CborReadFloat64(const uint8_t*& p,
+                            const uint8_t* end,
+                            double* val) {
+  if (p >= end || *p != kCborFloat64) return false;
+  p++;
+  if (p + 8 > end) return false;
+  uint64_t bits = (static_cast<uint64_t>(p[0]) << 56) |
+                  (static_cast<uint64_t>(p[1]) << 48) |
+                  (static_cast<uint64_t>(p[2]) << 40) |
+                  (static_cast<uint64_t>(p[3]) << 32) |
+                  (static_cast<uint64_t>(p[4]) << 24) |
+                  (static_cast<uint64_t>(p[5]) << 16) |
+                  (static_cast<uint64_t>(p[6]) << 8) | p[7];
+  p += 8;
+  memcpy(val, &bits, sizeof(*val));
+  return true;
+}
+
+// Read a value that may be either a uint or float64.
+static bool CborReadNumber(const uint8_t*& p, const uint8_t* end, double* val) {
+  if (p >= end) return false;
+  if (*p == kCborFloat64) return CborReadFloat64(p, end, val);
+  uint64_t u;
+  if (!CborReadUint(p, end, &u)) return false;
+  *val = static_cast<double>(u);
+  return true;
+}
+
+// Histogram export format version.
+constexpr uint64_t kExportVersion = 1;
+
+// Integer keys for the top-level CBOR map.
+constexpr uint64_t kKeyVersion = 0;
+constexpr uint64_t kKeyLowest = 1;
+constexpr uint64_t kKeyHighest = 2;
+constexpr uint64_t kKeyFigures = 3;
+constexpr uint64_t kKeyTotalCount = 4;
+constexpr uint64_t kKeyMin = 5;
+constexpr uint64_t kKeyMax = 6;
+constexpr uint64_t kKeyNormOffset = 7;
+constexpr uint64_t kKeyConvRatio = 8;
+constexpr uint64_t kKeyCountsLen = 9;
+constexpr uint64_t kKeyCounts = 10;
+constexpr uint64_t kKeyEwma = 11;
+
+// Integer keys for the EWMA sub-map.
+constexpr uint64_t kEwmaAlpha = 0;
+constexpr uint64_t kEwmaMean = 1;
+constexpr uint64_t kEwmaVariance = 2;
+constexpr uint64_t kEwmaErrorRate = 3;
+constexpr uint64_t kEwmaThreshold = 4;
 }  // namespace
 
 Histogram::WelchTestResult Histogram::WelchTest(const Histogram& other,
@@ -590,8 +737,319 @@ Histogram::PercentileCIResult Histogram::PercentileCI(double percentile,
   return {value, lower_val, upper_val};
 }
 
+// Serialize the histogram to a CBOR (RFC 8949) byte sequence. There is no
+// standard for serializing histograms, so this format is specific to this
+// implementation. But, it has been designed to be compact, extensible, and
+// portable across languages and platforms. Should be easily parseable in
+// other languages with or without a CBOR library.
+//
+// The delta-encoded sparse counts is a space-saving optimization in the
+// common case.
+//
+// Layout: a CBOR map with integer keys:
+//   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 as flat [delta, count, ...]
+//                 (first delta is the absolute index)
+//   11 -> map     EWMA state (omitted when alpha = 0):
+//        0 -> float64 alpha
+//        1 -> float64 mean
+//        2 -> float64 variance
+//        3 -> float64 error rate
+//        4 -> uint    threshold
+std::vector<uint8_t> Histogram::Export() const {
+  RwLock::ScopedReadLock lock(mutex_);
+
+  // Count non-zero buckets for the sparse encoding.
+  int32_t non_zero = 0;
+  for (int32_t i = 0; i < histogram_->counts_len; i++) {
+    if (histogram_->counts[i] != 0) non_zero++;
+  }
+
+  bool has_ewma = ewma_alpha_ > 0;
+  uint64_t map_size = has_ewma ? 12 : 11;
+
+  std::vector<uint8_t> out;
+  out.reserve(64 + non_zero * 10);
+
+  // Top-level map.
+  CborWriteUint(out, kCborMap, map_size);
+
+  // 0: version
+  CborWriteUint(out, kCborUint, kKeyVersion);
+  CborWriteUint(out, kCborUint, kExportVersion);
+  // 1: lowest
+  CborWriteUint(out, kCborUint, kKeyLowest);
+  CborWriteUint(out,
+                kCborUint,
+                static_cast<uint64_t>(histogram_->lowest_discernible_value));
+  // 2: highest
+  CborWriteUint(out, kCborUint, kKeyHighest);
+  CborWriteUint(out,
+                kCborUint,
+                static_cast<uint64_t>(histogram_->highest_trackable_value));
+  // 3: figures
+  CborWriteUint(out, kCborUint, kKeyFigures);
+  CborWriteUint(
+      out, kCborUint, static_cast<uint64_t>(histogram_->significant_figures));
+  // 4: total_count
+  CborWriteUint(out, kCborUint, kKeyTotalCount);
+  CborWriteUint(out, kCborUint, static_cast<uint64_t>(histogram_->total_count));
+  // 5: min
+  CborWriteUint(out, kCborUint, kKeyMin);
+  CborWriteUint(out, kCborUint, static_cast<uint64_t>(histogram_->min_value));
+  // 6: max
+  CborWriteUint(out, kCborUint, kKeyMax);
+  CborWriteUint(out, kCborUint, static_cast<uint64_t>(histogram_->max_value));
+  // 7: normalizing_index_offset
+  CborWriteUint(out, kCborUint, kKeyNormOffset);
+  CborWriteUint(out,
+                kCborUint,
+                static_cast<uint64_t>(histogram_->normalizing_index_offset));
+  // 8: conversion_ratio
+  CborWriteUint(out, kCborUint, kKeyConvRatio);
+  CborWriteFloat64(out, histogram_->conversion_ratio);
+  // 9: counts_len
+  CborWriteUint(out, kCborUint, kKeyCountsLen);
+  CborWriteUint(out, kCborUint, static_cast<uint64_t>(histogram_->counts_len));
+  // 10: sparse counts -- array of [delta, count, ...] pairs.
+  // Indices are delta-encoded: the first value is the absolute index,
+  // each subsequent value is the difference from the previous index.
+  CborWriteUint(out, kCborUint, kKeyCounts);
+  CborWriteUint(out, kCborArray, static_cast<uint64_t>(non_zero) * 2);
+  int32_t prev_idx = 0;
+  for (int32_t i = 0; i < histogram_->counts_len; i++) {
+    if (histogram_->counts[i] != 0) {
+      CborWriteUint(out, kCborUint, static_cast<uint64_t>(i - prev_idx));
+      CborWriteUint(
+          out, kCborUint, static_cast<uint64_t>(histogram_->counts[i]));
+      prev_idx = i;
+    }
+  }
+
+  // 11: EWMA state (optional)
+  if (has_ewma) {
+    CborWriteUint(out, kCborUint, kKeyEwma);
+    CborWriteUint(out, kCborMap, 5);
+    CborWriteUint(out, kCborUint, kEwmaAlpha);
+    CborWriteFloat64(out, ewma_alpha_);
+    CborWriteUint(out, kCborUint, kEwmaMean);
+    CborWriteFloat64(out, ewma_mean_);
+    CborWriteUint(out, kCborUint, kEwmaVariance);
+    CborWriteFloat64(out, ewma_variance_);
+    CborWriteUint(out, kCborUint, kEwmaErrorRate);
+    CborWriteFloat64(out, ewma_error_rate_);
+    CborWriteUint(out, kCborUint, kEwmaThreshold);
+    CborWriteUint(out, kCborUint, static_cast<uint64_t>(threshold_));
+  }
+
+  return out;
+}
+
+std::shared_ptr<Histogram> Histogram::Import(const uint8_t* data, size_t len) {
+  const uint8_t* p = data;
+  const uint8_t* end = data + len;
+
+  // Read top-level map header.
+  if (p >= end || (*p >> 5) != 5) return nullptr;  // Must be a map.
+  uint64_t map_size;
+  if (!CborReadUint(p, end, &map_size)) return nullptr;
+
+  int64_t lowest = 1;
+  int64_t highest = std::numeric_limits<int64_t>::max();
+  int figures = 3;
+  int64_t total_count = 0;
+  int64_t min_value = std::numeric_limits<int64_t>::max();
+  int64_t max_value = 0;
+  int32_t norm_offset = 0;
+  double conv_ratio = 1.0;
+  int32_t counts_len = 0;
+  uint64_t version = 0;
+
+  // Sparse counts storage.
+  std::vector<std::pair<int32_t, int64_t>> sparse_counts;
+
+  // EWMA state.
+  double ewma_alpha = 0;
+  double ewma_mean = 0;
+  double ewma_variance = 0;
+  double ewma_error_rate = 0;
+  int64_t threshold = 0;
+
+  for (uint64_t i = 0; i < map_size; i++) {
+    // Read key (unsigned int).
+    uint64_t key;
+    if (!CborReadUint(p, end, &key)) return nullptr;
+
+    switch (key) {
+      case kKeyVersion:
+        if (!CborReadUint(p, end, &version)) return nullptr;
+        if (version != kExportVersion) return nullptr;
+        break;
+      case kKeyLowest: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        lowest = static_cast<int64_t>(v);
+        break;
+      }
+      case kKeyHighest: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        highest = static_cast<int64_t>(v);
+        break;
+      }
+      case kKeyFigures: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        figures = static_cast<int>(v);
+        break;
+      }
+      case kKeyTotalCount: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        total_count = static_cast<int64_t>(v);
+        break;
+      }
+      case kKeyMin: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        min_value = static_cast<int64_t>(v);
+        break;
+      }
+      case kKeyMax: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        max_value = static_cast<int64_t>(v);
+        break;
+      }
+      case kKeyNormOffset: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        norm_offset = static_cast<int32_t>(v);
+        break;
+      }
+      case kKeyConvRatio:
+        if (!CborReadNumber(p, end, &conv_ratio)) return nullptr;
+        break;
+      case kKeyCountsLen: {
+        uint64_t v;
+        if (!CborReadUint(p, end, &v)) return nullptr;
+        counts_len = static_cast<int32_t>(v);
+        break;
+      }
+      case kKeyCounts: {
+        // Array of flat [delta, count, ...] pairs. Indices are
+        // delta-encoded: accumulate to recover absolute indices.
+        if (p >= end || (*p >> 5) != 4) return nullptr;
+        uint64_t arr_len;
+        if (!CborReadUint(p, end, &arr_len)) return nullptr;
+        if (arr_len % 2 != 0) return nullptr;
+        // Each element needs at least 1 byte of CBOR encoding, so
+        // arr_len can't exceed the remaining buffer. Without this
+        // check, a crafted buffer claiming arr_len=2^60 would cause
+        // reserve() to OOM-crash before the loop catches the error.
+        if (arr_len > static_cast<uint64_t>(end - p)) return nullptr;
+        sparse_counts.reserve(static_cast<size_t>(arr_len / 2));
+        int32_t acc_idx = 0;
+        for (uint64_t j = 0; j < arr_len; j += 2) {
+          uint64_t delta, cnt;
+          if (!CborReadUint(p, end, &delta)) return nullptr;
+          if (!CborReadUint(p, end, &cnt)) return nullptr;
+          acc_idx += static_cast<int32_t>(delta);
+          sparse_counts.emplace_back(acc_idx, static_cast<int64_t>(cnt));
+        }
+        break;
+      }
+      case kKeyEwma: {
+        // Sub-map for EWMA state.
+        if (p >= end || (*p >> 5) != 5) return nullptr;
+        uint64_t sub_size;
+        if (!CborReadUint(p, end, &sub_size)) return nullptr;
+        for (uint64_t j = 0; j < sub_size; j++) {
+          uint64_t sub_key;
+          if (!CborReadUint(p, end, &sub_key)) return nullptr;
+          switch (sub_key) {
+            case kEwmaAlpha:
+              if (!CborReadNumber(p, end, &ewma_alpha)) return nullptr;
+              break;
+            case kEwmaMean:
+              if (!CborReadNumber(p, end, &ewma_mean)) return nullptr;
+              break;
+            case kEwmaVariance:
+              if (!CborReadNumber(p, end, &ewma_variance)) return nullptr;
+              break;
+            case kEwmaErrorRate:
+              if (!CborReadNumber(p, end, &ewma_error_rate)) return nullptr;
+              break;
+            case kEwmaThreshold: {
+              uint64_t v;
+              if (!CborReadUint(p, end, &v)) return nullptr;
+              threshold = static_cast<int64_t>(v);
+              break;
+            }
+            default:
+              return nullptr;  // Unknown EWMA key.
+          }
+        }
+        break;
+      }
+      default:
+        return nullptr;  // Unknown key.
+    }
+  }
+
+  // Reconstruct the histogram.
+  Options opts;
+  opts.lowest = lowest;
+  opts.highest = highest;
+  opts.figures = figures;
+  // Compute half_life from alpha: alpha = 1 - 2^(-1/halfLife)
+  // => halfLife = -1 / log2(1 - alpha)
+  if (ewma_alpha > 0 && ewma_alpha < 1) {
+    opts.half_life = -1.0 / std::log2(1.0 - ewma_alpha);
+  }
+  opts.threshold = threshold;
+
+  auto histogram = Histogram::Create(opts);
+  if (!histogram) return nullptr;
+
+  // Validate counts_len matches what the options produce.
+  if (histogram->histogram_->counts_len != counts_len) return nullptr;
+
+  // Restore counts directly.
+  for (const auto& [idx, cnt] : sparse_counts) {
+    if (idx < 0 || idx >= counts_len) return nullptr;
+    histogram->histogram_->counts[idx] = cnt;
+  }
+  histogram->histogram_->total_count = total_count;
+  histogram->histogram_->min_value = min_value;
+  histogram->histogram_->max_value = max_value;
+  histogram->histogram_->normalizing_index_offset = norm_offset;
+  histogram->histogram_->conversion_ratio = conv_ratio;
+
+  // Restore EWMA state.
+  if (ewma_alpha > 0) {
+    histogram->ewma_mean_ = ewma_mean;
+    histogram->ewma_variance_ = ewma_variance;
+    histogram->ewma_error_rate_ = ewma_error_rate;
+    histogram->ewma_initialized_ = true;
+  }
+
+  return histogram;
+}
+
 HistogramImpl::HistogramImpl(const Histogram::Options& options)
-    : histogram_(new Histogram(options)) {}
+    : histogram_(Histogram::Create(options)) {
+  CHECK(histogram_);
+}
 
 HistogramImpl::HistogramImpl(std::shared_ptr<Histogram> histogram)
     : histogram_(std::move(histogram)) {}
@@ -690,6 +1148,7 @@ void HistogramImpl::AddMethods(Isolate* isolate, Local<FunctionTemplate> tmpl) {
                             "ewmaErrorRate",
                             GetEwmaErrorRate,
                             &fast_get_ewma_error_rate_);
+  SetProtoMethodNoSideEffect(isolate, tmpl, "export", DoExport);
   SetFastMethod(isolate, instance, "reset", DoReset, &fast_reset_);
 }
 
@@ -736,6 +1195,7 @@ void HistogramImpl::RegisterExternalReferences(
   registry->Register(GetEwmaMean);
   registry->Register(GetEwmaStddev);
   registry->Register(GetEwmaErrorRate);
+  registry->Register(DoExport);
   registry->Register(fast_get_ewma_mean_);
   registry->Register(fast_get_ewma_stddev_);
   registry->Register(fast_get_ewma_error_rate_);
@@ -922,10 +1382,12 @@ void HistogramBase::New(const FunctionCallbackInfo<Value>& args) {
   if (args.Length() > 4 && args[4]->IsNumber()) {
     threshold = static_cast<int64_t>(args[4].As<Number>()->Value());
   }
-  new HistogramBase(
-      env,
-      args.This(),
+  auto histogram = Histogram::Create(
       Histogram::Options{lowest, highest, figures, half_life, threshold});
+  if (!histogram) {
+    return THROW_ERR_INVALID_ARG_VALUE(env, "Invalid histogram options");
+  }
+  new HistogramBase(env, args.This(), std::move(histogram));
 }
 
 Local<FunctionTemplate> HistogramBase::GetConstructorTemplate(
@@ -960,16 +1422,17 @@ void HistogramBase::RegisterExternalReferences(
   registry->Register(RecordCorrected);
   registry->Register(fast_record_);
   registry->Register(fast_record_delta_);
+  registry->Register(HistogramImpl::DoImport);
   HistogramImpl::RegisterExternalReferences(registry);
 }
 
 void HistogramBase::Initialize(IsolateData* isolate_data,
                                Local<ObjectTemplate> target) {
-  SetConstructorFunction(isolate_data->isolate(),
-                         target,
-                         "Histogram",
-                         GetConstructorTemplate(isolate_data),
-                         SetConstructorFunctionFlag::NONE);
+  Isolate* isolate = isolate_data->isolate();
+  Local<FunctionTemplate> tmpl = GetConstructorTemplate(isolate_data);
+  SetMethodNoSideEffect(isolate, tmpl, "import", HistogramImpl::DoImport);
+  SetConstructorFunction(
+      isolate, target, "Histogram", tmpl, SetConstructorFunctionFlag::NONE);
 }
 
 BaseObjectPtr<BaseObject> HistogramBase::HistogramTransferData::Deserialize(
@@ -1528,6 +1991,46 @@ double HistogramImpl::FastGetEwmaErrorRate(Local<Value> receiver) {
   return (*histogram)->EwmaErrorRate();
 }
 
+void HistogramImpl::DoExport(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  HistogramImpl* histogram = HistogramImpl::FromJSObject(args.This());
+  std::vector<uint8_t> data = (*histogram)->Export();
+
+  auto store = v8::ArrayBuffer::NewBackingStore(env->isolate(), data.size());
+  memcpy(store->Data(), data.data(), data.size());
+  auto buf = v8::ArrayBuffer::New(env->isolate(), std::move(store));
+  auto arr = v8::Uint8Array::New(buf, 0, data.size());
+  args.GetReturnValue().Set(arr);
+}
+
+void HistogramImpl::DoImport(const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  if (!args[0]->IsUint8Array()) {
+    THROW_ERR_INVALID_ARG_TYPE(env, "data must be a Uint8Array");
+    return;
+  }
+  Local<v8::Uint8Array> input = args[0].As<v8::Uint8Array>();
+  auto backing = input->Buffer()->GetBackingStore();
+  const uint8_t* data =
+      static_cast<const uint8_t*>(backing->Data()) + input->ByteOffset();
+  size_t len = input->ByteLength();
+
+  auto histogram = Histogram::Import(data, len);
+  if (!histogram) {
+    THROW_ERR_INVALID_ARG_VALUE(env, "Invalid histogram export data");
+    return;
+  }
+
+  // Create a new HistogramBase wrapping the imported histogram.
+  Local<FunctionTemplate> tmpl =
+      HistogramBase::GetConstructorTemplate(env->isolate_data());
+  Local<Object> obj;
+  if (!tmpl->InstanceTemplate()->NewInstance(env->context()).ToLocal(&obj))
+    return;
+  new HistogramBase(env, obj, std::move(histogram));
+  args.GetReturnValue().Set(obj);
+}
+
 void HistogramImpl::GetPercentilesAt(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   HistogramImpl* histogram = HistogramImpl::FromJSObject(args.This());
diff --git a/src/histogram.h b/src/histogram.h
index 31a2e9833d3e..05d6003c25cc 100644
--- a/src/histogram.h
+++ b/src/histogram.h
@@ -12,6 +12,7 @@
 #include "v8.h"
 
 #include <limits>
+#include <vector>
 
 namespace node {
 
@@ -36,7 +37,12 @@ class Histogram : public MemoryRetainer {
                             // exceeding this threshold.
   };
 
-  explicit Histogram(const Options& options);
+  using HistogramPointer = DeleteFnPtr<hdr_histogram, hdr_close>;
+
+  // Factory method that returns nullptr on hdr_init failure.
+  static std::shared_ptr<Histogram> Create(const Options& options);
+
+  Histogram(HistogramPointer histogram, const Options& options);
   virtual ~Histogram() = default;
 
   inline bool Record(int64_t value);
@@ -103,6 +109,10 @@ class Histogram : public MemoryRetainer {
   PercentileCIResult PercentileCI(double percentile,
                                   double confidence = 0.95) const;
 
+  // CBOR-encoded export/import for histogram exchange.
+  std::vector<uint8_t> Export() const;
+  static std::shared_ptr<Histogram> Import(const uint8_t* data, size_t len);
+
   inline bool RecordCorrected(int64_t value, int64_t expected_interval);
 
   template <typename Iterator>
@@ -120,7 +130,6 @@ class Histogram : public MemoryRetainer {
  private:
   inline void UpdateEwma(double value);
 
-  using HistogramPointer = DeleteFnPtr<hdr_histogram, hdr_close>;
   HistogramPointer histogram_;
   uint64_t prev_ = 0;
   size_t exceeds_ = 0;
@@ -189,6 +198,8 @@ class HistogramImpl {
   static void GetEwmaMean(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetEwmaStddev(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetEwmaErrorRate(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void DoExport(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void DoImport(const v8::FunctionCallbackInfo<v8::Value>& args);
 
   static void FastReset(v8::Local<v8::Value> receiver);
   static double FastGetCount(v8::Local<v8::Value> receiver);
diff --git a/test/parallel/test-perf-hooks-histogram-stats.js b/test/parallel/test-perf-hooks-histogram-stats.js
index 9b05a1061682..61a3894924ff 100644
--- a/test/parallel/test-perf-hooks-histogram-stats.js
+++ b/test/parallel/test-perf-hooks-histogram-stats.js
@@ -3,7 +3,7 @@
 
 require('../common');
 const assert = require('assert');
-const { createHistogram } = require('perf_hooks');
+const { createHistogram, importHistogram } = require('perf_hooks');
 
 // ---------------------------------------------------------------------------
 // welchTest(other) — Welch's t-test
@@ -440,6 +440,142 @@ const { createHistogram } = require('perf_hooks');
                 { code: 'ERR_INVALID_ARG_TYPE' });
 }
 
+// ---------------------------------------------------------------------------
+// export() / importHistogram() — CBOR round-trip
+// ---------------------------------------------------------------------------
+{
+  // Basic round-trip
+  const h = createHistogram();
+  for (let i = 1; i <= 1000; i++) h.record(i);
+
+  const buf = h.export();
+  assert.ok(buf instanceof Uint8Array, 'export should return Uint8Array');
+  assert.ok(buf.length > 0, 'export should not be empty');
+
+  const h2 = importHistogram(buf);
+  assert.strictEqual(h2.count, h.count);
+  assert.strictEqual(h2.min, h.min);
+  assert.strictEqual(h2.max, h.max);
+  assert.strictEqual(h2.mean, h.mean);
+  assert.strictEqual(h2.stddev, h.stddev);
+  assert.strictEqual(h2.percentile(50), h.percentile(50));
+  assert.strictEqual(h2.percentile(99), h.percentile(99));
+  assert.strictEqual(h2.percentile(99.9), h.percentile(99.9));
+
+  // Imported histogram is recordable
+  h2.record(9999);
+  assert.strictEqual(h2.count, h.count + 1);
+
+  // Round-trip with EWMA and threshold
+  const h3 = createHistogram({ halfLife: 10, threshold: 500 });
+  for (let i = 1; i <= 200; i++) h3.record(i);
+  const buf3 = h3.export();
+  const h4 = importHistogram(buf3);
+  assert.strictEqual(h4.count, h3.count);
+  assert.strictEqual(h4.ewmaMean, h3.ewmaMean);
+  assert.strictEqual(h4.ewmaStddev, h3.ewmaStddev);
+  assert.strictEqual(h4.ewmaErrorRate, h3.ewmaErrorRate);
+
+  // Empty histogram round-trip
+  const empty = createHistogram();
+  const emptyBuf = empty.export();
+  const empty2 = importHistogram(emptyBuf);
+  assert.strictEqual(empty2.count, 0);
+  assert.strictEqual(empty2.min, 9223372036854776000);  // INT64_MAX as double
+
+  // Sparse: only a few distinct values
+  const sparse = createHistogram();
+  sparse.record(1);
+  sparse.record(1000000);
+  const sparseBuf = sparse.export();
+  const sparse2 = importHistogram(sparseBuf);
+  assert.strictEqual(sparse2.count, 2);
+  assert.strictEqual(sparse2.percentile(1), sparse.percentile(1));
+  assert.strictEqual(sparse2.percentile(100), sparse.percentile(100));
+
+  // Size scales with distinct values, not total bucket count
+  assert.ok(sparseBuf.length < 200,
+            `Sparse export should be small, got ${sparseBuf.length}`);
+
+  // Validation — type and format
+  assert.throws(() => importHistogram('not a uint8array'),
+                { code: 'ERR_INVALID_ARG_TYPE' });
+  assert.throws(() => importHistogram(new Uint8Array(0)),
+                { code: 'ERR_INVALID_ARG_VALUE' });
+  assert.throws(() => importHistogram(new Uint8Array([0xff, 0xff])),
+                { code: 'ERR_INVALID_ARG_VALUE' });
+
+  // --- hdr_init failures (invalid histogram options) ---
+
+  // lowest=0 violates lowest>=1.
+  assert.throws(() => importHistogram(new Uint8Array([0xa1, 0x01, 0x00])),
+                { code: 'ERR_INVALID_ARG_VALUE' });
+  // figures=0 violates figures>=1.
+  assert.throws(() => importHistogram(new Uint8Array([0xa1, 0x03, 0x00])),
+                { code: 'ERR_INVALID_ARG_VALUE' });
+  // figures=6 violates figures<=5.
+  assert.throws(() => importHistogram(new Uint8Array([0xa1, 0x03, 0x06])),
+                { code: 'ERR_INVALID_ARG_VALUE' });
+  // lowest=100, highest=100: lowest*2 > highest.
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa2,                                         // map(2)
+    0x01, 0x18, 100,                              // 1 (lowest) = 100
+    0x02, 0x18, 100,                              // 2 (highest) = 100
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+  // Large values that trigger hdr_init internal overflow
+  // (unit_magnitude + sub_bucket_half_count_magnitude > 61).
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa3,                                         // map(3)
+    0x01, 0x1b, 0, 0, 0x20, 0, 0, 0, 0, 0,       // 1 (lowest) = 2**45
+    0x02, 0x1b, 0, 0, 0x40, 0, 0, 0, 0, 0,       // 2 (highest) = 2**46
+    0x03, 0x05,                                   // 3 (figures) = 5
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+
+  // --- Structural CBOR validation ---
+
+  // Wrong version number (version=99).
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa1,                                         // map(1)
+    0x00, 0x18, 99,                               // 0 (version) = 99
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+  // Unknown top-level key (key=255).
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa1,                                         // map(1)
+    0x18, 0xff, 0x00,                             // 255 (unknown) = 0
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+  // Counts array with odd length (must be even: delta/count pairs).
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa1,                                         // map(1)
+    0x0a, 0x81, 0x01,                             // 10 (counts) = [1]
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+
+  // --- Post-construction validation ---
+
+  // counts_len mismatch: valid options but declared counts_len
+  // doesn't match what hdr_init actually produces.
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa2,                                         // map(2)
+    0x09, 0x01,                                   // 9 (countsLen) = 1
+    0x0a, 0x80,                                   // 10 (counts) = []
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+  // Oversized counts array: declared length exceeds remaining buffer.
+  // Without bounds checking, reserve() would OOM-crash.
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa1,                                         // map(1)
+    0x0a, 0x9b,                                   // 10 (counts) = array(
+    0x00, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, //   2**52 elements)
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+  // Sparse count index out of bounds: lowest=1, highest=100, figures=1
+  // produces counts_len=64. Index 100 exceeds it.
+  assert.throws(() => importHistogram(new Uint8Array([
+    0xa4,                                         // map(4)
+    0x02, 0x18, 0x64,                             // 2 (highest) = 100
+    0x03, 0x01,                                   // 3 (figures) = 1
+    0x09, 0x18, 0x40,                             // 9 (countsLen) = 64
+    0x0a, 0x82, 0x18, 0x64, 0x01,                 // 10 (counts) = [100, 1]
+  ])), { code: 'ERR_INVALID_ARG_VALUE' });
+}
+
 // ---------------------------------------------------------------------------
 // ERR_INVALID_THIS for all new methods on wrong receiver
 // ---------------------------------------------------------------------------

From b7844667cc63c0d7bbc30e2f6fbca6b099451e0a Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Thu, 20 Aug 2026 07:23:37 -0700
Subject: [PATCH 2/2] doc: move histogram.burnRate to correct location in doc

Signed-off-by: James M Snell <jasnell@gmail.com>
---
 doc/api/perf_hooks.md | 62 +++++++++++++++++++++----------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md
index 72d2b9c3b7f0..2bf1b2475387 100644
--- a/doc/api/perf_hooks.md
+++ b/doc/api/perf_hooks.md
@@ -1882,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
@@ -2073,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