RE: Issue 85: Update Stats (Section 13 revamp)

For those interested in what Section 13 looks like with all of the potential edits are made, here it is: 

13. Statistics API

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

interface RTCStatsProvider {
    Promise<RTCStatsReport> 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:

If the object's RTCRtpParameters.RTCRtpEncodingParameters.active state is 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<RTCStatsReport>

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",
    "track",
    "transport",
    "candidatepair",
    "localcandidate",
    "remotecandidate"
};
 
Enumeration description
inboundrtp 
Statistics for the inbound RTP stream that is currently received with this RTCRtpReceiver object. It is accessed by the RTCInboundRTPStreamStats, defined in [WEBRTC-STATS] Section 5.3.3.

outboundrtp 
Statistics for the outbound RTP stream that is currently sent with this RTCRtpSender object. It is accessed by the RTCOutboundRTPStreamStats, defined in [WEBRTC-STATS] Section 5.3.4..

session 
Statistics relating to RTCDataChannel objects. It is accessed by the RTCPeerConnectionStats, defined in [WEBRTC-STATS] Section 5.4 and RTCDataChannelStats defined in [WEBRTC-STATS] Section 5.6.

track 
Statistics relating to the MediaStreamTrack object. It is accessed by RTCMediaStreamTrackStats, defined in [WEBRTC-STATS] Section 5.5.2.

transport 
Transport statistics related to the RTCDtlsTransport object. It is accessed by RTCTransportStats, defined in [WEBRTC-STATS] Section 5.7 and RTCCertificateStats, defined in [WEBRTC-STATS] Section 5.10.

candidatepair 
ICE candidate pair statistics related to RTCIceTransport objects. It is accessed by RTCIceCandidatePairStats, defined in [WEBRTC-STATS] Section 5.9.

localcandidate 
ICE local candidate statistics related to RTCIceTransport objects. It is accessed by RTCIceCandidateAttributes, defined in [WEBRTC-STATS] Section 5.8.

remotecandidate 
ICE remote candidate statistics related to RTCIceTransport objects. It is accessed by RTCIceCandidateAttributes, defined in [WEBRTC-STATS] Section 5.8.

13.4 Example

Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:

EXAMPLE 21
 
var mySender = new RTCRtpSender(myTrack); 
var myPreviousReport = null;

// ... wait a bit
setTimeout(function () {
        mySender.getStats().then(function (report) {
        processStats(report);
        myPreviousReport = report;
    });
}, aBit);

function processStats(currentReport) {
    if (myPreviousReport === null) return;
    // currentReport + myPreviousReport are an RTCStatsReport interface
    // compare the elements from the current report with the baseline
    for (var now in currentReport) {
        if (now.type != "outbound-rtp")
            continue;
        // get the corresponding stats from the previous report
        base = myPreviousReport[now.id];
        // base + now will be of RTCRtpStreamStats dictionary type
        if (base) {
            remoteNow = currentReport[now.remoteId];
            remoteBase = myPreviousReport[base.remoteId];
            var packetsSent = now.packetsSent - base.packetsSent;
            var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;
            // if fractionLost is > 0.3, we have probably found the culprit
            var fractionLost = (packetsSent - packetsReceived) / packetsSent;
        }
    }
}

Received on Sunday, 12 October 2014 02:08:31 UTC