A Registry for WebRTC statistics identifiers
draft-alvestrand-rtcweb-stats-registry-00

Abstract

This memo describes a registration procedure for statistics identifiers used in the WebRTC Javascript API to access statistical information about a PeerConnection.

It also gives some identifiers that will, when approved, form the initial content of this registry.

Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on March 26, 2013.

Copyright Notice

Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http:/⁠/⁠trustee.ietf.org/⁠license-⁠info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. The Registry Procedure
• 2.1. Designated Expert Instructions
• 3. Variable Groups
• 4. Initial Variables
• 4.1. Variables from basic RTCP SR/RR
• 4.2. Transport variables
• 4.3. ICE variables
• 5. IANA Considerations
• 6. Security Considerations
• 7. Acknowledgements
• 8. References
• 8.1. Normative References
• 8.2. Informative References
• Author's Address

1. Introduction

When transmitting media or data via a PeerConnection , there is the need to extract statistics on its performance.

These statistics may be as simple as wanting to know how many bytes of data have been delivered, or they may be as sophisiticated as wanting to know the efficiency of an echo canceller on the local device.

The W3C specification has designed a very simple API to this statistic, where a call may return all relevant data for a particular MediaStreamTrack, or for the whole PeerConnection, and the data has an uniform structure, consisting of a string identifying the statistic and a simple-typed value.

Providers of this API will want to expose both standardized and non-standard statistics over this API.

This memo describes the registration procedure for such statistics, and an initial set of registrations that will allow basic performance analysis on PeerConnections.

2. The Registry Procedure

IANA SHALL create a new name space of "RTCWeb Media Statistics". All maintenance within and additions to the contents of this name space MUST be according to the "Specification Required with Expert Review" registration policy as defined in RFC5226 [RFC5226]. The registry is initially populated with the content of Section 4 of this memo. The registry is defined in the remainder of this section.

Each registry entry consists of a Name and a Reference (or list of references).

A registration request MUST include the following information:

• The name to be registered
• What item or items the statistic is defined for
• Whether it is possible to
• Name and Email address of a contact person for the registration
• Organization or individuals having the change control
• Reference(s) to the specification(s) defining the statistic

2.1. Designated Expert Instructions

Statistic names are of unlimited length according to the syntax. However, it is RECOMMENDED that they be no longer than 80 characters in total. This is to keep them reasonable for humans to read and use.

The statistic MUST be well enough defined in the specification that it is understandable by implementors and application developers that will use the statistic. The statistic SHOULD NOT duplicate a condition that can be achieved using statistics already defined in the registry. The statistic name SHOULD be appropriate and specific enough for the statistic.

Documentation to consider when deciding whether a statistic is well enough defined includes [RFC6390], which gives some considerations when defining metrics for real time media.

3. Variable Groups

In some cases, there is a need to describe a group of objects reported as a single object.

Borrowing a concept from SNMP, we identify those objects using an index suffix in the naming string - so that, for instance, the address associated with the first ICE candidate would be called "RemoteIPAddress.1".

4. Initial Variables

All of these variables have contact person Harald Alvestrand <harald@alvestrand.no>, and change control rests with the IETF.

4.1. Variables from basic RTCP SR/RR

This group of variables is well defined on a ReportGroup corresponding to an SSRC. For a remote statistic, the timestamp will correspond to the timestamp from an incoming SR/RR packet; for a local statistic, it refers to the local clock (remembering that it is represented as milliseconds since Jan 1, 1970).

Name: SSRC

Definition: [RFC3550] section ....

Name: SentPacketCount

Definition: RFC 3550 section 6.4.1

Name: SentOctetCount

Definition: RFC 3550 section 6.4.1

Name: PacketsLost

Definition: RFC 3550 section 6.4.1

Name: Jitter

Definition: RFC 3550 section 6.4.1

Name: ReceivedPacketCount

Definition: RFC 2959 (RtpRcvrPackets)

Note: Will only be available locally, since it is not an RTCP value.

Name: RecevedOctetCount

Definition: RFC 2959 (RtpRcvrOctets)

A typical report for an outgoing SSRC will look like this:

{ local: { timestamp: 12345, stats: { SentPacketCount: 44, SentOctetCount: 4700 }},

remote: { timestamp: 12377, stats: { PacketsLost: 3, Jitter: 44 }}}

4.2. Transport variables

These variables are well defined on a ReportGroup representing a transport association. An RTP session is always a transport association; other things may also be transport associations.

Note that the actual IP addresses used may vary over the time of a transport association, and that there is no standardized way of getting data from the remote end, so all variables are local only.

Name: SentPackets

Name: SentOctets

Name: ReceivedPackets

Name: ReceivedOctets

4.3. ICE variables

The tracked objects regarding ICE are candidate pairs. Since these are closely aligned with a transport association, the indexing mechanism is used to keep track of the pairs; thus, each transport has its own checklist.

Name: IceLocalType, IceLocalPriority, IceLocalFoundation, IceLocalComponentId, IceLocalRelatedAddr, IceLocalBase, IceLocalIPAddr, IceLocalPort, IceLocalTransport

Definition: [RFC5245] section 5.7.1 figure 6

Name: <as above, but Remote>

QUESTION: Should we use the SDP representation for candidates instead?

Name: IceDefault, IceValid, iceNominated, IceState

A Transport Association with two IP address pairs may thus report data thus:

{ local: { timestamp: 12345, stats: {
      SentPackets: 47,
      SentOctets: 4444,
      ReceivedPackets: 33,
      ReceivedOctets: 2346,
      IceLocalIPAddr.1: '129.241.1.99',
      IceRemoteIPAddr.1: '234.978.4.3',
      IceState.1: Succeeded, 
      IceUsed.1: True
      IceLocalIPAddr.2: '10.0.0.1',
      IceRemoteIPAddr.2: '10.0.1.24',
      IceState.2: Failed,
      IceUsed.2: False
}}}

(most ICE data omitted for brevity)

5. IANA Considerations

This document requests IANA to set up the registry described in chapter Section 2, and populate it with the variables defined in chapter Section 4.

6. Security Considerations

Some variables exposed by stats may have personally identifiable information, for instance the IP addresses of the remote party when a relay is not used. This warrants careful thinking about when this information is exposed, which may result in guidelines for hiding the information entirely from the end system, or recommending that it not be exposed on the stats interface except under certain conditions.

(This section may bear some expansion.)

7. Acknowledgements

Dan Burnett's document on the constraints registry [I-D.burnett-rtcweb-constraints-registry] served as an inspiration to this memo.

Initial feedback from Cullen Jennings and the rest of the WebRTC editors' team was invaluable in getting this out the door.

8. References

8.1. Normative References

8.2. Informative References

Author's Address