Internet DRAFT - draft-alvestrand-rtcweb-stats-registry

draft-alvestrand-rtcweb-stats-registry






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
   <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 ....



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: <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



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]