diff --git a/packages/utils/src/lib/performance-observer.ts b/packages/utils/src/lib/performance-observer.ts index 0c55f0ff2..6c75f09e9 100644 --- a/packages/utils/src/lib/performance-observer.ts +++ b/packages/utils/src/lib/performance-observer.ts @@ -95,8 +95,10 @@ export type PerformanceObserverOptions = { /** * Whether to enable buffered observation mode. - * When true, captures all performance entries that occurred before observation started. - * When false, only captures entries after subscription begins. + * + * When true, captures all performance marks and measures that exist in the Node.js + * performance buffer at the time `subscribe()` is called using `performance.getEntriesByType()` + * (the native `buffered` option is unreliable in Node.js). * * @default true */ @@ -309,9 +311,8 @@ export class PerformanceObserverSink { * * Creates a Node.js PerformanceObserver that monitors 'mark' and 'measure' entries. * The observer uses a bounded queue with proactive flushing to manage memory usage. - * When buffered mode is enabled, any existing buffered entries are immediately flushed. + * When buffered mode is enabled, existing entries are captured via `performance.getEntriesByType()` instead of the unreliable native `buffered` option. * If the sink is closed, items stay in the queue until reopened. - * */ subscribe(): void { if (this.#observer) { @@ -322,11 +323,7 @@ export class PerformanceObserverSink { this.processPerformanceEntries(list.getEntries()); }); - // When buffered mode is enabled, Node.js PerformanceObserver invokes - // the callback synchronously with all buffered entries before observe() returns. - // However, entries created before any observer existed may not be buffered by Node.js. - // We manually retrieve entries from the performance buffer using getEntriesByType() - // to capture entries that were created before the observer was created. + // Manually capture buffered entries instead of the unreliable native buffered option. if (this.#buffered) { const existingMarks = performance.getEntriesByType('mark'); const existingMeasures = performance.getEntriesByType('measure'); @@ -336,8 +333,7 @@ export class PerformanceObserverSink { this.#observer.observe({ entryTypes: OBSERVED_TYPES, - // @NOTE: This is for unknown reasons not working, and we manually do it above - // buffered: this.#buffered, + // Note: buffered option intentionally omitted due to unreliability in Node.js. }); }