Statistics API - a proposal

One of my work items is to get a media statistics API proposed.
Here's one that Justin and I have been doodling somewhat on - see what you
think.
Apologies for formatting strangenesses, if any.

*A proposal for statistics in WebRTC

Design goals:

   - Well defined metrics: WHAT was measured, WHEN it was measured, BY WHOM
   it was measured.
   - Don’t constrain implementation too much
   - Make stats from remote endpoints available (if already passed in RTCP)
   - Make the stats set extensible - new stats should require a define, not
   a redesign
   - Support the stats currently in use by Hangouts


Proposalinterface PeerConnection {

…. as before
   + void getStats(Function statsHandler, [MediaStreamTrack|Object]?
selector);
   };

The “selector” may be a MediaStreamTrack that is a member of a MediaStream
on the incoming or outgoing streams. The callback reports on all relevant
statistics for that stream.
If the selector is blank or missing, stats for the whole PeerConnection are
reported.
TODO: Evaluate the need for other selectors than MediaStreamTrack.

statsHandler(statsStructure stats)

interface statsStructure {
   Object selector;  // reference to the selection parameter of getStats
  readonly statsReports array [] {
 index enum {‘local’, ‘remote’};
           value statsElements[]; // Array of statsElement
   }
}

interface statsElement {
   readonly attribute long timestamp;
  readonly enum reporter {‘local’, ‘remote’} // Other values TBD.
   readonly Dictionary stats { statName DOMString, statValue
int|bool|float|string }
}

Reasoning:

stats may take time to collect, so let’s not make it synchronous. (They
should be on-system, but might require stuff like calling out to media
processor components to collect).
Stats need to be synchronized with each other in order to yield reasonable
values in computation; for instance, if “bytesSent” and “packetsSent” are
both reported, they both need to be reported over the same interval, so
that “average packet size” can be computed as “bytes / packets” - if the
intervals are different, this will yield errors.

Design principles Stats should be as raw as reasonable. If reporting bytes
sent, report bytes sent, not bytes sent per second. The caller can compute
per second from other info.

Example query for “I get lousy sound, is it packet loss?”?
The sound track is audio track 0 of remote stream 0 of pc1.

pc1.RemoteStreams[0].audioTracks[0].getStats(function(stats) { baseline =
stats });
… wait a byte
pc1.RemoteStreams[0].audioTracks[0].getStats(function(stats) { now = stats;
processStats(); });

processStats = function() {
  // Check that timestamp of “local stats” and “remote stats” are
reasonably consistent.
   packetsSent = now[‘remote’].stats{‘packetsSent’} -
baseline[‘remote’].stats{‘packetsSent’};
  packetsReceived = now[‘local’].stats{‘packetsReceived’} -
             baseline[‘local’].stats{‘packetsReceived’};
  fractionLost = (packetsSent - packetsReceived)  / packetsSent;
   // If fractionLost is > 0.3, we have probably found the culprit.
}

Alternative ways of computing the same thing are imaginable, given that
baseline/now would also contain stats that are based on incoming RTCP
reports (timestamped to that report).

Specific stats to track
adapted from http://go/jmidataNot all of these will necessarily be tracked
in the first version.
As far as possible, the definitions from RFC 3550 and successors should be
used for metrics.

AudioMediaStreamTrack

   - SSRC
   - Send codec in use (string)
   - Bytes sent/received
   - Packets sent/received
   - Fraction lost
   - Packets lost
   - Last Sequence number
   - Jitter
   - RTT
   - Energy level
   - Jitter buffer size (rx)
   - ERL/ERLE


VideoMediaStreamTrack

   - SSRC
   - SSRC groups (for Simulcast grouping etc)
   - Send codec in use
   - Bytes sent/received
   - Packets sent/received
   - Fraction lost
   - Packets lost
   - FIRs sent/received
   - NACKs sent/received
   - Packets retransmitted
   - RTT
   - Video width/height/fps/
   - Video bitrate/target bitrate


PeerConnection

   - Bandwidth Estimation
      - Available send bw
      - Available recv bw
      - Total TX bitrate
      - Total RTX bitrate
   - Connection Info
      - Total bytes sent/received
      - Local candidate
      - Remote candidate




*