This document defines a set of WebIDL objects that allow access to the statistical information about a PeerConnection.
These objects are returned from the getStats API that is specified in [[WEBRTC]].
This document is incomplete, and as such is not yet suitable for implementation. However, early experimentation is encouraged.
Audio, video, or data packets transmitted over a peer-connection can be lost, and experience varying amounts of network delay. A web application implementing WebRTC expects to monitor the performance of the underlying network and media pipeline.
This document defines the statistic identifiers used by the web application to extract metrics from the user agent.
This specification defines the conformance criteria that applies to a single product: the user agent.
Implementations that use ECMAScript to implement the 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:
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, RTCDtlsTransportState and RTCIceTransport are defined in [[!WEBRTC]].
The term RTP stream is defined in [[RFC7656]] section 2.1.10.
The terms RTCStats, The terms
RTCStats.timestamp,
RTCStats.type,
RTCStats.id,
RTCCertificate, are defined
in [[!WEBRTC]].
The basic object of the stats model is the stats object. The following terms are defined to describe it:
An internal object that keeps a set of data values. Most monitored objects are object defined in the WebRTC API; they may be thought of as being internal properties of those objects.
A monitored object has a stable identifier "id", which is reflected in all stats objects produced from the monitored object. Stats objects may contain references to other stats objects using this "id" value. In a stats object, these references are represented by a DOMString containing "id" value of the referenced stats object.
All stats object references have type DOMString and attribute names ending in 'Id', or they have type sequence<DOMString> and attribute names ending in 'Ids'.
A monitored object changes the values it contains continuously over its lifetime, but is never visible through the getStats API call. A stats object, once returned, never changes.
The stats API is defined in [[!WEBRTC]]. It is defined to return a collection of stats objects, each of which is a dictionary inheriting directly or indirectly from the RTCStats dictionary. This API is normatively defined in [[!WEBRTC]], but is reproduced here for ease of reference.
dictionary RTCStats {
DOMHighResTimeStamp timestamp;
RTCStatsType type;
DOMString id;
};
When introducing a new stats object, the following principles should be followed:
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 a stats object reference; names ending in "Ids" (such as "trackIds") are always of type sequence<DOMString>, where each DOMString is a stats object reference.
Stats are sampled by Javascript. In general, an application will not have overall control over how often stats are sampled, and the implementation cannot know what the intended use of the stats is. There is, by design, no control surface for the application to influence how stats are generated.
Therefore, letting the implementation compute "average" rates is not a good idea, since that implies some averaging time interval that can't be set beforehand. Instead, the recommended approach is to count the number of measurements of a value and sum the measurements given even if the sum is meaningless in itself; the JS application can then compute averages over any desired time interval by calling getStats() twice, taking the difference of the two sums and dividing by the difference of the two counts.
For stats that are measured against time, such as byte counts, no separate counter is needed; one can instead divide by the difference in the timestamps.
When implementing stats objects, the following guidelines should be adhered to:
When a monitored object is destroyed, a final stats object is produced, carrying the values current at the time of destruction. This object will be returned, with a timestamp reflecting the time of destruction, whenever getStats() is called, as long as the PeerConnection exists. This is important in order to report consistently on short-lived objects and to be able to consistently report totals over the lifetime of a PeerConnection.
This document, in its editors' draft form, serves as the repository for the currently defined set of stats object types.
If a need for a new stats object type or stats value within a stats object 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.
At times, it makes sense to retire the definition for a stats object or a stats value. When this happens, it is not advisable to simply delete it from the spec, since there may be implementations out there that use it, and it is important that the name is reserved from re-use for another, incompatible definition.
Therefore, retired stats objects are moved to a separate section in this document. Retired stats objects are moved there in their entirety; retired stats values are moved to a "partial dictionary".
If there is no evidence that the retired object definition has ever been used (such as an object that is added to the spec and renamed, redefined or removed prior to implementation), the editors can decide to just remove the object from the spec.
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",
"csrc",
"peer-connection",
"data-channel",
"stream",
"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.
csrc
Statistics for a contributing source (CSRC) that contributed to
an inbound RTP stream. It is accessed by the
RTCRTPContributingSourceStats.
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.
stream
Contains statistics related to a specific MediaStream. It is accessed by the
RTCMediaStreamStats.
track
Contains statistics related to a specific MediaStreamTrack and the corresponding
media-level metrics. It is accessed by the
RTCMediaStreamTrackStats.
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. It is accessed by the
RTCCertificateStats.
dictionary RTCRTPStreamStats : RTCStats {
unsigned long ssrc;
DOMString associateStatsId;
boolean isRemote = false;
DOMString mediaType;
DOMString trackId;
DOMString transportId;
DOMString codecId;
unsigned long firCount;
unsigned long pliCount;
unsigned long nackCount;
unsigned long sliCount;
unsigned long long qpSum;
};
ssrc of type unsigned
long
The 32-bit unsigned integer value per [[RFC3550]] used to identify the source of the stream of RTP packets that this stats object concerns.
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, and MUST match the "kind" attribute of the
related MediaStreamTrack.
trackId 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.
dictionary RTCCodecStats : RTCStats {
unsigned long payloadType;
DOMString mimeType;
unsigned long clockRate;
unsigned long channels;
DOMString sdpFmtpLine;
DOMString implementation;
};
payloadType of type unsigned
long
Payload type as used in RTP encoding.
mimeType of type DOMString
The codec MIME media type/subtype. 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.
sdpFmtpLine of type DOMString
The a=fmtp line in the SDP corresponding to the codec, i.e., after the colon following the PT. This defined by [[!JSEP]] in Section 5.7.
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.
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;
double roundTripTime;
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;
};
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.
roundTripTime of type double
Round trip time is present only if isRemote is true.
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]]. If no RTCP Receiver Report is received with a DLSR value
other than 0, the round trip time is left undefined.
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 [[!RFC8015]].
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]].
RTCOutboundRTPStreamStats dictionary represents the measurement metrics for the outgoing RTP stream.
dictionary RTCOutboundRTPStreamStats : RTCRTPStreamStats {
DOMHighResTimeStamp remoteTimestamp;
unsigned long packetsSent;
unsigned long long bytesSent;
double targetBitrate;
unsigned long framesEncoded;
double totalEncodeTime;
};
remoteTimestamp of type DOMHighResTimeStamp
Present if isRemote is true,
remoteTimestamp, of type DOMHighResTimeStamp
[[!HIGHRES-TIME]], represents the remote timestamp at which these statistics were
sent by the remote endpoint. This differs from timestamp, which
represents the time at which the statistics were generated or received by the
local endpoint. The remoteTimestamp, if present, is derived from the
NTP timestamp in an RTCP SR packet, which reflects the remote endpoint's clock.
That clock may not be synchronized with the local clock. The time is relative to
the UNIX epoch (Jan 1, 1970, UTC).
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.
framesEncoded of type long
Only valid for video. It represents the total number of frames successfully encoded for this RTP media stream.
totalEncodeTime of type
double
Total number of seconds that has been spent encoding the framesEncoded frames of this stream. The average encode time can be calculated by dividing this value with framesEncoded. The time it takes to encode one frame is the time passed between feeding the encoder a frame and the encoder returning encoded data for that frame. This does not include any additional time it may take to packetize the resulting data.
The RTCRTPContributingSourceStats dictionary represents
the measurement metrics for a contributing source (CSRC) that is
contributing to an incoming RTP stream. Each contributing source
produces a stream of RTP packets, which are combined by a mixer into
a single stream of RTP packets that is ultimately received by the
WebRTC endpoint. Information about the sources that contributed to
this combined stream may be provided in the CSRC list or [[RFC6465]]
header extension of received RTP packets. The
timestamp of this
stats object is the most recent time an RTP packet the source
contributed to was received and counted by packetsContributedTo.
dictionary RTCRTPContributingSourceStats : RTCStats {
unsigned long contributorSsrc;
DOMString inboundRtpStreamId;
unsigned long packetsContributedTo;
double audioLevel;
};
contributorSsrc of type unsigned long
The SSRC identifier of the contributing source represented by this stats object, as defined by [[!RFC3550]]. It is a 32-bit unsigned integer that appears in the CSRC list of any packets the relevant source contributed to.
inboundRtpStreamId of type DOMString
The ID of the RTCInboundRTPStreamStats
object representing the inbound RTP stream that this
contributing source is contributing to.
packetsContributedTo of type unsigned long
The total number of RTP packets that this contributing source
contributed to. This value is incremented each time a packet
is counted by
RTCInboundRTPStreamStats.packetsReceived,
and the packet's CSRC list (as defined by [[!RFC3550]]
section 5.1) contains the SSRC identifier of this
contributing source, contributorSsrc.
audioLevel of type double
Present if the last received RTP packet that this source
contributed to contained an [[!RFC6465]] mixer-to-client
audio level header extension. The value of
audioLevel is between 0..1 (linear), where 1.0
represents 0 dBov, 0 represents silence, and 0.5 represents
approximately 6 dBSPL change in the sound pressure level from
0 dBov.
The [[!RFC6465]] header extension contains values in the
range 0..127, in units of -dBov, where 127 represents
silence. To convert these values to the linear 0..1 range of
audioLevel, a value of 127 is converted to 0,
and all other values are converted using the equation:
f(rfc6465_level) = 10^(-rfc6465_level/20).
dictionary RTCPeerConnectionStats : RTCStats {
unsigned long dataChannelsOpened;
unsigned long dataChannelsClosed;
unsigned long dataChannelsRequested;
unsigned long dataChannelsAccepted;
};
dataChannelsOpened of type unsigned long
Represents the number of unique DataChannels that have entered the "open" state during their lifetime.
dataChannelsClosed of type unsigned long
Represents the number of unique DataChannels that have left the "open" state during their lifetime (due to being closed by either end or the underlying transport being closed). DataChannels that transition from "connecting" to "closing" or "closed" without ever being "open" are not counted in this number.
dataChannelsRequested of type unsigned long
Represents the number of unique DataChannels returned from a successful createDataChannel() call on the PeerConnection. If the underlying data transport is not established, these may be in the "connecting" state.
dataChannelsAccepted of type unsigned long
Represents the number of unique DataChannels signaled in a "datachannel" event on the PeerConnection.
The total number of open data channels at any time can be calculated as dataChannelsOpened - dataChannelsClosed. This number is always positive.
The sum of dataChannelsRequested and dataChannelsAccepted is always greater than or equal to dataChannelsOpened - the difference is equal to the number of channels that have been requested, but have not reached the "open" state.
dictionary RTCMediaStreamStats : RTCStats {
DOMString streamIdentifier;
sequence<DOMString> trackIds;
};
An RTCMediaStreamTrackStats object represents the stats about one attachment of a MediaStreamTrack 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 an outgoing track is attached twice (via addTransceiver or ReplaceTrack), there will be two RTCMediaStreamTrackStats objects, one for each attachment. They will have the same "trackIdentifier" attribute, but different "id" attributes.
If the track is detached from the PeerConnection (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;
DOMString kind;
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;
};
trackIdentifier of type DOMString
Represents the id property of the track.
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.
kind of type DOMString
Either "audio" or "video". This reflects the "kind"
attribute of the MediaStreamTrack.
frameWidth of type unsigned
long
Only valid for video MediaStreamTracks and represents the width of the last processed video frame for this track. Before the first frame is processed this attribute is missing.
frameHeight of type unsigned
long
Only valid for video MediaStreamTracks and represents the height of the last processed video frame for this track. Before the first frame is processed this attribute is missing.
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. The value is between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.
The "audio level" value defined in [[RFC6464]] and used in the RTCRtpContributingSource.audioLevel of [[WEBRTC]] (defined as 0..127, where 0 represents 0 dBov, 126 represents -126 dBov and 127 represents silence) is obtained by the calculation given in appendix A of [[!RFC6465]]: informally, level = -round(log10(audioLevel) * 20), with audioLevel 0.0 and values above 127 mapped to 127.
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.
dictionary RTCDataChannelStats : RTCStats {
DOMString label;
DOMString protocol;
long datachannelid;
DOMString transportId;
RTCDataChannelState state;
unsigned long messagesSent;
unsigned long long bytesSent;
unsigned long messagesReceived;
unsigned long long bytesReceived;
};
label of type DOMString
protocol of type DOMString
datachannelid of type long
The "id" attribute of the RTCDataChannel object.
transportId of type DOMString
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.
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;
RTCDtlsTransportState dtlsState;
DOMString selectedCandidatePairId;
DOMString localCertificateId;
DOMString remoteCertificateId;
};
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.
dtlsState of type RTCDtlsTransportState
Set to the current value of the "state" attribute of the underlying RTCDtlsTransport.
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.
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;
DOMString relayProtocol;
boolean deleted = false;
};
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.
relayProtocol of type DOMString
It is the protocol used by the endpoint to communicate with the TURN server. This
is only present for local candidates. Valid values for the TURN URL protocol is
one of udp, tcp, or tls.
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.
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;
DOMHighResTimeStamp lastPacketSentTimestamp;
DOMHighResTimeStamp lastPacketReceivedTimestamp;
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 consentRequestsSent;
};
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.
lastPacketSentTimestamp of type DOMHighResTimeStamp
Represents the timestamp at which the last packet was sent on this particular candidate pair.
lastPacketReceivedTimestamp of type DOMHighResTimeStamp
Represents the timestamp at which the last packet was received on this particular candidate pair.
totalRoundTripTime of type double
Represents the sum of all round trip time measurements in seconds since the
beginning of the session, based on STUN connectivity check [[!STUN-PATH-CHAR]]
responses (responsesReceived), including those that reply to requests that are
sent in order to verify consent [[!RFC7675]]. The average round trip time can be
computed from totalRoundTripTime by dividing it by
responsesReceived.
currentRoundTripTime of type double
Represents the latest round trip time measured in seconds, computed from both STUN connectivity checks [[!STUN-PATH-CHAR]], including those that are sent for consent verification [[!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.
Implementations that do not calculate a sender-side estimate MUST leave this
undefined. Additionally, the value MUST be undefined for candidate pairs that
were never used. For pairs in use, the estimate is normally no lower than the
bitrate for the packets sent at lastPacketSentTimestamp, but might
be higher. For candidate pairs that are not currently in use but were used
before, implementations MUST return undefined.
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.
Implementations that do not calculate a receiver-side estimate MUST leave this
undefined. Additionally, the value should be undefined for candidate pairs that
were never used. For pairs in use, the estimate is normally no lower than the
bitrate for the packets received at lastPacketReceivedTimestamp, but
might be higher. For candidate pairs that are not currently in use but were used
before, implementations MUST return undefined.
requestsReceived of type unsigned long long
Represents the total number of connectivity check requests received (including retransmissions). It is impossible for the receiver to tell whether the request was sent in order to check connectivity or check consent, so all connectivity checks requests are counted here.
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. Since we cannot distinguish connectivity check requests and consent requests, all responses are counted.
retransmissionsReceived of type unsigned long long
Represents the total number of connectivity check request retransmissions received. Retransmissions are defined as connectivity check requests with a TRANSACTION_TRANSMIT_COUNTER attribute where the "req" field is larger than 1, as defined in [[!RFC7982]].
retransmissionsSent of type unsigned long long
Represents the total number of connectivity check request retransmissions sent.
consentRequestsSent of type unsigned long long
Represents the total number of consent requests sent.
enum RTCStatsIceCandidatePairState {
"frozen",
"waiting",
"in-progress",
"failed",
"succeeded"
};
| Enumeration description | |
|---|---|
frozen
|
Defined in Section 5.7.4 of [[!RFC5245]]. |
waiting
|
Defined in Section 5.7.4 of [[!RFC5245]]. |
in-progress
|
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]]. |
dictionary RTCCertificateStats : RTCStats {
DOMString fingerprint;
DOMString fingerprintAlgorithm;
DOMString base64Certificate;
DOMString issuerCertificateId;
};
fingerprint of type DOMString
The fingerprint of the certificate. Only use the fingerprint value as defined in Section 5 of [[!RFC4572]].
fingerprintAlgorithm of type DOMString
The hash function used to compute the certificate fingerprint. For instance, "sha-256".
base64Certificate of type DOMString
The DER-encoded base-64 representation of the certifiate.
issuerCertificateId of type DOMString
The issuerCertificateId refers to the stats object that contains the next certificate in the certificate chain. If the current certificate is at the end of the chain (i.e. a self-signed certificate), this will not be set.
partial dictionary RTCIceCandidatePairStats {
double totalRtt;
double currentRtt;
};
totalRtt
This field got renamed to "totalRoundTripTime" in Dec 2016.
currentRtt
This field got renamed to "currentRoundTripTime" in Dec 2016.
The following example code shows the association of remote statistics with local
statistics in a RTCStats dictionary.
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
}
]
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:
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);
}
Some stats identifiers may expose personally identifiable information, for example the IP addresses of the participating endpoints when a TURN relay is not used.
This section will be removed before publication. The entries are in reverse chronological order.
This list does not include infrastructure and minor editorials.
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.