Skip to content

doc: fix perf_hooks documentation gaps and inaccuracies#62194

Open
kovan wants to merge 1 commit intonodejs:mainfrom
kovan:doc-perf-hooks-audit
Open

doc: fix perf_hooks documentation gaps and inaccuracies#62194
kovan wants to merge 1 commit intonodejs:mainfrom
kovan:doc-perf-hooks-audit

Conversation

@kovan
Copy link

@kovan kovan commented Mar 11, 2026

Summary

Audit of doc/api/perf_hooks.md fixing several long-standing documentation
issues:

  • Fix introductory ESM example — the example referenced an undefined
    doSomeLongRunningProcess callback and prematurely called
    performance.clearMarks() in the observer, which would cause subsequent
    performance.measure() calls to throw

  • Add 5 missing PerformanceResourceTiming properties
    initiatorType (added v18.6.0/v16.17.0, PR perf_hooks: add initiatorType getter #43593),
    nextHopProtocol and responseStart (added v18.2.0/v16.17.0, PR perf_hooks: add PerformanceResourceTiming #42725),
    deliveryType and responseStatus (added v22.2.0, PR perf_hooks: add deliveryType and responseStatus fields #51589) are
    implemented in lib/internal/perf/resource_timing.js but were absent from
    the docs

  • Correct PerformanceMark version metadata — introduced in v16.0.0
    (PR perf_hooks: complete overhaul of the implementation #37136), not v18.2.0/v16.17.0 (which is when PR perf_hooks: fix webperf idlharness #44483 reorganized the
    doc sections)

  • Correct PerformanceMeasure version metadata — exported from the module
    in v16.7.0 (PR perf_hooks: add ability to fetch performance entries synchronously #39297), not v18.2.0/v16.17.0

  • Fix histogram.exceeds description — the docs claimed a "1 hour event
    loop delay threshold" but the C++ source (src/histogram-inl.h) shows
    exceeds_ increments when hdr_record_value returns false, i.e. the value
    exceeds the histogram's configured highest trackable value

  • Fix requestStart description — was incorrectly described as "before
    Node.js receives the first byte of the response" (that's responseStart);
    corrected to "before Node.js starts requesting the resource"

  • Generalize Histogram property descriptionsmin, max, mean,
    stddev described "event loop delay" but Histogram is a generic class
    also used by createHistogram() and timerify()

All version metadata verified against full git history (git tag --contains).

Fixes: #40558
Fixes: #40096
Fixes: #40723
Fixes: #55792
Fixes: #55793

- Fix introductory ESM example that references undefined
  `doSomeLongRunningProcess` and prematurely clears marks

- Add missing PerformanceResourceTiming properties: initiatorType,
  nextHopProtocol, responseStart, deliveryType, responseStatus

- Correct PerformanceMark/PerformanceMeasure version metadata from
  v18.2.0/v16.17.0 to v16.0.0 (introduced in PR nodejs#37136)

- Fix histogram.exceeds description: it counts values exceeding the
  histogram's configured `highest` value, not a "1 hour" threshold

- Generalize Histogram property descriptions (min, max, mean, stddev)
  to not reference "event loop delay" since Histogram is a generic class

Fixes: nodejs#40558
Fixes: nodejs#40096
Fixes: nodejs#40723
Fixes: nodejs#55792
Fixes: nodejs#55793

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. perf_hooks Issues and PRs related to the implementation of the Performance Timing API. labels Mar 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to the documentations. perf_hooks Issues and PRs related to the implementation of the Performance Timing API.

Projects

None yet

2 participants