RE: Issue 85: Update Stats

Varun said:

“These aren’t defined as enums any more, are just strings that will be defined in an IANA registry.”

[BA] Thanks for pointing out the change.  Will add this to the list of updates for Issue 85.

The outbound and inbound relate to RtpSender and RtpReceiver objects, respectively.

[BA] That is true for *local* outbound/inbound statistics.  But for remote statistics, isn’t it reversed?  For example, won’t remote outbound statistics (obtained from Sender Reports) be obtained from RtpReceiver objects and remote inbound statistics (obtained from Receiver Reports) be obtained from RtpSender objects?

The local and remote candidates are actually listing attributes and do not really expose any stats. IIUC, the information contained within will be accessible from the corresponding IceCandidate object.

[BA] My assumption is that local candidate reports can be obtained from IceGatherer objects and remote candidate reports from the IceTransport objects.  The objects defined in the Statistics API are slightly different from those in ORTC API.

Session should contain the sequence of peer connections, and datachannels.

[BA] For ORTC there are  no peerConnection objects.


2) maybe it would be better if the enum had a 1 to 1 mapping from the derived struct object name from the base RTCStats to it’s clear the 1:1 relationship between the type and the state.

Names are easy to change, if the WG agrees what to change them to. :)

[BA] The issue isn’t really the names, but understanding what ORTC objects can be interrogated to retrieve what statistics.


3) then it would be clearer in ORTC which structs we would need to use (vs not use) and the type / enum mapping would be many times clearer.

-Robin



On March 10, 2015 at 6:25:38 PM, Bernard Aboba (bernard.aboba@microsoft.com<mailto:bernard.aboba@microsoft.com>) wrote:
The Statistics API document has been updated at http://www.w3.org/TR/webrtc-stats/. Here is a proposed update to Section 13 to sync up with the changes.

  1.  Statistics API
The Statistics API enables retrieval of statistics relating to RTCRtpSender, RTCRtpReceiver, RTCDtlsTransport, RTCIceGatherer, RTCIceTransport and RTCSctpTransport objects. For detailed information on the Statistics API, consult [WEBRTC-STATS].
interface RTCStatsProvider {
Promise getStats ();
};
13.1 Methods
getStats
Gathers stats for the given object and reports the result asynchronously.
When the getStats() method is invoked, the user agent must queue a task to run the following steps:
For RTCDtlsTransport.getStats(), check whether RTCDtlsTransport.start() has been called; if not, throw an InvalidStateError exception. For RTCIceTransport.getStats(), check whether RTCIceTransport.start() has been called; if not, or if RTCIceTransport.stop() has been called, throw an InvalidStateError exception. For RTCRtpSender.getStats(), check whether RTCRtpSender.send(parameters) has been called; if not, or if parameters.encodings[j].active has a value of false, throw an InvalidStateError exception. For RTCRtpReceiver.getStats(), check whether RTCRtpReceiver.receive(parameters) has been called; if not, or if parameters.encodings[j].active has a value of false, throw an InvalidStateError exception.
Return, but continue the following steps in the background.
Start gathering the stats.
When the relevant stats have been gathered, return a new RTCStatsReport object, representing the gathered stats.
No parameters.
Return type: Promise
13.2 RTCStatsReport Object
The getStats() method delivers a successful result in the form of a RTCStatsReport object. A RTCStatsReport object represents a map between strings, identifying the inspected objects (RTCStats.id), and their corresponding RTCStats objects.
An RTCStatsReport may be composed of several RTCStats objects, each reporting stats for one underlying object. One achieves the total for the object by summing over all stats of a certain type; for instance, if an RTCRtpSender object is sending RTP streams involving multiple SSRCs over the network, the RTCStatsReport may contain one RTCStats object per SSRC (which can be distinguished by the value of the ssrc stats attribute).
interface RTCStatsReport {
getter RTCStats (DOMString id);
};
13.2.1 Methods
RTCStats
Getter to retrieve the RTCStats objects that this stats report is composed of.
The set of supported property names [WEBIDL] is defined as the ids of all the RTCStats objects that has been generated for this stats report. The order of the property names is left to the user agent.
Parameter Type Nullable Optional Description
id DOMString ✘✘
Return type: getter
13.3 RTCStats Dictionary
An RTCStats dictionary represents the stats gathered by inspecting a specific object. The RTCStats dictionary is a base type that specifies as set of default attributes, such as timestamp and type. Specific stats are added by extending the RTCStats dictionary.
Note that while stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications must be prepared to deal with unknown stats.
Statistics 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. Thus implementations must return synchronized values for all stats in a RTCStats object.
dictionary RTCStats {
DOMHiResTimeStamp timestamp;
RTCStatsType type;
DOMString id;
};
13.3.1 Dictionary RTCStats Members
id of type DOMString
A unique id that is associated with the object that was inspected to produce this RTCStats object. Two RTCStats objects, extracted from two different RTCStatsReport objects, must have the same id if they were produced by inspecting the same underlying object. User agents are free to pick any format for the id as long as it meets the requirements above.
timestamp of type DOMHiResTimeStamp
The timestamp, of type DOMHiResTimeStamp [HIGHRES-TIME], associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC). The timestamp for local measurements corresponds to the to the local clock and for remote measurements corresponds to the timestamp indicated in the incoming RTCP Sender Report (SR), Receiver Report (RR) or Extended Report (XR).
type of type RTCStatsType
The type of this object.
The type attribute must be initialized to the name of the most specific type this RTCStats dictionary represents.
13.3.2 enum RTCStatsType
enum RTCStatsType {
"inboundrtp",
"outboundrtp",
"session",
"datachannel",
"track",
"transport",
"candidatepair",
"localcandidate",
"remotecandidate"
};
Enumeration description
inboundrtp

