RTCStatsReport - make this the center of statistics docs #27028
Conversation
Preview URLs (42 pages)
Flaws (85)Note! 25 documents with no flaws that don't need to be listed. 🎉 URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
(comment last updated: 2023-06-05 07:08:48) |
|
|
||
| ## Examples | ||
|
|
||
| ### Iterate report from an RTCPeerConnection using forEach loop |
There was a problem hiding this comment.
FWIW all the examples are similar because they are all ways of iterating the map and checking against type. We should revisit this later with a few more interesting examples - looking at real statistics - that would show off things like taking averages as I did in the peer connection stats.
Don't want to do that until I have a better idea of what you can do with stats.
| The **`keys()`** method of the {{domxref("RTCStatsReport")}} interface returns a new _[map iterator](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)_ object that can be used to iterate through the keys for each element in the `RTCStatsReport` object, in insertion order. | ||
|
|
||
| The keys in the `RTCStatsReport` are unique string `id` values, which represent the monitored statistics objects from which the statistics are derived. |
There was a problem hiding this comment.
FYI I wasn't sure how to do this (everywhere) refer to keys, and values as per map and then explain what they are, or refer to them as ids and statistics dictionaries. My feeling is that this approach is slightly better.
|
|
||
| ### Using keys() | ||
|
|
||
| This example shows how to iterate through a statistics report by calling `next()` on the iterator returned by `keys()`. |
There was a problem hiding this comment.
Note that this example is a little contrived. Yes you can do it, but as we're only using the keys to get the values, you might as well iterate the values or entries.
As far as I can tell the ids aren't all that useful unless you're comparing a particular statistic across a timeslice.
What do you think about converting this to a "Analyzing WebRTC statistics" guide page? It doesn't make sense at all as an API overview page. (edited: or you could just fold whatever is salvageable into https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport. Less work. But I do feel this could benefit from a guide.) |
hamishwillee
force-pushed
the
rtcstatsreport_fixes
branch
from
1a9011d
to
2d3a9ed
Compare
…Analyzing WebRTC Statistics
| @@ -0,0 +1,84 @@ | |||
| --- | |||
There was a problem hiding this comment.
@wbamberg This is the old WebRTC Statistics API page moved to the title you suggested. I tidied up the table and there is a lot more work that can and should be done. This is "less crap" than it was. But we will need to create a more complete guide later, after having done all the dictionaries.
This PR should merge first.
Co-authored-by: wbamberg <[email protected]>
| The report may contain many different categories of statistics, including inbound and outbound statistics for both the current and remote ends of the peer connection, information about codecs, certificates and media used, and so on. | ||
| Each category of statistic is provided in a different type of statistics dictionary object, which can be identified from its [`type`](#type) property. | ||
|
|
||
| ### Common instance properties |
There was a problem hiding this comment.
@wbamberg OK, so this adds a specific section in description about the instance properties, as you suggested in https://github.com/mdn/content/pull/27028/files#r1213871272
It makes clear that you probably use type to find your stat of interest, and can subsequently use the id to track change.
This could do with an example, but it is pretty hard to test stuff. So for now I have not done one.
If I was to, I might expand the example here: https://developer.mozilla.org/en-US/docs/Web/API/RTCAudioSourceStats#examples
Showing how you calculate the audio level across a timeslice.
|
Thanks for that. I think we're ready for another round of re-review. |
* zh-cn: sync translated content * RTCStatsReport - make this the center of statistics docs ref: mdn/content#27028 --------- Co-authored-by: allo <[email protected]>
|
Thanks so much for the review. I appreciate it is not much fun! :-( |
We're flattening the
RTCStatshierarchy and making the entry points clearer. This updates RTCStatsReport to include the list of types it might return and information about the map methods.I have individually documented the map methods. I don't think we can just link to map because the versions in which these are implemented would then not be documentable in the context of RTCStatsReport BCD.
If this gets in, next step would be to purge RTCStats. Then start filling out the other dictionaries.
A question - this is in
RTCStatsReportis shown in WebRTC API home page AND https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_Statistics_API -. Is this second doc of any use? It has no sidebar, and I will move most things intoRTCStatsReport?Or to put it another way, how do we handle sidebars with these kind of "sub APIs"
This is part of the docs work in #26146