Stats

OBSOLETE

This Wiki page has been superseded by a real document.

The new document is here:

http://w3c.github.io/webrtc-stats/

WebRTC Statistics - version 3

This document supersedes:

It assumes the stats API that is defined here (per May 8):

http://dev.w3.org/2011/webrtc/editor/webrtc.html#statistics-model

General conventions:

long is preferred. int is not used. (general WebIDL advice)
double is preferred. float is not used. (general WebIDL advice)
long long is used where the value might overflow a 32-bit integer.
All stats objects have WebIDL names starting with "RTC" and ending in "Stats".
All counters start at zero, and are never reset.
If an implementation does not report an object, it's omitted from the dictionary. Placeholders like -1 are not used. 0 means that the count is zero, and will be incremented if it's non-zero.

RTCStatsType enum

In the webrtc document, the RTCStatsType enum is defined.

It is redefined here to use lowercasenospacesordashes name convention, and has some more values.

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

Root of hierarchy:

dictionary RTCStats {
    DOMHighResTimeStamp timestamp;
    RTCStatsType      type;
    DOMString         id;
};

Global stats for a PeerConnection

Type is "session".

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

SSRCs

All SSRCs:


dictionary RTCRTPStreamStats : RTCStats {
    DOMString ssrc;
    DOMString remoteId;
    boolean isRemote = false;
    DOMString mediaTrackId;
    DOMString transportId;
    DOMString codecId;
    // Stuff valid for video - these are sent by receiver, received by sender.
    unsigned long firCount;  // Defined in RFC 5104 section 4.3.1
         // We are not counting the FIR defined in RFC 2032 section 5.2.1, deprecated in RFC 4587
    unsigned long pliCount;  // Defined in RFC 4585 section 6.3.1
    unsigned long nackCount;  // Defined in RFC 4585 section 6.2.1
    unsigned long sliCount;  // Defined in RFC 4585 section 6.3.2
};

Note the convention that names ending in “Id” are identifiers of other stats objects.

Directed SSRCs - type inboundrtp and outboundrtp:


dictionary RTCInboundRTPStreamStats : RTCRTPStreamStats {
    unsigned long packetsReceived;
    unsigned long long bytesReceived;
    unsigned long packetsLost;
    double jitter;  // Calculated as in RFC 3550 section 6.4.1, but given in seconds.
};

dictionary RTCOutboundRTPStreamStats : RTCRTPStreamStats {
    unsigned long packetsSent;
    unsigned long long bytesSent;
    double targetBitrate;  // Presently configured bitrate target of this SSRC, in bits per second.
                           // Typically this is a configuration parameter of the codec's encoder.
    double roundTripTime;  // Estimated round trip time (seconds) based on RTCP timestamp.
                           // Calculation is given in RFC 3550 section 6.4.1.
};

Representing MediaStreamTracks and Streams


dictionary RTCMediaStreamTrackStats : RTCStats {
   DOMString trackIdentifier;  // track.id property
   boolean remoteSource;
   sequence<DOMString> ssrcIds;
   // Only makes sense for video
   unsigned long frameWidth;
   unsigned long frameHeight;
   double framesPerSecond;  // The nominal FPS value
   unsigned long framesSent;
   unsigned long framesReceived;  // Only makes sense for remoteSource=true
   unsigned long framesDecoded;
   unsigned long framesDropped;  // Same definition as droppedVideoFrames in media-source VideoPlaybackQuality
   unsigned long framesCorrupted;  // As above.
   // Stuff that makes sense for audio
   double audioLevel;  // Value 0..1, linear, with 1.0 = 0 dBov as defined in RFC 6464.
   // Stuff that makes sense if an echo canceller is present and computes these values.
   // Only present on audio tracks sourced from a microphone where echo cancellation is applied.
   double echoReturnLoss;  // as defined in G.168 (2012) section 3.14, in decibels
   double echoReturnLossEnhancement  // as above, section 3.15
};

dictionary RTCMediaStreamStats : RTCStats {
   DOMString streamIdentifier; // stream.id property
   sequence<DOMString> trackIds;  // Note: This is the id of the stats object, not the track.id
};

DataChannels

dictionary RTCDataChannelStats : RTCStats {
   DOMString label;
   DOMString protocol;
   long datachannelid;  // the "id" attribute of the RTCDataChannel object
   RTCDataChannelState state;
   unsigned long long bytesSent;
   unsigned long long bytesReceived;
   unsigned long messagesSent;  // Number of API "message" events
   unsigned long messagesReceived;
}

Representing transports


// A Transport carries a part of an SDP session, consisting of RTP and RTCP.
// When Bundle is in use, an SDP session will have only one Transport per Bundle group.
// When Bundle is not in use, there is one Transport per m-line.
dictionary RTCTransportStats: RTCStats {
    unsigned long long bytesSent;
    unsigned long long bytesReceived;
    // 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.
    DOMString rtcpTransportStatsId;
    boolean activeConnection;
    DOMString selectedCandidatePairId;
    // For components where DTLS is negotiated, give certificates.
    DOMString localCertificateId;
    DOMString remoteCertificateId;
};

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

dictionary RTCIceCandidatePairStats : RTCStats {
    DOMString transportId;
    DOMString localCandidateId;
    DOMString remoteCandidateId;
    RTCStatsIceCandidatePairState state;
    unsigned long long priority;  // Calculated from candidate priorities.
    boolean nominated;
    boolean writable;  // Has gotten ACK to an ICE request
    boolean readable;  // Has gotten a valid incoming ICE request
    unsigned long long bytesSent;
    unsigned long long bytesReceived;
    double roundTripTime;
    double availableOutgoingBitrate;  // Bits per second, implementation dependent computation.
    double availableIncomingBitrate;
}

enum RTCStatsIceCandidateType {
 "host",
 "serverreflexive",
 "peerreflexive",
 "relayed"
};

// This definition of "RTCIceCandidate" reflects the properties of a "candidate" in
// https://tools.ietf.org/html/rfc5245#section-15.1

dictionary RTCIceCandidate : RTCStats {
    DOMString ipAddress;
    long portNumber;
    DOMString transport;  // "tcp" or "udp"
    RTCStatsIceCandidateType candidateType;
    long priority;
    DOMString addressSourceUrl;  // Which URL in RTCIceServers sourced this address, if TURN or STUN
    // More ICE-related info goes here.
}

dictionary RTCCodec : RTCStats {
    unsigned long payloadType;  // As used in RTP encoding.
    DOMString codec;  // video/vp8 or equivalent
    unsigned long clockRate;
    unsigned long channels;  // 2 for stereo, missing for most other cases.
    DOMString parameters;  // From SDP description line
}

Representing certificates

Certificates are given in a form intended to be useful for verification that the chain is complete. The "issuerCertificateId" gives the stats ID of the issuer certificate, allowing one to follow the certificate chain without decoding the certificate.

dictionary RTCCertificateStats : RTCStats {
    DOMString fingerprint;  // As defined in RFC 4572 section 5 - the fingerprint value only
    DOMString fingerprintAlgorithm;  // For instance "sha-256"
    DOMString base64Certificate;  // DER-encoded, base-64 representation of certifiate
    DOMString issuerCertificateId;
}