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]
