Identifiers for WebRTC's Statistics API

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY and MUST are to be interpreted as described in [RFC2119].

This specification defines the conformance criteria that applies to a single product: the user agent.

Implementations that use ECMAScript to implement the APIs and objects defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this document uses that specification and terminology.

This specification does not define what objects a conforming implementation should generate. Specifications that refer to this specification have the need to specify conformance. They should put in their document text like this:

An implementation MUST support generating statistics for the type RTCInboundRTPStreamStats, with attributes packetsReceived, bytesReceived, packetsLost, jitter, and fractionLost.
It MUST support generating statistics for the type RTCOutboundRTPStreamStats, with attributes packetsSent, bytesSent.
For all subclasses of RTCRtpStreamStats, it MUST include ssrc, associateStatsId, isRemote, mediaType.
It MAY support generating other stats.

3. Terminology

The EventHandler represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task, and fires a simple event are defined in [HTML5].

The terms event, event handlers, and event handler event types are defined in [HTML5].

The terms MediaStream, MediaStreamTrack, and Consumer are defined in [GETUSERMEDIA].

The terms RTCPeerConnection, RTCDataChannel, RTCDtlsTransport and RTCIceTransport are defined in [WEBRTC].

The term RTP stream is defined in [RFC7656] section 2.1.10.

4.1 Guidelines for design of stats objects

When introducing a new stats type, the following principles should be followed:

An RTCStats object should correspond to an object defined in the specification it supports.
All members of the new object need to have definitions that make them consistently implementable. References to other specifications are a good way of doing this.
All members need to have defined behavior for what happens before the thing it counts happens, or when the information it's supposed to show is not available. Usually, this will be "start at zero" or "do not populate the value".

The new members of the stats dictionary need to be named according to standard practice (camelCase).

Names ending in "Id" (such as "datachannelId") are always of type DOMString and are used to refer to other stats objects by the value of their "id" field; names ending in "Ids" (such as "trackIds") are always of type sequence<DOMString>, and are used to refer to a list of other stats objects.

4.2 Guidelines for implementing stats objects

When implementing stats objects, the following guidelines should be adhered to:

When a feature is not implemented on the platform, omit the dictionary member that is tracking usage of the feature.
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".
When a counted feature hasn't been used yet, but may happen in the future, report a count of zero.

4.3 Lifetime of stats objects

The general rule is that stats objects, once created, exist for the lifetime of the PeerConnection that contains them, even when the underlying object they report on is stopped or deleted. This is important in order to report consistently on short-lived objects and to be able to report totals over the lifetime of a PeerConnection.

When an object is closed or deleted, the timestamp member of the stats object stops updating; it is frozen at the time when the object stopped.

5. Maintenance procedures for stats types

This document, in its editors' draft form, serves as the repository for the currently defined set of stats types.

If a need for a new stats dictionary or dictionary member is found, an issue should be raised against this spec on Github, and a review process will decide on whether the stat should be added to the specification or not.

A pull request for a change to this document may serve as guidance for the discussion, but the eventual merge is dependent on the review process.

While the WebRTC WG exist, it will serve as the review body; once it has disbanded, the W3C will have to establish appropriate review.

The level of review sought is that of the IETF process' "expert review", as defined in [RFC5226] section 4.1. The documentation needed includes the names of the new stats, their data types, and the definitions they are based on, specified to a level that allows interoperable implementation. The specification may consist of references to other documents.

Another specification that wishes to refer to a specific version (for instance for conformance) should refer to a dated version; these will be produced regularly when updates happen.

6. RTCStatsType

The type element, of type RTCStatsType, indicates the type of the object that the RTCStats object represents. An object with a given "type" can have only one IDL dictionary type, but multiple "type" values may indicate the same IDL dictionary type; for example, "local-candidate" and "remote-candidate" both use the IDL dictionary type RTCIceCandidateStats.

This specification is normative for the allowed values of RTCStatsType.

enum RTCStatsType {
    "codec",
    "inbound-rtp",
    "outbound-rtp",
    "peer-connection",
    "data-channel",
    "track",
    "transport",
    "candidate-pair",
    "local-candidate",
    "remote-candidate",
    "certificate"
};

The following strings are valid values for RTCStatsType:

codec: Statistics for a codec that is currently being used by RTP streams being sent or received by this RTCPeerConnection object. It is accessed by the RTCCodecStats.
inbound-rtp: Statistics for an inbound RTP stream that is currently received with this RTCPeerConnection object. It is accessed by the RTCInboundRTPStreamStats.
outbound-rtp: Statistics for an outbound RTP stream that is currently sent with this RTCPeerConnection object. It is accessed by the RTCOutboundRTPStreamStats.
peer-connection: Statistics related to the RTCPeerConnection object. It is accessed by the RTCPeerConnectionStats.
data-channel: Statistics related to each RTCDataChannel id. It is accessed by the RTCDataChannelStats.
track: Contains statistics related to a specific MediaStreamTrack and the corresponding media-level metrics. It is accessed by the RTCMediaStreamStats.
transport: Transport statistics related to the RTCPeerConnection object. It is accessed by the RTCTransportStats.
candidate-pair: ICE candidate pair statistics related to the RTCIceTransport objects. It is accessed by the RTCIceCandidatePairStats.
local-candidate: ICE local candidate statistics related to the RTCIceTransport objects. It is accessed by the RTCIceCandidateStats for the local candidate.
remote-candidate: ICE remote candidate statistics related to the RTCIceTransport objects. It is accessed by the RTCIceCandidateStats for the remote candidate.
certificate: Information about a certificate used by an RTCIceTransport.

