docs(utils): clarify buffered mode implementation in PerformanceObserverSink #1233
+7
−11
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…d limitations Co-authored-by: BioPhoton <10064416+BioPhoton@users.noreply.github.com>
Author
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Copilot
AI
changed the title
[WIP] WIP address feedback from review on sharded WAL refactor PR
docs(utils): clarify buffered mode implementation in PerformanceObserverSink
Feb 1, 2026
BioPhoton
requested changes
Feb 1, 2026
Comment on lines
323
to
351
| * ## Buffered Mode Implementation | ||
| * | ||
| * When `captureBufferedEntries` is true, this method captures all performance entries | ||
| * that exist in the Node.js performance buffer at the time of subscription. | ||
| * | ||
| * **Why Manual Approach:** | ||
| * The standard `buffered: true` option in PerformanceObserver.observe() is not used | ||
| * because it has proven unreliable in Node.js environments. Instead, we use | ||
| * `performance.getEntriesByType()` to manually retrieve buffered entries. | ||
| * | ||
| * **Guarantees:** | ||
| * - All marks and measures in the performance buffer at subscription time will be captured | ||
| * - Entries are processed synchronously before the observer begins watching for new entries | ||
| * - No entries created after subscription will be missed (observer handles them) | ||
| * | ||
| * **Limitations:** | ||
| * - Potential for duplicate processing if an entry exists both in the buffer and is | ||
| * delivered by the observer callback (though Node.js typically avoids this) | ||
| * - Performance buffer has a limited size; very old entries may have been evicted by Node.js | ||
| * - The manual approach captures a snapshot at subscription time; there's a small race | ||
| * condition window where entries created during getEntriesByType() execution might | ||
| * be captured by both the manual call and the observer | ||
| * | ||
| * **Memory Management:** | ||
| * Applications should call `performance.clearMarks()` and `performance.clearMeasures()` | ||
| * periodically to prevent the Node.js performance buffer from growing unbounded. | ||
| * This is especially important when using buffered mode, as the entire buffer is | ||
| * processed on subscription. | ||
| */ |
Collaborator
There was a problem hiding this comment.
Too muh test. could you reduce it to 1 sentence @copilot
Author
There was a problem hiding this comment.
Reduced the extensive documentation section to one concise sentence that explains the manual approach and why the native option isn't used. Changes in commit 37cc84e.
Co-authored-by: BioPhoton <10064416+BioPhoton@users.noreply.github.com>
Author
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The
subscribe()method uses a manualperformance.getEntriesByType()workaround instead of the nativebufferedoption, but documentation was unclear about why.Changes
captureBufferedEntriesoption: Simplified documentation to explain the manual approach usingperformance.getEntriesByType()and note that the nativebufferedoption is unreliable in Node.jssubscribe()method: Added concise explanation that buffered entries are captured viaperformance.getEntriesByType()instead of the unreliable nativebufferedoptionThe documentation now concisely explains why the manual approach is used (native
bufferedoption unreliability) without extensive detail about guarantees, limitations, or memory management.✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.