Clarify that metrics are omitted when their value is not yet determined or unknown about webrtc-stats HOT 7 CLOSED

@fippo

from webrtc-stats.

I don't think this is controversial so using labels "Editorial" and "Ready for PR"

from webrtc-stats.

Yeah, this is mostly wordsmithing. But behold, this is a can of worms.

IMO encoderImplementation/decoderImplementation fall under this

When a counted feature hasn't been used yet, but may happen in the future, report a count of zero.

but for strings. For these it may make sense to include the empty string despite guidance against this in the sentence before.
I think it is the only two cases? Easy... but behold...

"may happen in the future" is vague. What this means is you:

• should include packetsLost (even though you may never loose a packet)
  since it means that you can safely subtract stats from two times T_a and T_b without worrying about a value being undefined a T_a.

This applies to some things that are not "counted" but should be covered like STUN RTT. This should be 0 initially and be present. It is clear that this has not happened yet because responsesReceived is still 0.

STUN currentRoundTripTime however should not be present before a response has been received.
Neither should audioLevel before you decode or send a packet.
Both values are instantaneous. Following that logic, decoderImplementation should not be set either.

For RTCP we have conflicting guidance in here to only include when a RR with a non-zero DLSR field was received (and yep, that takes some time, say hello to flaky tests). This seems slightly off, the intention is to count valid round trip times and only increment for those.

Now trying to summarize that I would say the guidance should be

• When a cumulative feature hasn't been used yet report a count of zero so stats values from two points in time can be safely subtracted.
• When an momentary feature hasn't been used yet, omit the dictionary member

from webrtc-stats.

If there is no current (e.g. currentRoundTripTime), then it is not applicable. Not applicable => undefined.
Same reasoning applies to encoderImplementation. If there is no current encoder, then enoderImplementation is not applicable, so its undefined.

A counted feature starting at 0 is separate, if something has happened no times then the counter is 0, its a superflous sentence in the spec

from webrtc-stats.

"4.2 Guidelines for implementing stats objects" already says to use undefined if "a feature is not applicable"

It doesn't say that. It says: "When a feature is not applicable to an instance of an object (for example audioLevel on a video stream), omit the dictionary member. Do NOT report a count of zero, -1 or "empty string"."

It says to "omit" the member, which is different from a value of undefined. audioLevel: "Only exists for audio."

E.g. here audioLevel exists:

{audioLevel: undefined}

...and here it is omitted:

{}

AFAIK WebIDL bindings coerce the former into the latter on input (e.g. dictionaries as arguments to a method), but not output.

from webrtc-stats.

(I'm interpreting defined/undefined in this thread to mean missing/present/exists. See #737. LMK if that's not right)

While there might be some value today in knowing immediately whether a browser supports a stat or not, such value should diminish over time, so omitting members until they can be accurately reported seems superior to me to the alternatives.

There's probably some precedence here with stats objects of type remote-inbound-rtp and remote-outbound-rtp which don't appear until rtcp packets have been received (e.g. comment out the await wait(5000) in this fiddle).

from webrtc-stats.

You're right I meant missing when I said undefined. We should fix #737.

from webrtc-stats.