idnits 2.17.1 draft-alvestrand-rtcweb-stats-registry-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 24, 2012) is 4232 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5245 (Obsoleted by RFC 8445, RFC 8839) == Outdated reference: A later version (-05) exists of draft-burnett-rtcweb-constraints-registry-01 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Alvestrand 3 Internet-Draft Google 4 Intended status: BCP September 24, 2012 5 Expires: March 28, 2013 7 A Registry for WebRTC statistics identifiers 8 draft-alvestrand-rtcweb-stats-registry-00 10 Abstract 12 This memo describes a registration procedure for statistics 13 identifiers used in the WebRTC Javascript API to access statistical 14 information about a PeerConnection. 16 It also gives some identifiers that will, when approved, form the 17 initial content of this registry. 19 Requirements Language 21 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 22 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 23 document are to be interpreted as described in RFC 2119 [RFC2119]. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on March 28, 2013. 42 Copyright Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. The Registry Procedure . . . . . . . . . . . . . . . . . . . . 3 61 2.1. Designated Expert Instructions . . . . . . . . . . . . . . 4 62 3. Variable Groups . . . . . . . . . . . . . . . . . . . . . . . . 4 63 4. Initial Variables . . . . . . . . . . . . . . . . . . . . . . . 4 64 4.1. Variables from basic RTCP SR/RR . . . . . . . . . . . . . . 4 65 4.2. Transport variables . . . . . . . . . . . . . . . . . . . . 5 66 4.3. ICE variables . . . . . . . . . . . . . . . . . . . . . . . 6 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 69 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 8.1. Normative References . . . . . . . . . . . . . . . . . . . 7 72 8.2. Informative References . . . . . . . . . . . . . . . . . . 8 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 1. Introduction 77 When transmitting media or data via a PeerConnection , there is the 78 need to extract statistics on its performance. 80 These statistics may be as simple as wanting to know how many bytes 81 of data have been delivered, or they may be as sophisiticated as 82 wanting to know the efficiency of an echo canceller on the local 83 device. 85 The W3C specification has designed a very simple API to this 86 statistic, where a call may return all relevant data for a particular 87 MediaStreamTrack, or for the whole PeerConnection, and the data has 88 an uniform structure, consisting of a string identifying the 89 statistic and a simple-typed value. 91 Providers of this API will want to expose both standardized and non- 92 standard statistics over this API. 94 This memo describes the registration procedure for such statistics, 95 and an initial set of registrations that will allow basic performance 96 analysis on PeerConnections. 98 2. The Registry Procedure 100 IANA SHALL create a new name space of "RTCWeb Media Statistics". All 101 maintenance within and additions to the contents of this name space 102 MUST be according to the "Specification Required with Expert Review" 103 registration policy as defined in RFC5226 [RFC5226]. The registry is 104 initially populated with the content of Section 4 of this memo. The 105 registry is defined in the remainder of this section. 107 Each registry entry consists of a Name and a Reference (or list of 108 references). 110 A registration request MUST include the following information: 112 o The name to be registered 114 o What item or items the statistic is defined for 116 o Whether it is possible to 118 o Name and Email address of a contact person for the registration 120 o Organization or individuals having the change control 121 o Reference(s) to the specification(s) defining the statistic 123 2.1. Designated Expert Instructions 125 Statistic names are of unlimited length according to the syntax. 126 However, it is RECOMMENDED that they be no longer than 80 characters 127 in total. This is to keep them reasonable for humans to read and 128 use. 130 The statistic MUST be well enough defined in the specification that 131 it is understandable by implementors and application developers that 132 will use the statistic. The statistic SHOULD NOT duplicate a 133 condition that can be achieved using statistics already defined in 134 the registry. The statistic name SHOULD be appropriate and specific 135 enough for the statistic. 137 Documentation to consider when deciding whether a statistic is well 138 enough defined includes [RFC6390], which gives some considerations 139 when defining metrics for real time media. 141 3. Variable Groups 143 In some cases, there is a need to describe a group of objects 144 reported as a single object. 146 Borrowing a concept from SNMP, we identify those objects using an 147 index suffix in the naming string - so that, for instance, the 148 address associated with the first ICE candidate would be called 149 "RemoteIPAddress.1". 151 4. Initial Variables 153 All of these variables have contact person Harald Alvestrand 154 , and change control rests with the IETF. 156 4.1. Variables from basic RTCP SR/RR 158 This group of variables is well defined on a ReportGroup 159 corresponding to an SSRC. For a remote statistic, the timestamp will 160 correspond to the timestamp from an incoming SR/RR packet; for a 161 local statistic, it refers to the local clock (remembering that it is 162 represented as milliseconds since Jan 1, 1970). 164 Name: SSRC 166 Definition: [RFC3550] section .... 168 Name: SentPacketCount 170 Definition: RFC 3550 section 6.4.1 172 Name: SentOctetCount 174 Definition: RFC 3550 section 6.4.1 176 Name: PacketsLost 178 Definition: RFC 3550 section 6.4.1 180 Name: Jitter 182 Definition: RFC 3550 section 6.4.1 184 Name: ReceivedPacketCount 186 Definition: RFC 2959 (RtpRcvrPackets) 188 Note: Will only be available locally, since it is not an RTCP value. 190 Name: RecevedOctetCount 192 Definition: RFC 2959 (RtpRcvrOctets) 194 A typical report for an outgoing SSRC will look like this: 196 { local: { timestamp: 12345, stats: { SentPacketCount: 44, 197 SentOctetCount: 4700 }}, 199 remote: { timestamp: 12377, stats: { PacketsLost: 3, Jitter: 44 }}} 201 4.2. Transport variables 203 These variables are well defined on a ReportGroup representing a 204 transport association. An RTP session is always a transport 205 association; other things may also be transport associations. 207 Note that the actual IP addresses used may vary over the time of a 208 transport association, and that there is no standardized way of 209 getting data from the remote end, so all variables are local only. 211 Name: SentPackets 213 Name: SentOctets 215 Name: ReceivedPackets 216 Name: ReceivedOctets 218 4.3. ICE variables 220 The tracked objects regarding ICE are candidate pairs. Since these 221 are closely aligned with a transport association, the indexing 222 mechanism is used to keep track of the pairs; thus, each transport 223 has its own checklist. 225 Name: IceLocalType, IceLocalPriority, IceLocalFoundation, 226 IceLocalComponentId, IceLocalRelatedAddr, IceLocalBase, 227 IceLocalIPAddr, IceLocalPort, IceLocalTransport 229 Definition: [RFC5245] section 5.7.1 figure 6 231 Name: 233 QUESTION: Should we use the SDP representation for candidates 234 instead? 236 Name: IceDefault, IceValid, iceNominated, IceState 238 A Transport Association with two IP address pairs may thus report 239 data thus: 241 { local: { timestamp: 12345, stats: { 242 SentPackets: 47, 243 SentOctets: 4444, 244 ReceivedPackets: 33, 245 ReceivedOctets: 2346, 246 IceLocalIPAddr.1: '129.241.1.99', 247 IceRemoteIPAddr.1: '234.978.4.3', 248 IceState.1: Succeeded, 249 IceUsed.1: True 250 IceLocalIPAddr.2: '10.0.0.1', 251 IceRemoteIPAddr.2: '10.0.1.24', 252 IceState.2: Failed, 253 IceUsed.2: False 254 }}} 256 (most ICE data omitted for brevity) 258 5. IANA Considerations 260 This document requests IANA to set up the registry described in 261 chapter Section 2, and populate it with the variables defined in 262 chapter Section 4. 264 6. Security Considerations 266 Some variables exposed by stats may have personally identifiable 267 information, for instance the IP addresses of the remote party when a 268 relay is not used. This warrants careful thinking about when this 269 information is exposed, which may result in guidelines for hiding the 270 information entirely from the end system, or recommending that it not 271 be exposed on the stats interface except under certain conditions. 273 (This section may bear some expansion.) 275 7. Acknowledgements 277 Dan Burnett's document on the constraints registry 278 [I-D.burnett-rtcweb-constraints-registry] served as an inspiration to 279 this memo. 281 Initial feedback from Cullen Jennings and the rest of the WebRTC 282 editors' team was invaluable in getting this out the door. 284 8. References 286 8.1. Normative References 288 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 289 Requirement Levels", BCP 14, RFC 2119, March 1997. 291 [RFC3550] Schulzrinne, H., Casner, S., Frederick, R., and V. 292 Jacobson, "RTP: A Transport Protocol for Real-Time 293 Applications", STD 64, RFC 3550, July 2003. 295 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 296 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 297 May 2008. 299 [RFC5245] Rosenberg, J., "Interactive Connectivity Establishment 300 (ICE): A Protocol for Network Address Translator (NAT) 301 Traversal for Offer/Answer Protocols", RFC 5245, 302 April 2010. 304 8.2. Informative References 306 [I-D.burnett-rtcweb-constraints-registry] 307 Burnett, D., "IANA Registry for RTCWeb Media Constraints", 308 draft-burnett-rtcweb-constraints-registry-01 (work in 309 progress), April 2012. 311 [RFC6390] Clark, A. and B. Claise, "Guidelines for Considering New 312 Performance Metric Development", BCP 170, RFC 6390, 313 October 2011. 315 Author's Address 317 Harald T. Alvestrand 318 Google 319 Kungsbron 2 320 Stockholm, 11122 321 Sweden 323 Email: harald@alvestrand.no