787242 - GC: Document the observer/JSON GC stats interface

Status: RESOLVED FIXED

(Core :: JavaScript Engine, defect)

Description

[Terrence Cole [:terrence]]

This interface is getting way more usage than I originally anticipated.  I need to create a page on MDN that documents how to get data out of it and what the fields in the JSON blob mean.

Comment 1

[Nicholas Nethercote [inactive]]

My standard observation:  wikis are never up-to-date.  Can this be a comment in the code?

Comment 2

[Andrew McCreight [:mccr8]]

This is an interface intended for addon writers, so a Wiki I think will be less intimidating.  It should also be reasonably stable.  That said, it might be good to have a version in the code itself.  More things to let go out of date!

Comment 3

[Nicholas Nethercote [inactive]]

In that case, the code should contain a reference to the URL of the wiki page.

Comment 4

[Terrence Cole [:terrence]]

The JSON interface is now documented at:
https://developer.mozilla.org/en-US/docs/SpiderMonkey/Internals/Garbage_collection

Bill may have more to add to it.  I think we also want to split this article into several sub-pages - including one for the Statistic interface - as it is getting quite long.

Comment 5

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Looks good so far. Thanks Terrence! Just one question where we could add a bit more details:

> mmu_20ms: Integer (percentage) - A measurement of overall GC performance.

What type of measurement is that? What does the percentage number tell us?

Comment 6

[Terrence Cole [:terrence]]

Looks like there is a good explanation here:
https://bugzilla.mozilla.org/show_bug.cgi?id=719492#c2

Comment 7

[Terrence Cole [:terrence]]

Benoit, Henrik, Bill, or anyone else: is this documentation adequate?  Does anyone see (or rather: not see) anything more I should add before closing this bug?

Comment 8

[Henrik Skupin [:whimboo][⌚️UTC+1]]

The only thing I have to note is that in its current state it will be really hard to find on MDN. For people who do not know what to search for we probably should add a heading which includes API. That way it will be listed in the TOC too. Just saying, because I have even problems to find it.

Comment 9

[Terrence Cole [:terrence]]

Excellent idea!  I've split out the text into a sub-article:
https://developer.mozilla.org/en-US/docs/SpiderMonkey/Internals/GC/Statistics_API

And relabeled the section as "GC Statistics API".  The new page has tags SpiderMonkey, GC, and API, so it should also be easier to search for now.

Comment 10

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Hm, the link points to no-where :/

https://developer.mozilla.org/en-US/docs/SpiderMonkey/Internals/Garbage_collection#GC_Statistics_API

Comment 11

[Terrence Cole [:terrence]]

Sorry about that, thought the wiki software would be smarter about updating references.  Should be fixed now.

Comment 12

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Looks great at least for the API part I mostly understand! Thanks Terrence.

Comment 13

[Bill McCloskey [inactive unless it's an emergency] (:billm)]

I made a few revisions to the statistics article. I think we can mark this as closed now.