7. Stats dictionaries

7.1 `RTCRTPStreamStats` dictionary

dictionary RTCRTPStreamStats : RTCStats {
    DOMString          ssrc;
    DOMString          associateStatsId;
    boolean            isRemote = false;
    DOMString          mediaType;
    DOMString          mediaTrackId;
    DOMString          transportId;
    DOMString          codecId;
    unsigned long      firCount;
    unsigned long      pliCount;
    unsigned long      nackCount;
    unsigned long      sliCount;
    unsigned long long qpSum;
};

Dictionary `RTCRTPStreamStats` Members

ssrc of type DOMString

associateStatsId of type DOMString

The associateStatsId is used for looking up the corresponding (local/remote) RTCStats object for a given SSRC.

isRemote of type boolean, defaulting to false

false indicates that the statistics are measured locally, while true indicates that the measurements were done at the remote endpoint and reported in an RTCP RR/XR.

mediaType of type DOMString

Either "audio" or "video". This MUST match the media type part of the information in the corresponding codec member of RTCCodecStats.

mediaTrackId of type DOMString

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this RTP stream.

codecId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCCodecStats associated with this RTP stream.

firCount of type unsigned long

Count the total number of Full Intra Request (FIR) packets received by the sender. This metric is only valid for video and is sent by receiver. Calculated as defined in [RFC5104] section 4.3.1. and does not use the metric indicated in [RFC2032], because it was deprecated by [RFC4587].

pliCount of type unsigned long

Count the total number of Packet Loss Indication (PLI) packets received by the sender. This metric is only valid for video and is sent by receiver. Calculated as defined in [RFC4585] section 6.3.1.

nackCount of type unsigned long

Count the total number of Negative ACKnowledgement (NACK) packets received by the sender and is sent by receiver. Calculated as defined in [RFC4585] section 6.2.1.

sliCount of type unsigned long

Count the total number of Slice Loss Indication (SLI) packets received by the sender. This metric is only valid for video and is sent by receiver. Calculated as defined in [RFC4585] section 6.3.2.

qpSum of type unsigned long long

The sum of the QP values of frames passed. The count of frames is in framesDecoded for inbound stream stats, and in framesEncoded for outbound stream stats.

The definition of QP value depends on the codec; for VP8, the QP value is the value carried in the frame header as the syntax element "y_ac_qi", and defined in [RFC6386] section 19.2. Its range is 0..127.

Note that the QP value is only an indication of quantizer values used; many formats have ways to vary the quantizer value within the frame.

Only valid for video.

7.2 `RTCCodecStats` dictionary

dictionary RTCCodecStats : RTCStats {
    unsigned long payloadType;
    DOMString     codec;
    unsigned long clockRate;
    unsigned long channels;
    DOMString     parameters;
    DOMString     implementation;
};

Dictionary `RTCCodecStats` Members

payloadType of type unsigned long

Payload type as used in RTP encoding.

codec of type DOMString

e.g., video/vp8 or equivalent.

clockRate of type unsigned long

Represents the media sampling rate.

channels of type unsigned long

Use 2 for stereo, missing for most other cases.

parameters of type DOMString

From the SDP description line.

implementation of type DOMString

Identifies the implementation used. This is useful for diagnosing interoperability issues.

If too much information is given here, it increases the fingerprint surface. Since it is only given for active tracks, the incremental exposure is small.

7.3 RTCInboundRTPStreamStats dictionary

The RTCInboundRTPStreamStats dictionary represents the measurement metrics for the incoming RTP media stream.

dictionary RTCInboundRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsReceived;
    unsigned long long bytesReceived;
    unsigned long      packetsLost;
    double             jitter;
    double             fractionLost;
    unsigned long      packetsDiscarded;
    unsigned long      packetsRepaired;
    unsigned long      burstPacketsLost;
    unsigned long      burstPacketsDiscarded;
    unsigned long      burstLossCount;
    unsigned long      burstDiscardCount;
    double             burstLossRate;
    double             burstDiscardRate;
    double             gapLossRate;
    double             gapDiscardRate;
    unsigned long      framesDecoded;
};

Dictionary `RTCInboundRTPStreamStats` Members

packetsReceived of type unsigned long

Total number of RTP packets received for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

