Add docs for JS self-profiling API by wbamberg · Pull Request #37796 · mdn/content

wbamberg · 2025-01-24T19:10:04Z

Docs for the JS Self-Profiling API.

I've included a page for samplebufferfull which is mentioned in the spec but not defined, and which doesn't have a BCD entry yet.
in my experiments I often see samples which only have a timestamp and no stack ID. I believe that these are when the browser is doing some other work that isn't directly executing the program, like GC. Is that right? I should probably say something about this.
this API is protected using Document Policy which AFAIK is not documented on MDN. I haven't done that as part of this PR but we should. I think there is an issue somewhere to document it but I can't find it in mdn/content.

github-actions · 2025-01-24T19:11:27Z

Preview URLs (6 pages)

Flaws (2)

Note! 5 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/JS_Self-Profiling_API
Title: JS Self-Profiling API
Flaw count: 2

broken_links:
- /en-US/docs/Glossary/call_stack is ill cased
macros:
- Macro produces link /en-US/docs/Glossary/call_stack which is a redirect

External URLs (2)

URL: /en-US/docs/Web/API/Profiler/Profiler
Title: Profiler: Profiler() constructor

https://wicg.github.io/document-policy/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/JS_Self-Profiling_API
Title: JS Self-Profiling API

https://wicg.github.io/document-policy/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-28 22:05:22)

captainbrosset

Looks great to me from a tech writing perspective. Thanks Will.
I'll ping someone from my side to take a look at the technical details too.

files/en-us/web/api/js_self-profiling_api/index.md

files/en-us/web/api/js_self-profiling_api/profile_content_and_format/index.md

captainbrosset · 2025-01-27T09:24:29Z

files/en-us/web/api/profiler/samplebufferfull_event/index.md

@@ -0,0 +1,49 @@
+---
+title: "Profiler: samplebufferfull event"


It is indeed mentioned briefly in the spec, and is implemented in chromium (it seems).
I think this should be spec'd properly, and then added to BCD.

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

skyclouds2001 · 2025-02-14T15:56:27Z

see mdn/mdn#507

wbamberg · 2025-02-25T02:11:12Z

@captainbrosset , did you find anyone who could take a look at this?

captainbrosset · 2025-02-26T13:23:29Z

@captainbrosset , did you find anyone who could take a look at this?

@wbamberg I will ask again. Thanks for the ping.

nhelfman · 2025-02-26T15:55:34Z

files/en-us/web/api/js_self-profiling_api/profile_content_and_format/profile.svg

small correction - the stack frame has resource id which points to an index in the resources array.

What I'm trying to talk about here is the logical structure of a profile, not the data structure of the object returned by the API. The intention in this page is to talk about the (1) the logical structure, (2) the data structure, and (3) how to map from (2) to (1).

nhelfman · 2025-02-26T15:57:38Z

files/en-us/web/api/js_self-profiling_api/profile_content_and_format/index.md

+
+Each stack frame contains information about the location of its corresponding function in the program:
+
+- The URL of the script


similar to the other comment - this is not the URL but an index to the URL of the script

nhelfman · 2025-02-26T16:14:49Z

Let me just say that this is great you are doing this!

I'm wondering if best practices for using the Profiler should also be included to help users avoid shooting themselves in the foot.

For example, it may be worth mentioning that there might be some overhead in collecting profile and processing trace data and developers should be measure performance impact carefully.

Some potential strategies to address that:

Increase sampling interval - this will produce less samples but will have lower impact.
Collect profiles for short periods in a sampled manner. E.g. trace for 5 seconds every 60 seconds.
Process the samples in a web worker to avoid impacting performance on the main thread.
The Profiler has a potential to generate huge amount of data which will be hard to send to a central place for processing. It is possible to aggregate samples on the client before sending them to analytics/telemetry system.

Caveat - since in production systems the JS is typically minified - the captured traces will include minified function names which can be hard to reason about. Some ammonification logic has to happen wither on the client before sending or on the analytics system to un-minify the traces based on source maps.

wbamberg · 2025-02-26T18:12:41Z

I'm wondering if best practices for using the Profiler should also be included to help users avoid shooting themselves in the foot.

Yes, this makes a lot of sense! I will write something up based on your comment. Thanks for taking a look.

wbamberg · 2025-02-27T01:26:42Z

Thanks for the review @nhelfman ! I added a bit on "best practices". I didn't change the bit about the stack frame containing the resource URL because that part is intended to describe the abstract/logical structure of a trace, not the implementation. If there's anything I can do to make that clearer I'm happy to have a go at it.

nhelfman · 2025-02-27T08:28:53Z

