Change occurrences of Path to Tuple (#491)

Author: rmarx

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

@@ -600,7 +600,7 @@ Event = {
     time: float64
     name: text
     data: $ProtocolEventData
-    ? path: PathID
+    ? tuple: TupleID
     ? time_format: TimeFormat
     ? group_id: GroupID
     ? system_info: SystemInformation
@@ -621,7 +621,7 @@ the specific values and semantics of common fields, in particular the `name` and
 `data` fields. Furthermore, they can optionally add custom fields.
 
 Each qlog event MAY contain the optional fields: "time_format"
-({{time-based-fields}}), path ({{path-field}}) "trigger" ({{trigger-field}}),
+({{time-based-fields}}), tuple ({{tuple-field}}) "trigger" ({{trigger-field}}),
 and "group_id" ({{group-ids}}).
 
 Multiple events can appear in a Trace or TraceSeq and they might contain fields
@@ -831,35 +831,35 @@ Example of a monotonic log using the relative_to_epoch format:
 {: #mono-time-ex title="Monotonic timestamps"}
 
 
-## Path {#path-field}
+## Tuple {#tuple-field}
 
-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
+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 {{common-fields}}).
 
 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.
+multiple (concurrent) tuples and/or paths.
 
 Definition:
 
 ~~~ cddl
-PathID = text .default ""
+TupleID = text .default ""
 ~~~
-{: #path-def title="PathID definition"}
+{: #tuple-def title="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}}.
 
 ## Grouping {#group-ids}
 
@@ -870,14 +870,15 @@ 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.
 
-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
+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.
+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.
 
 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
@@ -890,15 +891,15 @@ GroupID = text
 ~~~
 {: #group-id-def title="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": { ... }
     },
@@ -913,8 +914,8 @@ and QUIC connection IDs:
 {: #group-id-ex title="GroupID example"}
 
 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 {{path-field}}), rather than use the group_id field for that purpose.
+make sense to add additional contextual per-event fields (for example TupleID,
+see {{tuple-field}}), rather than use the group_id field for that purpose.
 
 Note also that, typically, a single trace only contains events belonging to a
 single logical group (for example, an individual QUIC connection). As such,
@@ -1023,7 +1024,7 @@ below:
 
 ~~~ cddl
 CommonFields = {
-    ? path: PathID
+    ? tuple: TupleID
     ? time_format: TimeFormat
     ? reference_time: ReferenceTime
     ? group_id: GroupID
@@ -1840,11 +1841,11 @@ steer this generation and access of the results.
 ## Set file output destination via an environment variable
 
 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 MUST include the full file
-extension. The second, QLOGDIR, sets a general directory path in which qlog files
-should be placed. This path MUST include the directory separator character at the
-end.
+environment variables are defined. The first, QLOGFILE, indicates a full path to
+where an individual qlog file should be stored. This path MUST include the full
+file extension. The second, QLOGDIR, sets a general directory path in which qlog
+files should be placed. This path MUST include the directory separator character
+at the end.
 
 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

draft-ietf-quic-qlog-quic-events.md

@@ -122,8 +122,7 @@ in the Concise Data Definition Language {{!CDDL=RFC8610}} and its
 extensions described in {{QLOG-MAIN}}.
 
 The following fields from {{QLOG-MAIN}} are imported and used: name, namespace,
-type, data, group_id, RawInfo, and time-related
-fields.
+type, data, tuple, group_id, RawInfo, and time-related fields.
 
 Events are defined with an importance level as described in {{Section 8.3 of
 QLOG-MAIN}}.
@@ -165,7 +164,7 @@ this specification.
 | quic:connection_id_updated    | Base       | {{quic-connectionidupdated}} |
 | quic:spin_bit_updated         | Base       | {{quic-spinbitupdated}} |
 | quic:connection_state_updated | Base       | {{quic-connectionstateupdated}} |
-| quic:path_assigned            | Base       | {{quic-pathassigned}} |
+| quic:tuple_assigned            | Base      | {{quic-tupleassigned}} |
 | quic:mtu_updated              | Extra      | {{quic-mtuupdated}} |
 | quic:version_information      | Core       | {{quic-versioninformation}} |
 | quic:alpn_information         | Core       | {{quic-alpninformation}} |
@@ -210,7 +209,7 @@ QuicEventData = QUICServerListening /
                 QUICConnectionIDUpdated /
                 QUICSpinBitUpdated /
                 QUICConnectionStateUpdated /
-                QUICPathAssigned /
+                QUICTupleAssigned /
                 QUICMTUUpdated /
                 QUICVersionInformation /
                 QUICALPNInformation /
@@ -287,8 +286,8 @@ importance level.
 
 ~~~ cddl
 QUICConnectionStarted = {
-    local: PathEndpointInfo
-    remote: PathEndpointInfo
+    local: TupleEndpointInfo
+    remote: TupleEndpointInfo
 
     * $$quic-connectionstarted-extension
 }
@@ -489,56 +488,56 @@ implementations are allowed to use other ConnectionState values that adhere more
 closely to their internal logic. Tools SHOULD be able to deal with these custom
 states in a similar way to the pre-defined states in this document.
 
-## path_assigned {#quic-pathassigned}
+## tuple_assigned {#quic-tupleassigned}
 Importance: Base
 
-This event is used to associate a single PathID's value with other parameters
-that describe a unique network path.
+This event is used to associate a single TupleID's value with other parameters
+that describe a unique network tuple.
 
 As described in {{QLOG-MAIN}}, each qlog event can be linked to a single network
-path by means of the top-level "path" field, whose value is a PathID. However,
-since it can be cumbersome to encode additional path metadata (such as IP
-addresses or Connection IDs) directly into the PathID, this event allows such an
-association to happen separately. As such, PathIDs can be short and unique, and
+tuple by means of the top-level "tuple" field, whose value is a TupleID. However,
+since it can be cumbersome to encode additional tuple metadata (such as IP
+addresses or Connection IDs) directly into the TupleID, this event allows such an
+association to happen separately. As such, TupleIDs can be short and unique, and
 can even be updated to be associated with new metadata as the connection's state
 evolves.
 
 Definition:
 
 ~~~ cddl
-QUICPathAssigned = {
-    path_id: PathID
+QUICTupleAssigned = {
+    tuple_id: TupleID
 
     ; the information for traffic going towards the remote receiver
-    ? path_remote: PathEndpointInfo
+    ? tuple_remote: TupleEndpointInfo
 
     ; the information for traffic coming in at the local endpoint
-    ? path_local: PathEndpointInfo
+    ? tuple_local: TupleEndpointInfo
 
-    * $$quic-pathassigned-extension
+    * $$quic-tupleassigned-extension
 }
 ~~~
-{: #quic-pathassigned-def title="QUICPathAssigned definition"}
+{: #quic-tupleassigned-def title="QUICTupleAssigned definition"}
 
-Choosing the different `path_id` values is left up to the implementation. Some
+Choosing the different `tuple_id` values is left up to the implementation. Some
 options include using a uniquely incrementing integer, using the (first)
-Destination Connection ID associated with a path (or its sequence number), or
+Destination Connection ID associated with a tuple (or its sequence number), or
 using (a hash of) the two endpoint IP addresses.
 
-It is important to note that the empty string ("") is a valid PathID and that it
-is the default assigned to events that do not explicitly set a "path" field. Put
-differently, the initial path of a QUIC connection on which the handshake occurs
-(see also {{quic-connectionstarted}}) is implicitly associated with the PathID
-with value "". Associating metadata with this default path is possible by
-logging the QUICPathAssigned event with a value of "" for the `path_id` field.
-
-As paths and their metadata can evolve over time, multiple QUICPathAssigned
-events can be emitted for each unique PathID. The latest event contains the most
-up-to-date information for that PathID. As such, the first time a PathID is seen
-in a QUICPathAssigned event, it is an indication that the path is
-created. Subsequent occurrences indicate the path is updated, while a final
-occurrence with both `path_local` and `path_remote` fields omitted implicitly
-indicates the path has been abandoned.
+It is important to note that the empty string ("") is a valid TupleID and that
+it is the default assigned to events that do not explicitly set a "tuple" field.
+Put differently, the initial tuple of a QUIC connection on which the handshake
+occurs (see also {{quic-connectionstarted}}) is implicitly associated with the
+TupleID with value "". Associating metadata with this default tuple is possible by
+logging the QUICTupleAssigned event with a value of "" for the `tuple_id` field.
+
+As the usage of TupleIDs and their metadata can evolve over time, multiple
+QUICTupleAssigned events can be emitted for each unique TupleID. The latest
+event contains the most up-to-date information for that TupleID. As such, the
+first time a TupleID is seen in a QUICTupleAssigned event, it is an indication
+that the TupleID is created. Subsequent occurrences indicate the TupleID is
+updated, while a final occurrence with both `tuple_local` and `tuple_remote`
+fields omitted implicitly indicates the TupleID has been abandoned.
 
 ## mtu_updated {#quic-mtuupdated}
 
@@ -1359,7 +1358,7 @@ QUICDatagramDataBlockedUpdated = {
 Use to provide additional information when attempting (client-side) connection
 migration. While most details of the QUIC connection migration process can be
 inferred by observing the PATH_CHALLENGE and PATH_RESPONSE frames, in
-combination with the QUICPathAssigned event, it can be useful to explicitly log
+combination with the QUICTupleAssigned event, it can be useful to explicitly log
 the progression of the migration and potentially made decisions in a single
 location/event. The event has Extra importance level.
 
@@ -1368,7 +1367,7 @@ phase (which is not always needed/present), and a migration phase (which can be
 abandoned upon error).
 
 Implementations that log per-path information in a QUICMigrationStateUpdated,
-SHOULD also emit QUICPathAssigned events, to serve as a ground-truth source of
+SHOULD also emit QUICTupleAssigned events, to serve as a ground-truth source of
 information.
 
 Definition:
@@ -1378,13 +1377,13 @@ QUICMigrationStateUpdated = {
     ? old: MigrationState
     new: MigrationState
 
-    ? path_id: PathID
+    ? tuple_id: TupleID
 
     ; the information for traffic going towards the remote receiver
-    ? path_remote: PathEndpointInfo
+    ? tuple_remote: TupleEndpointInfo
 
     ; the information for traffic coming in at the local endpoint
-    ? path_local: PathEndpointInfo
+    ? tuple_local: TupleEndpointInfo
 
     * $$quic-migrationstateupdated-extension
 }
@@ -1785,33 +1784,33 @@ IPAddress = text /
 ~~~
 {: #ipaddress-def title="IPAddress definition"}
 
-## PathEndpointInfo
+## TupleEndpointInfo
 
-PathEndpointInfo indicates a single half/direction of a path. A full path is
-comprised of two halves. Firstly: the server sends to the remote client IP
+TupleEndpointInfo indicates a single half/direction of a four-tuple. A full tuple
+is comprised of two halves. Firstly: the server sends to the remote client IP
 + port using a specific destination Connection ID. Secondly: the client sends to
 the remote server IP + port using a different destination Connection ID.
 
-As such, structures logging path information SHOULD include two different
-PathEndpointInfo instances, one for each half of the path.
+As such, structures logging tuple information SHOULD include two different
+TupleEndpointInfo instances, one for each half of the tuple.
 
 ~~~ cddl
-PathEndpointInfo = {
+TupleEndpointInfo = {
     ? ip_v4: IPAddress
     ? port_v4: uint16
     ? ip_v6: IPAddress
     ? port_v6: uint16
 
     ; Even though usually only a single ConnectionID
-    ; is associated with a given path at a time,
+    ; is associated with a given tuple/path at a time,
     ; there are situations where there can be an overlap
     ; or a need to keep track of previous ConnectionIDs
     ? connection_ids: [+ ConnectionID]
 
-    * $$quic-pathendpointinfo-extension
+    * $$quic-tupleendpointinfo-extension
 }
 ~~~
-{: #pathendpointinfo-def title="PathEndpointInfo definition"}
+{: #tupleendpointinfo-def title="TupleEndpointInfo definition"}
 
 ## PacketType
 
@@ -2428,7 +2427,7 @@ Event Types
   connection_id_updated,
   spin_bit_updated,
   connection_state_updated,
-  path_assigned,
+  tuple_assigned,
   mtu_updated,
   version_information,
   alpn_information,