bytesReceived of type unsigned long long

Total number of bytes received for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

packetsLost of type unsigned long

Total number of RTP packets lost for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.

jitter of type double

Packet Jitter measured in seconds for this SSRC. Calculated as defined in section 6.4.1. of [RFC3550].

fractionLost of type double

The fraction packet loss reported for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1 and Appendix A.3.

packetsDiscarded of type unsigned long

The cumulative number of RTP packets discarded by the jitter buffer due to late or early-arrival, i.e., these packets are not played out. RTP packets discarded due to packet duplication are not reported in this metric [XRBLOCK-STATS]. Calculated as defined in [ RFC7002] section 3.2 and Appendix A.a.

packetsRepaired of type unsigned long

The cumulative number of lost RTP packets repaired after applying an error-resilience mechanism [XRBLOCK-STATS]. It is measured for the primary source RTP packets and only counted for RTP packets that have no further chance of repair. To clarify, the value is upper-bound to the cumulative number of lost packets. Calculated as defined in [ RFC7509] section 3.1 and Appendix A.b.

burstPacketsLost of type unsigned long

The cumulative number of RTP packets lost during loss bursts, Appendix A (c) of [RFC6958].

burstPacketsDiscarded of type unsigned long

The cumulative number of RTP packets discarded during discard bursts, Appendix A (b) of [RFC7003].

burstLossCount of type unsigned long

The cumulative number of bursts of lost RTP packets, Appendix A (e) of [RFC6958].

[RFC3611] recommends a Gmin (threshold) value of 16 for classifying a sequence of packet losses or discards as a burst.

burstDiscardCount of type unsigned long

The cumulative number of bursts of discarded RTP packets, Appendix A (e) of [burst-gap-discard].

burstLossRate of type double

The fraction of RTP packets lost during bursts to the total number of RTP packets expected in the bursts. As defined in Appendix A (a) of [RFC7004], however, the actual value is reported without multiplying by 32768.

burstDiscardRate of type double

The fraction of RTP packets discarded during bursts to the total number of RTP packets expected in bursts. As defined in Appendix A (e) of [RFC7004], however, the actual value is reported without multiplying by 32768.

gapLossRate of type double

The fraction of RTP packets lost during the gap periods. Appendix A (b) of [RFC7004], however, the actual value is reported without multiplying by 32768.

gapDiscardRate of type double

The fraction of RTP packets discarded during the gap periods. Appendix A (f) of [RFC7004], however, the actual value is reported without multiplying by 32768.

framesDecoded

Only valid for video. It represents the total number of frames correctly decoded for this SSRC. Same definition as totalVideoFrames in Section 5 of [MEDIA-SOURCE].

7.4 RTCOutboundRTPStreamStats dictionary

RTCOutboundRTPStreamStats dictionary represents the measurement metrics for the outgoing RTP stream.

dictionary RTCOutboundRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsSent;
    unsigned long long bytesSent;
    double             targetBitrate;
    double             roundTripTime;
    unsigned long      framesEncoded;
};

Dictionary `RTCOutboundRTPStreamStats` Members

packetsSent of type unsigned long: Total number of RTP packets sent for this SSRC. Calculated as defined in [ RFC3550] section 6.4.1.
bytesSent of type unsigned long long: Total number of bytes sent for this SSRC. Calculated as defined in [RFC3550] section 6.4.1.
targetBitrate of type double: It is the current target bitrate configured for this particular SSRC and is the Transport Independent Application Specific (TIAS) bitrate [RFC3890]. Typically, the target bitrate is a configuration parameter provided to the codec's encoder and does not count the size of the IP or other transport layers like TCP or UDP. It is measured in bits per second and the bitrate is calculated over a 1 second window.
roundTripTime of type double: Estimated round trip time for this SSRC based on the RTCP timestamps in the RTCP Receiver Report (RR) and measured in seconds. Calculated as defined in section 6.4.1. of [RFC3550].
framesEncoded of type long: Only valid for video. It represents the total number of frames successfully encoded for this RTP media stream.

7.5 `RTCPeerConnectionStats` dictionary

dictionary RTCPeerConnectionStats : RTCStats {
    unsigned long dataChannelsOpened;
    unsigned long dataChannelsClosed;
};

Dictionary `RTCPeerConnectionStats` Members

dataChannelsOpened of type unsigned long: Represents the number of unique datachannels opened.
dataChannelsClosed of type unsigned long: Represents the number of unique datachannels closed.

7.6 `RTCMediaStreamStats` dictionary

dictionary RTCMediaStreamStats : RTCStats {
    DOMString           streamIdentifier;
    sequence<DOMString> trackIds;
};

Dictionary `RTCMediaStreamStats` Members

streamIdentifier of type DOMString: stream.id property
trackIds of type sequence<DOMString>: This is the id of the stats object, not the track.id.

7.7 `RTCMediaStreamTrackStats` dictionary

