This document describes an event logging API that can serve as an extension to RTCPeerConnection’s “getStats” API.
The chief goals of this extension are:
Get information about series of events
Allow the user to get information about all events at reasonable overhead
Build an extensible framework for carrying event information
The initial version of this API will be an object that can attach to a MediaStreamTrack (which defines its source) and its destination (since it can have mulitple destinations).
The initial object we record information about is a video frame. Later extensions can encompass audio frames too, with not much change in design.
1.1. Use cases
Imagine a remote control application: There is a control that allows the user to click on the screen locally, which causes changes to happen in the video generated remotely. The app wishes to collect latency information on the time between the click and the user seeing the result.
The click can be timed using existing mechanisms. The click event will then be sent to the remote app, and the remote app will identify the first frame generated after the click, use the recording API to figure out when it was generated (in the local clock), when it was sent out over the network, and what its RTP sequence number was. It returns this information to the local app.
The local app will use the event recording API to record when the frame with the given RTP sequence number arrived, and when it was displayed (in the local clock). It can then measure the click-to-display lag.
It can use the data recorded remotely to figure out if generation and sending took a long time; it can’t absolutely record the network delay between the parties (since the clocks are unsynchronized), but can get some boundaries on what the lag cause could be. This aids very much in locating problem spots.
These dictionaries and enums can be extended at need.
This provides an interface that is:
Designed for discrete event list delivery
Limits the amount of resources that needs to be spent on buffering events
Does not attach to the (possibly designed-out later) PeerConnection object
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
in the normative parts of this document
are to be interpreted as described in RFC 2119.
However, for readability,
these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative
except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example”
or are set apart from the normative text with class="example", like this:
This is an example of an informative example.
Informative notes begin with the word “Note”
and are set apart from the normative text with class="note", like this: