Re: Issue 85: Update Stats

The Statistics API document has been updated at http://www.w3.org/TR/webrtc-stats/. Here is a proposed update to Section 13 to sync up with the changes.

  1.  Statistics API

The Statistics API enables retrieval of statistics relating to RTCRtpSender, RTCRtpReceiver, RTCDtlsTransport, RTCIceGatherer, RTCIceTransport and RTCSctpTransport objects. For detailed information on the Statistics API, consult [WEBRTC-STATS].

interface RTCStatsProvider {
Promise getStats ();
};

13.1 Methods

getStats
Gathers stats for the given object and reports the result asynchronously.

When the getStats() method is invoked, the user agent must queue a task to run the following steps:

For RTCDtlsTransport.getStats(), check whether RTCDtlsTransport.start() has been called; if not, throw an InvalidStateError exception. For RTCIceTransport.getStats(), check whether RTCIceTransport.start() has been called; if not, or if RTCIceTransport.stop() has been called, throw an InvalidStateError exception. For RTCRtpSender.getStats(), check whether RTCRtpSender.send(parameters) has been called; if not, or if parameters.encodings[j].active has a value of false, throw an InvalidStateError exception. For RTCRtpReceiver.getStats(), check whether RTCRtpReceiver.receive(parameters) has been called; if not, or if parameters.encodings[j].active has a value of false, throw an InvalidStateError exception.

Return, but continue the following steps in the background.

Start gathering the stats.

When the relevant stats have been gathered, return a new RTCStatsReport object, representing the gathered stats.

No parameters.
Return type: Promise
13.2 RTCStatsReport Object

The getStats() method delivers a successful result in the form of a RTCStatsReport object. A RTCStatsReport object represents a map between strings, identifying the inspected objects (RTCStats.id), and their corresponding RTCStats objects.

An RTCStatsReport may be composed of several RTCStats objects, each reporting stats for one underlying object. One achieves the total for the object by summing over all stats of a certain type; for instance, if an RTCRtpSender object is sending RTP streams involving multiple SSRCs over the network, the RTCStatsReport may contain one RTCStats object per SSRC (which can be distinguished by the value of the ssrc stats attribute).

interface RTCStatsReport {
getter RTCStats (DOMString id);
};
13.2.1 Methods

RTCStats
Getter to retrieve the RTCStats objects that this stats report is composed of.

The set of supported property names [WEBIDL] is defined as the ids of all the RTCStats objects that has been generated for this stats report. The order of the property names is left to the user agent.

Parameter Type Nullable Optional Description
id DOMString ✘ ✘
Return type: getter
13.3 RTCStats Dictionary

An RTCStats dictionary represents the stats gathered by inspecting a specific object. The RTCStats dictionary is a base type that specifies as set of default attributes, such as timestamp and type. Specific stats are added by extending the RTCStats dictionary.

Note that while stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications must be prepared to deal with unknown stats.

Statistics need to be synchronized with each other in order to yield reasonable values in computation; for instance, if "bytesSent" and "packetsSent" are both reported, they both need to be reported over the same interval, so that "average packet size" can be computed as "bytes / packets" - if the intervals are different, this will yield errors. Thus implementations must return synchronized values for all stats in a RTCStats object.

dictionary RTCStats {
DOMHiResTimeStamp timestamp;
RTCStatsType type;
DOMString id;
};
13.3.1 Dictionary RTCStats Members

id of type DOMString
A unique id that is associated with the object that was inspected to produce this RTCStats object. Two RTCStats objects, extracted from two different RTCStatsReport objects, must have the same id if they were produced by inspecting the same underlying object. User agents are free to pick any format for the id as long as it meets the requirements above.

timestamp of type DOMHiResTimeStamp
The timestamp, of type DOMHiResTimeStamp [HIGHRES-TIME], associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC). The timestamp for local measurements corresponds to the to the local clock and for remote measurements corresponds to the timestamp indicated in the incoming RTCP Sender Report (SR), Receiver Report (RR) or Extended Report (XR).

type of type RTCStatsType
The type of this object.

The type attribute must be initialized to the name of the most specific type this RTCStats dictionary represents.

13.3.2 enum RTCStatsType

enum RTCStatsType {
"inboundrtp",
"outboundrtp",
"session",
"datachannel",
"track",
"transport",
"candidatepair",
"localcandidate",
"remotecandidate"
};
Enumeration description
inboundrtp

Statistics for the inbound RTP stream. It is accessed via the RTCInboundRTPStreamStats defined in [WEBRTC-STATS] Section 4.2.3. Local inbound RTP statistics can be obtained from the RTCRtpReceiver object; remote inbound RTP statistics can be obtained from the RTCRtpSender object.

outboundrtp
Statistics for the outbound RTP stream. It is accessed via the RTCOutboundRTPStreamStats defined in [WEBRTC-STATS] Section 4.2.4. Local outbound RTP statistics can be obtained from the RTCRtpSender object; remote outbound RTP statistics can be obtained from the RTCRtpReceiver object.

session
Statistics relating to RTCDataChannel objects. It is accessed via the RTCPeerConnectionStats defined in [WEBRTC-STATS] Section 4.3.

datachannel
Statistics relating to each RTCDataChannel id. It is accessed via the RTCDataChannelStats defined in [WEBRTC-STATS] Section 4.5.

track

Statistics relating to the MediaStreamTrack object. It is accessed via the RTCMediaStreamTrackStats defined in [WEBRTC-STATS] Section 4.4.2.

transport

Transport statistics related to the RTCDtlsTransport object. It is accessed via the RTCTransportStats and RTCCertificateStats defined in [WEBRTC-STATS] Sections 4.6 and 4.9.

candidatepair

ICE candidate pair statistics related to RTCIceTransport objects. It is accessed via the RTCIceCandidatePairStats defined in [WEBRTC-STATS] Section 4.8.

localcandidate

ICE local candidates, related to RTCIceGatherer objects. It is accessed via the RTCIceCandidateAttributes defined in [WEBRTC-STATS] Section 4.7.

remotecandidate
ICE remote candidate, related to RTCIceTransport objects. It is accessed via the RTCIceCandidateAttributes defined in [WEBRTC-STATS] Section 4.7.

C. References

C.1 Normative references

[WEBRTC-STATS]
Harald Alvestrand; Varun Singh. Identifiers for WebRTC's Statistics API. 06 February 2015 (work in progress). URL: http://www.w3.org/TR/webrtc-stats/