An RTCMediaStreamTrackStats object represents the stats about a MediaStreamTrack's connection to the PeerConnection object for which one calls getStats.

It appears in the stats as soon as it is attached (via addTrack, via addTransceiver, via ReplaceTrack on an RTPSender object, or via being created on an RTPReceiver object). If it is detached (via removeTrack or via replaceTrack), it continues to appear, but with the "detached" member set to True.

dictionary RTCMediaStreamTrackStats : RTCStats {
    DOMString           trackIdentifier;
    boolean             remoteSource;
    boolean             ended;
    boolean             detached;
    sequence<DOMString> ssrcIds;
    unsigned long       frameWidth;
    unsigned long       frameHeight;
    double              framesPerSecond;
    unsigned long       framesSent;
    unsigned long       framesReceived;
    unsigned long       framesDecoded;
    unsigned long       framesDropped;
    unsigned long       framesCorrupted;
    unsigned long       partialFramesLost;
    unsigned long       fullFramesLost;
    double              audioLevel;
    double              echoReturnLoss;
    double              echoReturnLossEnhancement;
};

Dictionary `RTCMediaStreamTrackStats` Members

trackIdentifier of type DOMString: Represents the track.id property.
remoteSource of type boolean
ended of type boolean: Reflects the "ended" state of the track.
detached of type boolean: True if the track has been detached from the PeerConnection object. If true, all stats reflect their values at the time when the track was detached.
ssrcIds of type sequence<DOMString>
frameWidth of type unsigned long: Only valid for video MediaStreamTracks and represents the width of the video frame for this track.
frameHeight of type unsigned long: Only valid for video MediaStreamTracks and represents the height of the video frame for this MediaStreamTrack.
framesPerSecond of type double: Only valid for video. It represents the nominal FPS value.
framesSent of type unsigned long: Only valid for video. It represents the total number of frames sent for this MediaStreamTrack.
framesReceived of type unsigned long: Only valid for video and when remoteSource is set to true. It represents the total number of frames received for this MediaStreamTrack.
framesDecoded of type unsigned long: Only valid for video and when remoteSource is set to true. It represents the total number of frames correctly decoded for this MediaStreamTrack, independent of which SSRC it was received from. It is defined as totalVideoFrames in Section 5 of [MEDIA-SOURCE].
framesDropped of type unsigned long: Only valid for video. It is the total number of frames dropped predecode or dropped because the frame missed its display deadline for this MediastreamTrack. It is the same definition as droppedVideoFrames in Section 5 of [MEDIA-SOURCE].
framesCorrupted of type unsigned long: Only valid for video. It is the total number of corrupted frames that have been detected for this MediaStreamTrack. It is the same definition as corruptedVideoFrames in Section 5 of [MEDIA-SOURCE].
partialFramesLost of type unsigned long: Only valid for video. partialFramesLost is the cumulative number of partial frames lost, as defined in Appendix A (j) of [RFC7004].
fullFramesLost of type unsigned long: Only valid for video. fullFramesLost is the cumulative number of full frames lost, as defined in Appendix A (i) of [RFC7004].
audioLevel of type double: Only valid for audio, and the value is between 0..1 (linear), where 1.0 represents 0 dBov. Calculated as defined in [RFC6464].
echoReturnLoss of type double: Only present on audio tracks sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.14.
echoReturnLossEnhancement of type double: Only present on audio tracks sourced from a microphone where echo cancellation is applied. Calculated in decibels, as defined in [ECHO] (2012) section 3.15.

7.8 `RTCDataChannelStats` dictionary

dictionary RTCDataChannelStats : RTCStats {
    DOMString           label;
    DOMString           protocol;
    long                datachannelid;
    RTCDataChannelState state;
    unsigned long       messagesSent;
    unsigned long long  bytesSent;
    unsigned long       messagesReceived;
    unsigned long long  bytesReceived;
};

Dictionary `RTCDataChannelStats` Members

label of type DOMString
protocol of type DOMString
datachannelid of type long: the "id" attribute of the RTCDataChannel object
state of type RTCDataChannelState
messagesSent of type unsigned long: Represents the total number of API "message" events sent.
bytesSent of type unsigned long long: Represents the total number of payload bytes sent on this RTCDatachannel, i.e., not including headers or padding.
messagesReceived of type unsigned long: Represents the total number of API "message" events received.
bytesReceived of type unsigned long long: Represents the total number of bytes received on this RTCDatachannel, i.e., not including headers or padding.

7.9 `RTCTransportStats` dictionary

An RTCTransportStats object represents the stats corresponding to an RTCDtlsTransport and its underlying RTCIceTransport. When RTCP multiplexing is used, one transport is used for both RTP and RTCP. Otherwise, RTP and RTCP will be sent on separate transports, and rtcpTransportStatsId can be used to pair the resulting RTCTransportStats objects. Additionally, when bundling is used, a single transport will be used for all MediaStreamTracks in the bundle group. If bundling is not used, different MediaStreamTrack will use different transports. RTCP multiplexing and bundling are described in [WEBRTC].

