Script updating gh-pages from fa28fd1. [ci skip]

Author: ID Bot

draft-ietf-quic-qlog-main-schema.html

@@ -1228,7 +1228,7 @@ <h2 id="name-copyright-notice">
                 <p id="section-toc.1-1.7.2.1.1"><a href="#section-7.1" class="auto internal xref">7.1</a>.  <a href="#name-timestamps" class="internal xref">Timestamps</a></p>
 </li>
               <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.7.2.2">
-                <p id="section-toc.1-1.7.2.2.1"><a href="#section-7.2" class="auto internal xref">7.2</a>.  <a href="#name-path" class="internal xref">Path</a></p>
+                <p id="section-toc.1-1.7.2.2.1"><a href="#section-7.2" class="auto internal xref">7.2</a>.  <a href="#name-tuple" class="internal xref">Tuple</a></p>
 </li>
               <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.7.2.3">
                 <p id="section-toc.1-1.7.2.3.1"><a href="#section-7.3" class="auto internal xref">7.3</a>.  <a href="#name-grouping" class="internal xref">Grouping</a></p>
@@ -2086,7 +2086,7 @@ <h2 id="name-abstract-event-class">
     time: float64
     name: text
     data: $ProtocolEventData
-    ? path: PathID
+    ? tuple: TupleID
     ? time_format: TimeFormat
     ? group_id: GroupID
     ? system_info: SystemInformation
@@ -2108,7 +2108,7 @@ <h2 id="name-abstract-event-class">
 the specific values and semantics of common fields, in particular the <code>name</code> and
 <code>data</code> fields. Furthermore, they can optionally add custom fields.<a href="#section-7-4" class="pilcrow">¶</a></p>
 <p id="section-7-5">Each qlog event <span class="bcp14">MAY</span> contain the optional fields: "time_format"
-(<a href="#time-based-fields" class="auto internal xref">Section 7.1</a>), path (<a href="#path-field" class="auto internal xref">Section 7.2</a>) "trigger" (<a href="#trigger-field" class="auto internal xref">Section 8.2.1</a>),
+(<a href="#time-based-fields" class="auto internal xref">Section 7.1</a>), tuple (<a href="#tuple-field" class="auto internal xref">Section 7.2</a>) "trigger" (<a href="#trigger-field" class="auto internal xref">Section 8.2.1</a>),
 and "group_id" (<a href="#group-ids" class="auto internal xref">Section 7.3</a>).<a href="#section-7-5" class="pilcrow">¶</a></p>
 <p id="section-7-6">Multiple events can appear in a Trace or TraceSeq and they might contain fields
 with identical values. It is possible to optimize out this duplication using
@@ -2347,40 +2347,40 @@ <h3 id="name-timestamps">
 </div>
 </section>
 </div>
-<div id="path-field">
+<div id="tuple-field">
 <section id="section-7.2">
-        <h3 id="name-path">
-<a href="#section-7.2" class="section-number selfRef">7.2. </a><a href="#name-path" class="section-name selfRef">Path</a>
+        <h3 id="name-tuple">
+<a href="#section-7.2" class="section-number selfRef">7.2. </a><a href="#name-tuple" class="section-name selfRef">Tuple</a>
         </h3>
-<p id="section-7.2-1">A qlog event can be associated with a single "network path" (usually, but not
-always, identified by a 4-tuple of IP addresses and ports). In many cases, the
-path will be the same for all events in a given trace, and does not need to be
-logged explicitly with each event. In this case, the "path" field can be omitted
-(in which case the default value of "" is assumed) or reflected in
+<p id="section-7.2-1">A qlog event is typically associated with a single network "path", which is
+usually aligned with a four-tuple of IP addresses and ports. In many cases, this
+tuple will be the same for all events in a given trace, and does not need to be
+logged explicitly with each event. In this case, the "tuple" field can be
+omitted (in which case the default value of "" is assumed) or reflected in
 "common_fields" instead (see <a href="#common-fields" class="auto internal xref">Section 7.5</a>).<a href="#section-7.2-1" class="pilcrow">¶</a></p>
 <p id="section-7.2-2">However, in some situations, such as during QUIC's Connection Migration or when
 using Multipath features, it is useful to be able to split events across
