Network Working Group H. Alvestrand Internet-Draft Google Intended status: BCP September 24, 2012 Expires: March 28, 2013 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 28, 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 Alvestrand Expires March 28, 2013 [Page 1] Internet-Draft WebRTC Stats September 2012 (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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. The Registry Procedure . . . . . . . . . . . . . . . . . . . . 3 2.1. Designated Expert Instructions . . . . . . . . . . . . . . 4 3. Variable Groups . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Initial Variables . . . . . . . . . . . . . . . . . . . . . . . 4 4.1. Variables from basic RTCP SR/RR . . . . . . . . . . . . . . 4 4.2. Transport variables . . . . . . . . . . . . . . . . . . . . 5 4.3. ICE variables . . . . . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 8.1. Normative References . . . . . . . . . . . . . . . . . . . 7 8.2. Informative References . . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 Alvestrand Expires March 28, 2013 [Page 2] Internet-Draft WebRTC Stats September 2012 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: o The name to be registered o What item or items the statistic is defined for o Whether it is possible to o Name and Email address of a contact person for the registration o Organization or individuals having the change control Alvestrand Expires March 28, 2013 [Page 3] Internet-Draft WebRTC Stats September 2012 o 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 , 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 .... Alvestrand Expires March 28, 2013 [Page 4] Internet-Draft WebRTC Stats September 2012 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 Alvestrand Expires March 28, 2013 [Page 5] Internet-Draft WebRTC Stats September 2012 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: 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 Alvestrand Expires March 28, 2013 [Page 6] Internet-Draft WebRTC Stats September 2012 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 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. Jacobson, "RTP: A Transport Protocol for Real-Time Applications", STD 64, RFC 3550, July 2003. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols", RFC 5245, April 2010. Alvestrand Expires March 28, 2013 [Page 7] Internet-Draft WebRTC Stats September 2012 8.2. Informative References [I-D.burnett-rtcweb-constraints-registry] Burnett, D., "IANA Registry for RTCWeb Media Constraints", draft-burnett-rtcweb-constraints-registry-01 (work in progress), April 2012. [RFC6390] Clark, A. and B. Claise, "Guidelines for Considering New Performance Metric Development", BCP 170, RFC 6390, October 2011. Author's Address Harald T. Alvestrand Google Kungsbron 2 Stockholm, 11122 Sweden Email: harald@alvestrand.no Alvestrand Expires March 28, 2013 [Page 8]