dictionary RTCTransportStats : RTCStats {
    unsigned long long bytesSent;
    unsigned long long bytesReceived;
    DOMString          rtcpTransportStatsId;
    boolean            activeConnection;
    DOMString          selectedCandidatePairId;
    DOMString          localCertificateId;
    DOMString          remoteCertificateId;
};

Dictionary `RTCTransportStats` Members

bytesSent of type unsigned long long: Represents the total number of payload bytes sent on this PeerConnection, i.e., not including headers or padding.
bytesReceived of type unsigned long long: Represents the total number of bytes received on this PeerConnection, i.e., not including headers or padding.
rtcpTransportStatsId of type DOMString: If RTP and RTCP are not multiplexed, this is the id of the transport that gives stats for the RTCP component, and this record has only the RTP component stats.
activeConnection of type boolean: Set to true when transport is active.
selectedCandidatePairId of type DOMString: It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidatePairStats associated with this transport.
localCertificateId of type DOMString: For components where DTLS is negotiated, give local certificate.
remoteCertificateId of type DOMString: For components where DTLS is negotiated, give remote certificate.

7.10 `RTCIceCandidateStats` dictionary

RTCIceCandidateStats reflects the properties of a candidate in Section 15.1 of [RFC5245]. It corresponds to a RTCIceCandidate object.

dictionary RTCIceCandidateStats : RTCStats {
    DOMString           transportId;
    boolean             isRemote;
    DOMString           ip;
    long                port;
    DOMString           protocol;
    RTCIceCandidateType candidateType;
    long                priority;
    DOMString           url;
    boolean             deleted = false;
};

Dictionary `RTCIceCandidateStats` Members

transportId of type DOMString

It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateStats associated with this candidate.

isRemote of type boolean

false indicates that this represents a local candidate; true indicates that this represents a remote candidate.

ip of type DOMString

It is the IP address of the candidate, allowing for IPv4 addresses and IPv6 addresses, but fully qualified domain names (FQDNs) are not allowed. See [RFC5245] section 15.1 for details.

port of type long

It is the port number of the candidate.

protocol of type DOMString

Valid values for transport is one of udp and tcp. Based on the "transport" defined in [RFC5245] section 15.1.

candidateType of type RTCIceCandidateType

This enumeration is defined in [WEBRTC].

priority of type long

Calculated as defined in [RFC5245] section 15.1.

url of type DOMString

The URL of the TURN or STUN server indicated in the that translated this IP address. It is the URL address surfaced in an RTCPeerConnectionIceEvent.

deleted of type boolean, defaulting to false

For local candidates, true indicates that the candidate has been deleted/freed as described by [RFC5245]. For host candidates, this means that any network resources (typically a socket) associated with the candidate have been released. For TURN candidates, this means the TURN allocation is no longer active.

For remote candidates, this property is not applicable.

7.11 `RTCIceCandidatePairStats` dictionary

dictionary RTCIceCandidatePairStats : RTCStats {
    DOMString                     transportId;
    DOMString                     localCandidateId;
    DOMString                     remoteCandidateId;
    RTCStatsIceCandidatePairState state;
    unsigned long long            priority;
    boolean                       nominated;
    boolean                       writable;
    boolean                       readable;
    unsigned long long            bytesSent;
    unsigned long long            bytesReceived;
    double                        totalRoundTripTime;
    double                        currentRoundTripTime;
    double                        availableOutgoingBitrate;
    double                        availableIncomingBitrate;
    unsigned long long            requestsReceived;
    unsigned long long            requestsSent;
    unsigned long long            responsesReceived;
    unsigned long long            responsesSent;
    unsigned long long            retransmissionsReceived;
    unsigned long long            retransmissionsSent;
    unsigned long long            consentRequestsReceived;
    unsigned long long            consentRequestsSent;
    unsigned long long            consentResponsesReceived;
    unsigned long long            consentResponsesSent;
};

Dictionary `RTCIceCandidatePairStats` Members