-multiple (concurrent) paths.<a href="#section-7.2-2" class="pilcrow">¶</a></p>
+multiple (concurrent) tuples and/or paths.<a href="#section-7.2-2" class="pilcrow">¶</a></p>
 <p id="section-7.2-3">Definition:<a href="#section-7.2-3" class="pilcrow">¶</a></p>
-<span id="name-pathid-definition"></span><div id="path-def">
+<span id="name-tupleid-definition"></span><div id="tuple-def">
 <figure id="figure-21">
           <div class="lang-cddl sourcecode" id="section-7.2-4.1">
 <pre>
-PathID = text .default ""
+TupleID = text .default ""
 </pre>
 </div>
 <figcaption><a href="#figure-21" class="selfRef">Figure 21</a>:
-<a href="#name-pathid-definition" class="selfRef">PathID definition</a>
+<a href="#name-tupleid-definition" class="selfRef">TupleID definition</a>
           </figcaption></figure>
 </div>
-<p id="section-7.2-5">The "path" field is an identifier that is associated with a single network path.
-This document intentionally does not define further how to choose this
-identifier's value per-path or how to potentially log other parameters that can
-be associated with such a path. This is left for other documents. Implementers
-are free to encode path information directly into the PathID or to log
-associated info in a separate event. For example, QUIC has the "path_assigned"
-event to couple the PathID value to a specific path configuration, see
-<span>[<a href="#QLOG-QUIC" class="cite xref">QLOG-QUIC</a>]</span>.<a href="#section-7.2-5" class="pilcrow">¶</a></p>
+<p id="section-7.2-5">The "tuple" field is an identifier that is associated with a single network
+four-tuple. This document intentionally does not define further how to choose
+this identifier's value per-tuple or how to potentially log other parameters
+that can be associated with such a tuple. This is left for other documents.
+Implementers are free to encode tuple information directly into the TupleID or
+to log associated info in a separate event. For example, QUIC has the
+"tuple_assigned" event to couple the TupleID value to a specific tuple
+configuration, see <span>[<a href="#QLOG-QUIC" class="cite xref">QLOG-QUIC</a>]</span>.<a href="#section-7.2-5" class="pilcrow">¶</a></p>
 </section>
 </div>
 <div id="group-ids">
@@ -2394,14 +2394,15 @@ <h3 id="name-grouping">
 might choose to log events for all incoming connections in a single large
 (streamed) qlog file. As such, a method for splitting up events belonging
 to separate logical entities is required.<a href="#section-7.3-1" class="pilcrow">¶</a></p>
-<p id="section-7.3-2">The simplest way to perform this splitting is by associating a "group id"
-to each event that indicates to which conceptual "group" each event belongs. A
+<p id="section-7.3-2">The simplest way to perform this splitting is by associating a "group id" to
+each event that indicates to which conceptual "group" each event belongs. A
 post-processing step can then extract events per group. However, this group
 identifier can be highly protocol and context-specific. In the example above,
-the QUIC "Original Destination Connection ID" could be used to uniquely identify a
-connection. As such, they might add a "ODCID" field to each event. However, a
-middlebox logging IP or TCP traffic might rather use four-tuples to identify
-connections, and add a "four_tuple" field.<a href="#section-7.3-2" class="pilcrow">¶</a></p>
+the QUIC "Original Destination Connection ID" could be used to uniquely identify
+a connection. As such, they might add a "ODCID" field to each event.
+Additionally, a service providing different levels of Quality of Service (QoS)
+to their users might wish to group connections per QoS level applied. They might
+instead prefer a "qos" field.<a href="#section-7.3-2" class="pilcrow">¶</a></p>
 <p id="section-7.3-3">As such, to provide consistency and ease of tooling in cross-protocol and
 cross-context setups, qlog instead defines the common "group_id" field, which
 contains a string value. Implementations are free to use their preferred string
@@ -2418,17 +2419,17 @@ <h3 id="name-grouping">
 <a href="#name-groupid-definition" class="selfRef">GroupID definition</a>
           </figcaption></figure>
 </div>
