Skip to content

perf_hooks: implement SlidingWindowHistogram - #65825

Open
jasnell wants to merge 2 commits into
nodejs:mainfrom
jasnell:jasnell/perf-hooks-slidingwindowhistogram
Open

perf_hooks: implement SlidingWindowHistogram#65825
jasnell wants to merge 2 commits into
nodejs:mainfrom
jasnell:jasnell/perf-hooks-slidingwindowhistogram

Conversation

@jasnell

@jasnell jasnell commented Sep 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Builds on #65806 ... this will remain draft until that lands. The first commit here is from 65806.

Implements SlidingWindowHistogram

const { createSlidingWindowHistogram } = require('node:perf_hooks');

const window = createSlidingWindowHistogram({
  chunks: 6,
  chunkDuration: 10_000,  // chunks are valid for 10 seconds
});

window.record(20_000_000);

// Materialize the current window as an independent Histogram.
const snapshot = window.snapshot();
console.log(snapshot.percentile(99));

Allows for count or time based windows. No timers are used. Validation and allocation are lazy. Uses a ring buffer internally to keep things bounded.

This completes the migration of my typical "performance analysis toolkit" that I've used for some time into built-in primitives.

Example of all this in use: https://github.com/jasnell/fastify-sliding-health

@jasnell
jasnell requested a review from mcollina September 5, 2026 16:57
@nodejs-github-bot

nodejs-github-bot commented Sep 5, 2026

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/performance

@jasnell
jasnell marked this pull request as draft September 5, 2026 16:57
@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Sep 5, 2026
@codecov

codecov Bot commented Sep 5, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 87.13826% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.99%. Comparing base (666edfd) to head (e496081).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/histogram.cc 77.40% 8 Missing and 32 partials ⚠️
Additional details and impacted files 
@@           Coverage Diff            @@
##             main   #65825    +/-   ##
========================================
  Coverage   89.98%   89.99%            
========================================
  Files         785      785            
  Lines      269282   269584   +302     
  Branches    51296    51370    +74     
========================================
+ Hits       242323   242619   +296     
+ Misses      17464    17430    -34     
- Partials     9495     9535    +40
Files with missing lines Coverage Δ
lib/internal/histogram.js 97.22% <100.00%> (+0.81%) ⬆️
lib/perf_hooks.js 100.00% <100.00%> (ø)
src/histogram.h 84.31% <100.00%> (+8.80%) ⬆️
src/node_perf.cc 86.77% <100.00%> (+0.11%) ⬆️
src/histogram.cc 85.25% <77.40%> (+0.05%) ⬆️

... and 25 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jasnell jasnell added the semver-minor PRs that contain new features and should be released in the next minor version. label Sep 5, 2026
@jasnell
perf_hooks: implement SlidingWindowHistogram
98a0362 
The current recordable `Histogram` does not maintain any sense
of time. Samples accumulate indefinitely as they are collected.
This implements a relatively simple sliding-window mechanism
that can be count or time based. The key benefit is that the
window remains fixed/bounded while samples are recorded.

The sliding window is chunk based. Internally, it maintains
a ring buffer of a fixed number of individual histograms.
When snapshot() is called, those are materialized into a
single combined histogram. As the window slides, older
chunks (and all of the samples they hold) are dropped from
the window so the window drops however many samples happened
to be in that chunk. This does mean that precision of the
window is determined by the chunk size.

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode
@jasnell
test: expand histogram test coverage
e496081 
Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode
@jasnell
jasnell force-pushed the jasnell/perf-hooks-slidingwindowhistogram branch from 3d03781 to e496081 Compare September 12, 2026 23:13
@jasnell
jasnell marked this pull request as ready for review September 12, 2026 23:13
mcollina
mcollina approved these changes Sep 13, 2026
View reviewed changes

@mcollina mcollina left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mcollina mcollina mcollina approved these changes

Assignees

No one assigned

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. semver-minor PRs that contain new features and should be released in the next minor version.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jasnell @nodejs-github-bot @mcollina