Thanks for the review @nhelfman ! I added a bit on "best practices". I didn't change the bit about the stack frame containing the resource URL because that part is intended to describe the abstract/logical structure of a trace, not the implementation. If there's anything I can do to make that clearer I'm happy to have a go at it.

Maybe indicate that this is an abstracted logical illustration so it will be clearer to the reader.

wbamberg · 2025-02-27T20:07:08Z

OK, I added some bits in dbef9f2 and 4236c92 to try to clarify that this section is not a description of the object format, and expanded on the preamble to try to describe the overall purpose of this page better (which is basically how to interpret the object returned, so you can reason about it).

wbamberg · 2025-03-21T06:31:47Z

I'm merging this, it has an r+ and has been around for a while.

* upstream/main: (172 commits) chore: improve code style guide (mdn#38715) fix: typo on `Error.isError()` page (mdn#38754) plural consistency (mdn#38747) fix: auto-cleanup by bot (mdn#38695) Synchronize with BCD v5.7.4 (mdn#38709) Add docs for JS self-profiling API (mdn#37796) Better SameSite docs (mdn#38710) Added missing explanation for Array Literals (mdn#38745) Add a page on CSRF (mdn#38151) Fix description of several Range methods (mdn#38518) Remove extraneous span (mdn#38696) Add a definition for media containers, improve how the media files are defined and Remove wrong information (mdn#38721) Move visited selector guide to CSS selectors module (mdn#38642) Make JSON learning article more technically precise (mdn#38644) Make translate3d() interactive example code valid (mdn#38647) Clarity on Safari support for custom elements (mdn#38727) feat(css): Link to learning doc about text direction (mdn#38719) Fix typo (mdn#38739) move guide to module: inline formatting context (mdn#38637) Fix CSS pseudo-class lists (mdn#38576) ...

* Add docs for JS self-profiling API * Apply suggestions from code review Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com> * Review feedback * Clarify that 'anatomy of a profile' doesn't describe object format * More clarification --------- Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

Add docs for JS self-profiling API

4311bac

wbamberg requested review from a team as code owners January 24, 2025 19:10

wbamberg requested review from bsmth and sideshowbarker and removed request for a team January 24, 2025 19:10

github-actions bot added the Content:WebAPI Web API docs label Jan 24, 2025

wbamberg requested a review from captainbrosset January 24, 2025 19:10

github-actions bot added the size/m [PR only] 51-500 LoC changed label Jan 24, 2025

sideshowbarker removed their request for review January 25, 2025 12:14

captainbrosset approved these changes Jan 27, 2025

View reviewed changes

Apply suggestions from code review

d556ad1

Co-authored-by: Patrick Brosset <patrickbrosset@gmail.com>

wbamberg mentioned this pull request Jan 28, 2025

Blog about self-profiling API docs openwebdocs/owd-website#142

Open

skyclouds2001 mentioned this pull request Feb 14, 2025

Add documentation for JS Self-Profiling API | Or combine it with current Performance APIs mdn/mdn#507

Closed

6 tasks

nhelfman reviewed Feb 26, 2025

View reviewed changes

Merge branch 'main' into js-self-profiling-api

8e026d2

Review feedback

13127f0

wbamberg added 2 commits February 27, 2025 11:56

Clarify that 'anatomy of a profile' doesn't describe object format

dbef9f2

More clarification

4236c92

bsmth removed their request for review March 10, 2025 15:35

wbamberg merged commit 49f3683 into mdn:main Mar 21, 2025
9 checks passed

		@@ -0,0 +1,49 @@
		---
		title: "Profiler: samplebufferfull event"


		Each stack frame contains information about the location of its corresponding function in the program:

		- The URL of the script

Conversation

wbamberg commented Jan 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

captainbrosset left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

captainbrosset Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

skyclouds2001 commented Feb 14, 2025

Uh oh!

wbamberg commented Feb 25, 2025

Uh oh!

captainbrosset commented Feb 26, 2025

Uh oh!

nhelfman Feb 26, 2025

Choose a reason for hiding this comment

Uh oh!

wbamberg Feb 26, 2025

Choose a reason for hiding this comment

Uh oh!

nhelfman Feb 26, 2025

Choose a reason for hiding this comment

Uh oh!

nhelfman commented Feb 26, 2025

Uh oh!

wbamberg commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wbamberg commented Feb 27, 2025

Uh oh!

nhelfman commented Feb 27, 2025

Uh oh!

wbamberg commented Feb 27, 2025

Uh oh!

wbamberg commented Mar 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

wbamberg commented Jan 24, 2025 •

edited

Loading

github-actions bot commented Jan 24, 2025 •

edited

Loading

wbamberg commented Feb 26, 2025 •

edited

Loading