-<p id="section-7.3-5">JSON serialization example for events grouped by four tuples
-and QUIC connection IDs:<a href="#section-7.3-5" class="pilcrow">¶</a></p>
+<p id="section-7.3-5">JSON serialization example for events grouped either by QUIC Connection IDs, or
+according to an endpoint-specific Quality of Service (QoS) logic that includes
+the service level:<a href="#section-7.3-5" class="pilcrow">¶</a></p>
 <span id="name-groupid-example"></span><div id="group-id-ex">
 <figure id="figure-23">
           <div class="alignLeft art-text artwork" id="section-7.3-6.1">
 <pre>
 "events": [
     {
         "time": 1553986553579,
-        "group_id": "ip1=2001:67c:1232:144:9498:6df6:f450:110b,
-                   ip2=2001:67c:2b0:1c1::198,port1=59105,port2=80",
+        "group_id": "qos=premium",
         "name": "quic:packet_received",
         "data": { ... }
     },
@@ -2446,8 +2447,8 @@ <h3 id="name-grouping">
           </figcaption></figure>
 </div>
 <p id="section-7.3-7">Note that in some contexts (for example a Multipath transport protocol) it might
-make sense to add additional contextual per-event fields (for example PathID,
-see <a href="#path-field" class="auto internal xref">Section 7.2</a>), rather than use the group_id field for that purpose.<a href="#section-7.3-7" class="pilcrow">¶</a></p>
+make sense to add additional contextual per-event fields (for example TupleID,
+see <a href="#tuple-field" class="auto internal xref">Section 7.2</a>), rather than use the group_id field for that purpose.<a href="#section-7.3-7" class="pilcrow">¶</a></p>
 <p id="section-7.3-8">Note also that, typically, a single trace only contains events belonging to a
 single logical group (for example, an individual QUIC connection). As such,
 instead of logging the "group_id" field with an identical value for each event
@@ -2569,7 +2570,7 @@ <h3 id="name-commonfields">
           <div class="lang-cddl sourcecode" id="section-7.5-6.1">
 <pre>
 CommonFields = {
-    ? path: PathID
+    ? tuple: TupleID
     ? time_format: TimeFormat
     ? reference_time: ReferenceTime
     ? group_id: GroupID
@@ -3553,11 +3554,11 @@ <h3 id="name-set-file-output-destination">
 <a href="#section-12.1" class="section-number selfRef">12.1. </a><a href="#name-set-file-output-destination" class="section-name selfRef">Set file output destination via an environment variable</a>
         </h3>
 <p id="section-12.1-1">To provide users control over where and how qlog files are created, two
-environment variables are defined. The first, QLOGFILE, indicates a full path to where an
-individual qlog file should be stored. This path <span class="bcp14">MUST</span> include the full file
-extension. The second, QLOGDIR, sets a general directory path in which qlog files
-should be placed. This path <span class="bcp14">MUST</span> include the directory separator character at the
-end.<a href="#section-12.1-1" class="pilcrow">¶</a></p>
+environment variables are defined. The first, QLOGFILE, indicates a full path to
+where an individual qlog file should be stored. This path <span class="bcp14">MUST</span> include the full
+file extension. The second, QLOGDIR, sets a general directory path in which qlog
+files should be placed. This path <span class="bcp14">MUST</span> include the directory separator character
+at the end.<a href="#section-12.1-1" class="pilcrow">¶</a></p>
 <p id="section-12.1-2">In general, QLOGDIR should be preferred over QLOGFILE if an endpoint is prone to
 generate multiple qlog files. This can for example be the case for a QUIC server
 implementation that logs each QUIC connection in a separate qlog file. An

draft-ietf-quic-qlog-main-schema.txt

@@ -85,7 +85,7 @@ Table of Contents
    6.  VantagePoint
    7.  Abstract Event Class
      7.1.  Timestamps
-     7.2.  Path
+     7.2.  Tuple
      7.3.  Grouping
      7.4.  SystemInformation
      7.5.  CommonFields
@@ -691,7 +691,7 @@ Table of Contents
        time: float64
        name: text
        data: $ProtocolEventData
-       ? path: PathID
+       ? tuple: TupleID
        ? time_format: TimeFormat
        ? group_id: GroupID
        ? system_info: SystemInformation
@@ -712,7 +712,7 @@ Table of Contents
    optionally add custom fields.
 
    Each qlog event MAY contain the optional fields: "time_format"
-   (Section 7.1), path (Section 7.2) "trigger" (Section 8.2.1), and
+   (Section 7.1), tuple (Section 7.2) "trigger" (Section 8.2.1), and
    "group_id" (Section 7.3).
 
    Multiple events can appear in a Trace or TraceSeq and they might
@@ -928,35 +928,35 @@ Table of Contents
 
                       Figure 20: Monotonic timestamps
 
-7.2.  Path
+7.2.  Tuple
 
-   A qlog event can be associated with a single "network path" (usually,
-   but not always, identified by a 4-tuple of IP addresses and ports).
-   In many cases, the path will be the same for all events in a given
+   A qlog event is typically associated with a single network "path",
+   which is usually aligned with a four-tuple of IP addresses and ports.
+   In many cases, this tuple will be the same for all events in a given
    trace, and does not need to be logged explicitly with each event.  In
-   this case, the "path" field can be omitted (in which case the default
-   value of "" is assumed) or reflected in "common_fields" instead (see
-   Section 7.5).
+   this case, the "tuple" field can be omitted (in which case the
+   default value of "" is assumed) or reflected in "common_fields"
+   instead (see Section 7.5).
 
    However, in some situations, such as during QUIC's Connection
    Migration or when using Multipath features, it is useful to be able
-   to split events across multiple (concurrent) paths.
+   to split events across multiple (concurrent) tuples and/or paths.
 
    Definition:
 
-   PathID = text .default ""
+   TupleID = text .default ""
 
-                        Figure 21: PathID definition
+                       Figure 21: TupleID definition
 
-   The "path" field is an identifier that is associated with a single
-   network path.  This document intentionally does not define further
-   how to choose this identifier's value per-path or how to potentially
-   log other parameters that can be associated with such a path.  This
-   is left for other documents.  Implementers are free to encode path
-   information directly into the PathID or to log associated info in a
-   separate event.  For example, QUIC has the "path_assigned" event to
-   couple the PathID value to a specific path configuration, see
-   [QLOG-QUIC].
+   The "tuple" field is an identifier that is associated with a single
+   network four-tuple.  This document intentionally does not define
+   further how to choose this identifier's value per-tuple or how to
+   potentially log other parameters that can be associated with such a
+   tuple.  This is left for other documents.  Implementers are free to
+   encode tuple information directly into the TupleID or to log
+   associated info in a separate event.  For example, QUIC has the
+   "tuple_assigned" event to couple the TupleID value to a specific
+   tuple configuration, see [QLOG-QUIC].
 
 7.3.  Grouping
 
@@ -975,8 +975,9 @@ Table of Contents
    context-specific.  In the example above, the QUIC "Original
    Destination Connection ID" could be used to uniquely identify a
    connection.  As such, they might add a "ODCID" field to each event.
-   However, a middlebox logging IP or TCP traffic might rather use four-
-   tuples to identify connections, and add a "four_tuple" field.
+   Additionally, a service providing different levels of Quality of
+   Service (QoS) to their users might wish to group connections per QoS
+   level applied.  They might instead prefer a "qos" field.
 
    As such, to provide consistency and ease of tooling in cross-protocol
    and cross-context setups, qlog instead defines the common "group_id"
@@ -989,14 +990,14 @@ Table of Contents
 
                        Figure 22: GroupID definition
 
-   JSON serialization example for events grouped by four tuples and QUIC
-   connection IDs:
+   JSON serialization example for events grouped either by QUIC
+   Connection IDs, or according to an endpoint-specific Quality of
+   Service (QoS) logic that includes the service level:
 
    "events": [
        {
            "time": 1553986553579,
-           "group_id": "ip1=2001:67c:1232:144:9498:6df6:f450:110b,
-                      ip2=2001:67c:2b0:1c1::198,port1=59105,port2=80",
+           "group_id": "qos=premium",
            "name": "quic:packet_received",
            "data": { ... }
        },
@@ -1012,7 +1013,7 @@ Table of Contents
 
    Note that in some contexts (for example a Multipath transport
    protocol) it might make sense to add additional contextual per-event
-   fields (for example PathID, see Section 7.2), rather than use the
+   fields (for example TupleID, see Section 7.2), rather than use the
    group_id field for that purpose.
 
    Note also that, typically, a single trace only contains events
@@ -1120,7 +1121,7 @@ Table of Contents
    are shown in the listing below:
 
    CommonFields = {
-       ? path: PathID
+       ? tuple: TupleID
        ? time_format: TimeFormat
        ? reference_time: ReferenceTime
        ? group_id: GroupID