One document matched: draft-alvestrand-rtcweb-stats-registry-00.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="bcp" docName="draft-alvestrand-rtcweb-stats-registry-00"
     ipr="trust200902">
  <front>
    <title abbrev="WebRTC Stats">A Registry for WebRTC statistics
    identifiers</title>

    <author fullname="Harald T. Alvestrand" initials="H. T. "
            surname="Alvestrand">
      <organization>Google</organization>

      <address>
        <postal>
          <street>Kungsbron 2</street>

          <city>Stockholm</city>

          <region></region>

          <code>11122</code>

          <country>Sweden</country>
        </postal>

        <email>harald@alvestrand.no</email>
      </address>
    </author>

    <date day="24" month="September" year="2012" />

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

      <t>It also gives some identifiers that will, when approved, form the
      initial content of this registry.</t>
    </abstract>

    <note title="Requirements Language">
      <t>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 <xref
      target="RFC2119">RFC 2119</xref>.</t>
    </note>
  </front>

  <middle>
    <section title="Introduction">
      <t>When transmitting media or data via a PeerConnection , there is the
      need to extract statistics on its performance.</t>

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

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

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

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

    <section anchor="s-registry" title="The Registry Procedure">
      <t>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 <xref target="RFC5226">RFC5226</xref>.
      The registry is initially populated with the content of <xref
      target="s-defs"></xref> of this memo. The registry is defined in the
      remainder of this section.</t>

      <t>Each registry entry consists of a Name and a Reference (or list of
      references).</t>

      <t>A registration request MUST include the following information:</t>

      <t><list style="symbols">
          <t>The name to be registered</t>

          <t>What item or items the statistic is defined for</t>

          <t>Whether it is possible to </t>

          <t>Name and Email address of a contact person for the
          registration</t>

          <t>Organization or individuals having the change control</t>

          <t>Reference(s) to the specification(s) defining the statistic</t>
        </list></t>

      <section title="Designated Expert Instructions">
        <t>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.</t>

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

        <t>Documentation to consider when deciding whether a statistic is well
        enough defined includes <xref target="RFC6390"></xref>, which gives
        some considerations when defining metrics for real time media.</t>
      </section>
    </section>

    <section title="Variable Groups">
      <t>In some cases, there is a need to describe a group of objects
      reported as a single object.</t>

      <t>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".</t>

      <t></t>
    </section>

    <section anchor="s-defs" title="Initial Variables">
      <t>All of these variables have contact person Harald Alvestrand
      <harald@alvestrand.no>, and change control rests with the
      IETF.</t>

      <t></t>

      <section title="Variables from basic RTCP SR/RR">
        <t>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).</t>

        <t>Name: SSRC</t>

        <t>Definition: <xref target="RFC3550"></xref> section ....</t>

        <t>Name: SentPacketCount</t>

        <t>Definition: RFC 3550 section 6.4.1</t>

        <t>Name: SentOctetCount</t>

        <t>Definition: RFC 3550 section 6.4.1</t>

        <t>Name: PacketsLost</t>

        <t>Definition: RFC 3550 section 6.4.1</t>

        <t>Name: Jitter</t>

        <t>Definition: RFC 3550 section 6.4.1</t>

        <t>Name: ReceivedPacketCount</t>

        <t>Definition: RFC 2959 (RtpRcvrPackets)</t>

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

        <t>Name: RecevedOctetCount</t>

        <t>Definition: RFC 2959 (RtpRcvrOctets)</t>

        <t>A typical report for an outgoing SSRC will look like this:</t>

        <t>{ local: { timestamp: 12345, stats: { SentPacketCount: 44,
        SentOctetCount: 4700 }},</t>

        <t> remote: { timestamp: 12377, stats: { PacketsLost: 3, Jitter: 44
        }}}</t>
      </section>

      <section title="Transport variables">
        <t>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.</t>

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

        <t>Name: SentPackets</t>

        <t>Name: SentOctets</t>

        <t>Name: ReceivedPackets</t>

        <t>Name: ReceivedOctets</t>
      </section>

      <section title="ICE variables">
        <t>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.</t>

        <t>Name: IceLocalType, IceLocalPriority, IceLocalFoundation,
        IceLocalComponentId, IceLocalRelatedAddr, IceLocalBase,
        IceLocalIPAddr, IceLocalPort, IceLocalTransport</t>

        <t>Definition: <xref target="RFC5245"></xref> section 5.7.1 figure
        6</t>

        <t>Name: <as above, but Remote></t>

        <t>QUESTION: Should we use the SDP representation for candidates
        instead?</t>

        <t>Name: IceDefault, IceValid, iceNominated, IceState</t>

        <t>A Transport Association with two IP address pairs may thus report
        data thus:</t>

        <figure>
          <artwork><![CDATA[
{ 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
}}}

]]></artwork>
        </figure>

        <t></t>

        <t>(most ICE data omitted for brevity)</t>
      </section>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document requests IANA to set up the registry described in
      chapter <xref target="s-registry"></xref>, and populate it with the
      variables defined in chapter <xref target="s-defs"></xref>.</t>

      <t></t>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>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.</t>

      <t>(This section may bear some expansion.)</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>Dan Burnett's document on the constraints registry <xref
      target="I-D.burnett-rtcweb-constraints-registry"></xref> served as an
      inspiration to this memo.</t>

      <t>Initial feedback from Cullen Jennings and the rest of the WebRTC
      editors' team was invaluable in getting this out the door.</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include='reference.RFC.3550'?>

      <?rfc include='reference.RFC.5226'?>

      <?rfc include='reference.RFC.5245'?>
    </references>

    <references title="Informative References">
      <?rfc include='reference.RFC.6390'?>

      <?rfc include='reference.I-D.burnett-rtcweb-constraints-registry'?>
    </references>
  </back>
</rfc>