Statistics for the inbound RTP stream. It is accessed via the RTCInboundRTPStreamStats defined in [WEBRTC-STATS] Section 4.2.3. Local inbound RTP statistics can be obtained from the RTCRtpReceiver object; remote inbound RTP statistics can be obtained from the RTCRtpSender object.
outboundrtp
Statistics for the outbound RTP stream. It is accessed via the RTCOutboundRTPStreamStats defined in [WEBRTC-STATS] Section 4.2.4. Local outbound RTP statistics can be obtained from the RTCRtpSender object; remote outbound RTP statistics can be obtained from the RTCRtpReceiver object.
session
Statistics relating to RTCDataChannel objects. It is accessed via the RTCPeerConnectionStats defined in [WEBRTC-STATS] Section 4.3.
datachannel
Statistics relating to each RTCDataChannel id. It is accessed via the RTCDataChannelStats defined in [WEBRTC-STATS] Section 4.5.
track

Statistics relating to the MediaStreamTrack object. It is accessed via the RTCMediaStreamTrackStats defined in [WEBRTC-STATS] Section 4.4.2.
transport

Transport statistics related to the RTCDtlsTransport object. It is accessed via the RTCTransportStats and RTCCertificateStats defined in [WEBRTC-STATS] Sections 4.6 and 4.9.
candidatepair

ICE candidate pair statistics related to RTCIceTransport objects. It is accessed via the RTCIceCandidatePairStats defined in [WEBRTC-STATS] Section 4.8.
localcandidate

ICE local candidates, related to RTCIceGatherer objects. It is accessed via the RTCIceCandidateAttributes defined in [WEBRTC-STATS] Section 4.7.
remotecandidate
ICE remote candidate, related to RTCIceTransport objects. It is accessed via the RTCIceCandidateAttributes defined in [WEBRTC-STATS] Section 4.7.
C. References
C.1 Normative references
[WEBRTC-STATS]
Harald Alvestrand; Varun Singh. Identifiers for WebRTC's Statistics API. 06 February 2015 (work in progress). URL: http://www.w3.org/TR/webrtc-stats/