transportId of type DOMString: It is a unique identifier that is associated to the object that was inspected to produce the RTCTransportStats associated with this candidate pair.
localCandidateId of type DOMString: It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateAttributes for the local candidate associated with this candidate pair.
remoteCandidateId of type DOMString: It is a unique identifier that is associated to the object that was inspected to produce the RTCIceCandidateAttributes for the remote candidate associated with this candidate pair.
state of type RTCStatsIceCandidatePairState: Represents the state of the checklist for the local and remote candidates in a pair.
priority of type unsigned long long: Calculated from candidate priorities as defined in [RFC5245] section 5.7.2.
nominated of type boolean: Related to updating the nominated flag described in Section 7.1.3.2.4 of [ RFC5245].
writable of type boolean: Has gotten ACK to an ICE request.
readable of type boolean: Has gotten a valid incoming ICE request.
bytesSent of type unsigned long long: Represents the total number of payload bytes sent on this candidate pair, i.e., not including headers or padding.
bytesReceived of type unsigned long long: Represents the total number of payload bytes received on this candidate pair, i.e., not including headers or padding.
totalRoundTripTime of type double: Represents the sum of all round trip time measurements in seconds since the beginning of the session, based on both STUN connectivity check [ STUN-PATH-CHAR] responses (responsesReceived) and consent [ RFC7675] responses (consentResponsesReceived). The average round trip time can be computed from totalRoundTripTime by dividing it by (responsesReceived + consentResponsesReceived).
currentRoundTripTime of type double: Represents the latest round trip time measured in seconds, computed from both STUN connectivity checks [STUN-PATH-CHAR] and consent responses [RFC7675].
availableOutgoingBitrate of type double: It is calculated by the underlying congestion control by combining the available bitrate for all the outgoing RTP streams using this candidate pair. The bitrate measurement does not count the size of the IP or other transport layers like TCP or UDP. It is similar to the TIAS defined in [RFC3890], i.e., it is measured in bits per second and the bitrate is calculated over a 1 second window.
availableIncomingBitrate of type double: It is calculated by the underlying congestion control by combining the available bitrate for all the incoming RTP streams using this candidate pair. The bitrate measurement does not count the size of the IP or other transport layers like TCP or UDP. It is similar to the TIAS defined in [RFC3890], i.e., it is measured in bits per second and the bitrate is calculated over a 1 second window.
requestsReceived of type unsigned long long: Represents the total number of connectivity check requests received (including retransmissions).
requestsSent of type unsigned long long: Represents the total number of connectivity check requests sent (not including retransmissions).
responsesReceived of type unsigned long long: Represents the total number of connectivity check responses received.
responsesSent of type unsigned long long: Represents the total number of connectivity check responses sent.
retransmissionsReceived of type unsigned long long: Represents the total number of connectivity check retransmissions received.
retransmissionsSent of type unsigned long long: Represents the total number of connectivity check retransmissions sent.
consentRequestsReceived of type unsigned long long: Represents the total number of consent requests received.
consentRequestsSent of type unsigned long long: Represents the total number of consent requests sent.
consentResponsesReceived of type unsigned long long: Represents the total number of consent responses received.
consentResponsesSent of type unsigned long long: Represents the total number of consent responses sent.

7.11.1 `RTCStatsIceCandidatePairState` enum

enum RTCStatsIceCandidatePairState {
    "frozen",
    "waiting",
    "inprogress",
    "failed",
    "succeeded",
    "cancelled"
};

Enumeration description
`frozen`	Defined in Section 5.7.4 of [RFC5245].
`waiting`	Defined in Section 5.7.4 of [RFC5245].
`inprogress`	Defined in Section 5.7.4 of [RFC5245].
`failed`	Defined in Section 5.7.4 of [RFC5245].
`succeeded`	Defined in Section 5.7.4 of [RFC5245].
`cancelled`	Defined in Section 5.7.4 of [RFC5245].

7.12 RTCCertificateStats dictionary

dictionary RTCCertificateStats : RTCStats {
    DOMString fingerprint;
    DOMString fingerprintAlgorithm;
    DOMString base64Certificate;
    DOMString issuerCertificateId;
};

Dictionary `RTCCertificateStats` Members

fingerprint of type DOMString: Only use the fingerprint value as defined in Section 5 of [RFC4572].
fingerprintAlgorithm of type DOMString: For instance, "sha-256".
base64Certificate of type DOMString: For example, DER-encoded, base-64 representation of a certifiate.
issuerCertificateId of type DOMString

8. Examples

8.1 Example of association of local and remote statistics

The following example code shows the association of remote statistics with local statistics in a RTCStats dictionary.

Example 1

stats [
   dictionary (of type RTPoutboundStatsDictionary) {
      ssrc=1234
      id=foobar
      type=outboundrtp
      isRemote=false
      associateStatsId=barfoo
  },
  dictionary (of type RTPinboundStatsDictionary) {
      ssrc=1234
      id=barfoo
      type=inboundrtp
      isRemote=true
      associateStatsId=foobar
  }
]

8.2 Example of a stats application

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 2

var baselineReport, currentReport;
var selector = pc.getRemoteStreams()[0].getAudioTracks()[0];

pc.getStats(selector, function (report) {
    baselineReport = report;
}, logError);

// ... wait a bit
setTimeout(function () {
    pc.getStats(selector, function (report) {
        currentReport = report;
        processStats();
    }, logError);
}, aBit);

function processStats() {
    // compare the elements from the current report with the baseline
    for (var i in currentReport) {
        var now = currentReport[i];
        if (now.type != "outbund-rtp")
            continue;

        // get the corresponding stats from the baseline report
        base = baselineReport[now.id];

        if (base) {
            remoteNow = currentReport[now.associateStatsId];
            remoteBase = baselineReport[base.associateStatsId];

            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;
        }
    }
}

function logError(error) {
    log(error.name + ": " + error.message);
}

9. Security Considerations

Some stats identifiers may expose personally identifiable information, for example the IP addresses of the participating endpoints when a TURN relay is not used.

10. Change Log

This section will be removed before publication. The entries are in reverse chronological order.

10.1 Changes since 21 sep 2016

[#64] Added text about which specification is authoriative
[#59] Example conformance specification
[#71] Introduced the term "RTP stream"
[#76] Adding missing "codec" RTCStatsType
[#68] Design considerations section
[#73] Fix the summary of RTCTransportStats
[#75] Clarify that pliCount is only valid for video
[#70] Added QP statistcs
[#90] Adding "deleted" property to RTCIceCandidate
[#93] Adding isRemote to RTCIceCandidate
[#95] Rename "RTT" to RoundTripTime
[#94] Add TransportId to RTCIceCandidateStats
[#43] Added procedures for new stats

This list does not include infrastructure and minor editorials.

10.2 Changes since 26 May 2016

[#54] Debug problems with ICE.
[#52] adding XRBLOCK metrics
[#51] Dashed enums and crosslinking to stats objects.
[#37] Clarified RTT units.

10.3 Changes since 23 October 2015

[#18] Updated spec changes.
[#17] Changed "remoteId" to "associateStatsId".
[#8] Ended and detached stats for a track.
[#33] Added the codec "implementation" variable.
[#34]Converted to WebIDL contiguious mode.
[#36] Aligned RTCIceCandidateStats with RTCIceCandidate.
[#24] Added packetsDiscarded and packetsRepaired to stats.
[#13] Aligned bitrate to the TIAS definition.
[#47] Changed RTCCodec to RTCCodecStats
Various formatting, layout and link fixes.

10.4 Changes since 03 February 2015

[#10] Added RTCRTPStreamStats.mediaType.

10.5 Changes since 30 September 2014

kept getStats() in webrtc-pc. Changed RTCStatsType from enum to DOMString.
Added "datachannel" to RTCStatsType.
Added fractionLost to RTCInboundRTPStreamStats.
Clarified that bytesSent and bytesReceived do no include headers or paddings.

10.6 Acknowledgements

The editors wish to thank the Working Group chairs, Stefan Håkansson, and the Team Contact, Dominique Hazaël-Massieux, for their support. The editors would like to thank Bernard Aboba, Jan-Ivar Bruaroey, and Cullen Jennings for their contributions to this specification.

A.1 Normative references

[ECHO]: ITU-T G.168. ITU-T. Digital network echo cancellers. Standard. URL: https://www.itu.int/rec/T-REC-G.168/en
[GETUSERMEDIA]: Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. Media Capture and Streams. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
[HTML5]: Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/
[MEDIA-SOURCE]: Matthew Wolenetz; Jerry Smith; Mark Watson; Aaron Colwell; Adrian Bateman. W3C. Media Source Extensions™. 17 November 2016. W3C Recommendation. URL: https://www.w3.org/TR/media-source/
[RFC2119]: S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3550]: H. Schulzrinne; S. Casner; R. Frederick; V. Jacobson. IETF. RTP: A Transport Protocol for Real-Time Applications. July 2003. Internet Standard. URL: https://tools.ietf.org/html/rfc3550
[RFC3611]: T. Friedman, Ed.; R. Caceres, Ed.; A. Clark, Ed.. IETF. RTP Control Protocol Extended Reports (RTCP XR). November 2003. Proposed Standard. URL: https://tools.ietf.org/html/rfc3611
[RFC3890]: M. Westerlund. IETF. A Transport Independent Bandwidth Modifier for the Session Description Protocol (SDP). September 2004. Proposed Standard. URL: https://tools.ietf.org/html/rfc3890
[RFC4572]: J. Lennox. IETF. Connection-Oriented Media Transport over the Transport Layer Security (TLS) Protocol in the Session Description Protocol (SDP). July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4572
[RFC4585]: J. Ott; S. Wenger; N. Sato; C. Burmeister; J. Rey. IETF. Extended RTP Profile for Real-time Transport Control Protocol (RTCP)-Based Feedback (RTP/AVPF). July 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4585
[RFC5104]: S. Wenger; U. Chandra; M. Westerlund; B. Burman. IETF. Codec Control Messages in the RTP Audio-Visual Profile with Feedback (AVPF). February 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5104
[RFC5245]: J. Rosenberg. IETF. Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols. April 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5245
[RFC6464]: J. Lennox, Ed.; E. Ivov; E. Marocco. IETF. A Real-time Transport Protocol (RTP) Header Extension for Client-to-Mixer Audio Level Indication. December 2011. Proposed Standard. URL: https://tools.ietf.org/html/rfc6464
[RFC6958]: A. Clark; S. Zhang; J. Zhao; Q. Wu, Ed.. IETF. RTP Control Protocol (RTCP) Extended Report (XR) Block for Burst/Gap Loss Metric Reporting. May 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc6958
[RFC7002]: A. Clark; G. Zorn; Q. Wu. IETF. RTP Control Protocol (RTCP) Extended Report (XR) Block for Discard Count Metric Reporting. September 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7002
[RFC7003]: A. Clark; R. Huang; Q. Wu, Ed.. IETF. RTP Control Protocol (RTCP) Extended Report (XR) Block for Burst/Gap Discard Metric Reporting. September 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7003
[RFC7004]: G. Zorn; R. Schott; Q. Wu, Ed.; R. Huang. IETF. RTP Control Protocol (RTCP) Extended Report (XR) Blocks for Summary Statistics Metrics Reporting. September 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7004
[RFC7509]: R. Huang; V. Singh. IETF. RTP Control Protocol (RTCP) Extended Report (XR) for Post-Repair Loss Count Metrics. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7509
[RFC7675]: M. Perumal; D. Wing; R. Ravindranath; T. Reddy; M. Thomson. IETF. Session Traversal Utilities for NAT (STUN) Usage for Consent Freshness. October 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7675
[STUN-PATH-CHAR]: T. Reddy; D. Wing; P. Martinsen; V. Singh. IETF. Discovery of path characteristics using STUN. Internet Draft. URL: https://tools.ietf.org/html/draft-reddy-tram-stun-path-data
[WEBRTC]: Adam Bergkvist; Daniel Burnett; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. WebRTC 1.0: Real-time Communication Between Browsers. 24 November 2016. W3C Working Draft. URL: https://www.w3.org/TR/webrtc/
[burst-gap-discard]: Varun Singh; Colin Perkins; Alan Clark; Rachel Huang. IETF. RTCP XR Block for Independent Reporting of Burst/Gap Discard Metric. Internet Draft. URL: https://tools.ietf.org/html/draft-ietf-xrblock-independent-burst-gap-discard

A.2 Informative references

[RFC2032]: T. Turletti; C. Huitema. IETF. RTP Payload Format for H.261 Video Streams. October 1996. Proposed Standard. URL: https://tools.ietf.org/html/rfc2032
[RFC4587]: R. Even. IETF. RTP Payload Format for H.261 Video Streams. August 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4587
[RFC5226]: T. Narten; H. Alvestrand. IETF. Guidelines for Writing an IANA Considerations Section in RFCs. May 2008. Best Current Practice. URL: https://tools.ietf.org/html/rfc5226
[RFC6386]: J. Bankoski; J. Koleszar; L. Quillio; J. Salonen; P. Wilkins; Y. Xu. IETF. VP8 Data Format and Decoding Guide. November 2011. Informational. URL: https://tools.ietf.org/html/rfc6386
[RFC7656]: J. Lennox; K. Gross; S. Nandakumar; G. Salgueiro; B. Burman, Ed.. IETF. A Taxonomy of Semantics and Mechanisms for Real-Time Transport Protocol (RTP) Sources. November 2015. Informational. URL: https://tools.ietf.org/html/rfc7656
[WEBIDL]: Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. Web IDL. 15 September 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/
[XRBLOCK-STATS]: Varun Singh; Rachel Huang; Roni Even; Dan Romascanu; Lingli Deng. IETF. RTCP XR Metrics for WebRTC. Internet Draft. URL: https://tools.ietf.org/html/draft-ietf-xrblock-rtcweb-rtcp-xr-metrics

Abstract

Status of This Document

1. Introduction

2. Conformance

3. Terminology

4. Basic concepts

4.1 Guidelines for design of stats objects

4.2 Guidelines for implementing stats objects

4.3 Lifetime of stats objects

5. Maintenance procedures for stats types

6. RTCStatsType

7. Stats dictionaries

7.1 RTCRTPStreamStats dictionary

Dictionary RTCRTPStreamStats Members

7.2 RTCCodecStats dictionary

Dictionary RTCCodecStats Members

7.3 RTCInboundRTPStreamStats dictionary

Dictionary RTCInboundRTPStreamStats Members

7.4 RTCOutboundRTPStreamStats dictionary

Dictionary RTCOutboundRTPStreamStats Members

7.5 RTCPeerConnectionStats dictionary

Dictionary RTCPeerConnectionStats Members

7.6 RTCMediaStreamStats dictionary

Dictionary RTCMediaStreamStats Members

7.7 RTCMediaStreamTrackStats dictionary

Dictionary RTCMediaStreamTrackStats Members

7.8 RTCDataChannelStats dictionary

Dictionary RTCDataChannelStats Members

7.9 RTCTransportStats dictionary

Dictionary RTCTransportStats Members

7.10 RTCIceCandidateStats dictionary

Dictionary RTCIceCandidateStats Members

7.11 RTCIceCandidatePairStats dictionary

Dictionary RTCIceCandidatePairStats Members

7.11.1 RTCStatsIceCandidatePairState enum