QUIC event definitions for qlog

Each subheading in this section is a qlog event category, while each sub-subheading is a qlog event type. Concretely, for the following two items, we have the category “connectivity” and event type “server_listening”, resulting in a concatenated qlog “name” field value of “connectivity:server_listening”.

Importance: Extra Emitted when the server starts accepting connections. Data:

Note: some QUIC stacks do not handle sockets directly and are thus unable to log IP and/or port information.

Importance: Base Used for both attempting (client-perspective) and accepting (server-perspective) new connections. Note that this event has overlap with connection_state_updated and this is a separate event mainly because of all the additional data that should be logged. Data:

Note: some QUIC stacks do not handle sockets directly and are thus unable to log IP and/or port information.

Importance: Base Used for logging when a connection was closed, typically when an error or timeout occurred. Note that this event has overlap with connectivity:connection_state_updated, as well as the CONNECTION_CLOSE frame. However, in practice, when analyzing large deployments, it can be useful to have a single event representing a connection_closed event, which also includes an additional reason field to provide additional information. Additionally, it is useful to log closures due to timeouts, which are difficult to reflect using the other options. In QUIC there are two main connection-closing error categories: connection and application errors. They have well-defined error codes and semantics. Next to these however, there can be internal errors that occur that may or may not get mapped to the official error codes in implementation-specific ways. As such, multiple error codes can be set on the same event to reflect this.

Triggers: * clean * handshake_timeout * idle_timeout * error // this is called the “immediate close” in the QUIC specification * stateless_reset * version_mismatch * application // for example HTTP/3’s GOAWAY frame

Importance: Base This event is emitted when either party updates their current Connection ID. As this typically happens only sparingly over the course of a connection, this event allows loggers to be more efficient than logging the observed CID with each packet in the .header field of the “packet_sent” or “packet_received” events. This is viewed from the perspective of the one applying the new id. As such, if we receive a new connection id from our peer, we will see the dst_ fields are set. If we update our own connection id (e.g., NEW_CONNECTION_ID frame), we log the src_ fields. Data:

Importance: Base To be emitted when the spin bit changes value. It SHOULD NOT be emitted if the spin bit is set without changing its value. Data:

TODO

Importance: Base This event is used to track progress through QUIC’s complex handshake and connection close procedures. It is intended to provide exhaustive options to log each state individually, but also provides a more basic, simpler set for implementations less interested in tracking each smaller state transition. As such, users should not expect to see -all- these states reflected in all qlogs and implementers should focus on support for the SimpleConnectionState set. Data: ~~~ { old?: ConnectionState | SimpleConnectionState, new: ConnectionState | SimpleConnectionState } enum ConnectionState { attempted, // initial sent/received peer_validated, // peer address validated by: client sent Handshake packet OR client used CONNID chosen by the server. transport-draft-32, section-8.1 handshake_started, early_write, // 1 RTT can be sent, but handshake isn’t done yet handshake_complete, // TLS handshake complete: Finished received and sent. tls-draft-32, section-4.1.1 handshake_confirmed, // HANDSHAKE_DONE sent/received (connection is now “active”, 1RTT can be sent). tls-draft-32, section-4.1.2 closing, draining, // connection_close sent/received closed // draining period done, connection state discarded } enum SimpleConnectionState { attempted, handshake_started, handshake_confirmed, closed } ~~~ These states correspond to the following transitions for both client and server: Client: send initial state = attempted get initial state = validated (not really “needed” at the client, but somewhat useful to indicate progress nonetheless) get first Handshake packet state = handshake_started get Handshake packet containing ServerFinished state = handshake_complete send ClientFinished state = early_write (1RTT can now be sent) get HANDSHAKE_DONE state = handshake_confirmed Server: get initial state = attempted send initial (don’t think this needs a separate state, since some handshake will always be sent in the same flight as this?) send handshake EE, CERT, CV, … state = handshake_started send ServerFinished state = early_write (1RTT can now be sent) get first handshake packet / something using a server-issued CID of min length state = validated get handshake packet containing ClientFinished state = handshake_complete send HANDSHAKE_DONE state = handshake_confirmed connection_state_changed with a new state of “attempted” is the same conceptual event as the connection_started event above from the client’s perspective. Similarly, a state of “closing” or “draining” corresponds to the connection_closed event.

e.g., path_updated TODO: read up on the draft how migration works and whether to best fit this here or in TRANSPORT TODO: integrate https://tools.ietf.org/html/draft-deconinck-quic-multipath-02 For now, infer from other connectivity events and path_challenge/path_response frames

Importance: Base Note: secret_updated would be more correct, but in the draft it’s called KEY_UPDATE, so stick with that for consistency Data:

Triggers: “tls” // (e.g., initial, handshake and 0-RTT keys are generated by TLS) “remote_update” “local_update”

Importance: Base Data:

Triggers: “tls” // (e.g., initial, handshake and 0-RTT keys are dropped implicitly) “remote_update” “local_update”

Importance: Core QUIC endpoints each have their own list of of QUIC versions they support. The client uses the most likely version in their first initial. If the server does support that version, it replies with a version_negotiation packet, containing supported versions. From this, the client selects a version. This event aggregates all this information in a single event type. It also allows logging of supported versions at an endpoint without actual version negotiation needing to happen. Data:

, client_versions?:Array, chosen_version?:bytes } ]]> Intended use: When sending an initial, the client logs this event with client_versions and chosen_version set Upon receiving a client initial with a supported version, the server logs this event with server_versions and chosen_version set Upon receiving a client initial with an unsupported version, the server logs this event with server_versions set and client_versions to the single-element array containing the client’s attempted version. The absence of chosen_version implies no overlap was found. Upon receiving a version negotiation packet from the server, the client logs this event with client_versions set and server_versions to the versions in the version negotiation packet and chosen_version to the version it will use for the next initial packet

Importance: Core QUIC implementations each have their own list of application level protocols and versions thereof they support. The client includes a list of their supported options in its first initial as part of the TLS Application Layer Protocol Negotiation (alpn) extension. If there are common option(s), the server chooses the most optimal one and communicates this back to the client. If not, the connection is closed. Data:

, client_alpns?:Array, chosen_alpn?:string } ]]> Intended use: When sending an initial, the client logs this event with client_alpns set When receiving an initial with a supported alpn, the server logs this event with server_alpns set, client_alpns equalling the client-provided list, and chosen_alpn to the value it will send back to the client. When receiving an initial with an alpn, the client logs this event with chosen_alpn to the received value. Alternatively, a client can choose to not log the first event, but wait for the receipt of the server initial to log this event with both client_alpns and chosen_alpn set.

Importance: Core This event groups settings from several different sources (transport parameters, TLS ciphers, etc.) into a single event. This is done to minimize the amount of events and to decouple conceptual setting impacts from their underlying mechanism for easier high-level reasoning. All these settings are typically set once and never change. However, they are typically set at different times during the connection, so there will typically be several instances of this event with different fields set. Note that some settings have two variations (one set locally, one requested by the remote peer). This is reflected in the “owner” field. As such, this field MUST be correct for all settings included a single event instance. If you need to log settings from two sides, you MUST emit two separate event instances. In the case of connection resumption and 0-RTT, some of the server’s parameters are stored up-front at the client and used for the initial connection startup. They are later updated with the server’s reply. In these cases, utilize the separate parameters_restored event to indicate the initial values, and this event to indicate the updated values, as normal. Data:

Additionally, this event can contain any number of unspecified fields. This is to reflect setting of for example unknown (greased) transport parameters or employed (proprietary) extensions.

Importance: Base When using QUIC 0-RTT, clients are expected to remember and restore the server’s transport parameters from the previous connection. This event is used to indicate which parameters were restored and to which values when utilizing 0-RTT. Note that not all transport parameters should be restored (many are even prohibited from being re-utilized). The ones listed here are the ones expected to be useful for correct 0-RTT usage. Data:

Note that, like parameters_set above, this event can contain any number of unspecified fields to allow for additional/custom parameters.

Importance: Core Data:

, // see appendix for the definitions is_coalesced?:boolean, // default value is false retry_token?:Token, // only if header.packet_type === retry stateless_reset_token?:bytes, // only if header.packet_type === stateless_reset. Is always 128 bits in length. supported_versions:Array, // only if header.packet_type === version_negotiation raw?:RawInfo, datagram_id?:uint32 } ]]> Note: We do not explicitly log the encryption_level or packet_number_space: the header.packet_type specifies this by inference (assuming correct implementation) Triggers: “retransmit_reordered” // draft-23 5.1.1 “retransmit_timeout” // draft-23 5.1.2 “pto_probe” // draft-23 5.3.1 “retransmit_crypto” // draft-19 6.2 “cc_bandwidth_probe” // needed for some CCs to figure out bandwidth allocations when there are no normal sends Note: for more details on “datagram_id”, see . It is only needed when keeping track of packet coalescing.

Importance: Core Data:

, // see appendix for the definitions is_coalesced?:boolean, retry_token?:Token, // only if header.packet_type === retry stateless_reset_token?:bytes, // only if header.packet_type === stateless_reset. Is always 128 bits in length. supported_versions:Array, // only if header.packet_type === version_negotiation raw?:RawInfo, datagram_id?:uint32 } ]]> Note: We do not explicitly log the encryption_level or packet_number_space: the header.packet_type specifies this by inference (assuming correct implementation) Triggers: “keys_available” // if packet was buffered because it couldn’t be decrypted before Note: for more details on “datagram_id”, see . It is only needed when keeping track of packet coalescing.

Importance: Base This event indicates a QUIC-level packet was dropped after partial or no parsing. Data:

For this event, the “trigger” field SHOULD be set (for example to one of the values below), as this helps tremendously in debugging. Triggers: “key_unavailable” “unknown_connection_id” “header_parse_error” “payload_decrypt_error” “protocol_violation” “dos_prevention” “unsupported_version” “unexpected_packet” “unexpected_source_connection_id” “unexpected_version” “duplicate” “invalid_initial” Note: sometimes packets are dropped before they can be associated with a particular connection (e.g., in case of “unsupported_version”). This situation is discussed more in . Note: for more details on “datagram_id”, see . It is only needed when keeping track of packet coalescing.

Importance: Base This event is emitted when a packet is buffered because it cannot be processed yet. Typically, this is because the packet cannot be parsed yet, and thus we only log the full packet contents when it was parsed in a packet_received event. Data:

Note: for more details on “datagram_id”, see . It is only needed when keeping track of packet coalescing. Triggers: “backpressure” // indicates the parser cannot keep up, temporarily buffers packet for later processing “keys_unavailable” // if packet cannot be decrypted because the proper keys were not yet available

Importance: Extra This event is emitted when a (group of) sent packet(s) is acknowledged by the remote peer for the first time. This information could also be deduced from the contents of received ACK frames. However, ACK frames require additional processing logic to determine when a given packet is acknowledged for the first time, as QUIC uses ACK ranges which can include repeated ACKs. Additionally, this event can be used by implementations that do not log frame contents. Data: ~~~ { packet_number_space?:PacketNumberSpace,

} ~~~ ]]> Note: if packet_number_space is omitted, it assumes the default value of PacketNumberSpace.application_data, as this is by far the most prevalent packet number space a typical QUIC connection will use.

Importance: Extra When we pass one or more UDP-level datagrams to the socket. This is useful for determining how QUIC packet buffers are drained to the OS. Data:

, // RawInfo:length field indicates total length of the datagrams, including UDP header length datagram_ids?:Array } ]]> Note: QUIC itself does not have a concept of a “datagram_id”. This field is a purely qlog-specific construct to allow tracking how multiple QUIC packets are coalesced inside of a single UDP datagram, which is an important optimization during the QUIC handshake. For this, implementations assign a (per-endpoint) unique ID to each datagram and keep track of which packets were coalesced into the same datagram. As packet coalescing typically only happens during the handshake (as it requires at least one long header packet), this can be done without much overhead.

Importance: Extra When we receive one or more UDP-level datagrams from the socket. This is useful for determining how datagrams are passed to the user space stack from the OS. Data:

, // RawInfo:length field indicates total length of the datagrams, including UDP header length datagram_ids?:Array } ]]> Note: for more details on “datagram_ids”, see .

Importance: Extra When we drop a UDP-level datagram. This is typically if it does not contain a valid QUIC packet (in that case, use packet_dropped instead). Data:

Importance: Base This event is emitted whenever the internal state of a QUIC stream is updated, as described in QUIC transport draft-23 section 3. Most of this can be inferred from several types of frames going over the wire, but it’s much easier to have explicit signals for these state changes. Data:

Note: QUIC implementations SHOULD mainly log the simplified bidirectional (HTTP/2-alike) stream states (e.g., idle, open, closed) instead of the more finegrained stream states (e.g., data_sent, reset_received). These latter ones are mainly for more in-depth debugging. Tools SHOULD be able to deal with both types equally.

Importance: Extra This event’s main goal is to prevent a large proliferation of specific purpose events (e.g., packets_acknowledged, flow_control_updated, stream_data_received). We want to give implementations the opportunity to (selectively) log this type of signal without having to log packet-level details (e.g., in packet_received). Since for almost all cases, the effects of applying a frame to the internal state of an implementation can be inferred from that frame’s contents, we aggregate these events in this single “frames_processed” event. Note: This event can be used to signal internal state change not resulting directly from the actual “parsing” of a frame (e.g., the frame could have been parsed, data put into a buffer, then later processed, then logged with this event). Note: Implementations logging “packet_received” and which include all of the packet’s constituent frames therein, are not expected to emit this “frames_processed” event. Rather, implementations not wishing to log full packets or that wish to explicitly convey extra information about when frames are processed (if not directly tied to their reception) can use this event. Note: for some events, this approach will lose some information (e.g., for which encryption level are packets being acknowledged?). If this information is important, please use the packet_received event instead. Note: in some implementations, it can be difficult to log frames directly, even when using packet_sent and packet_received events. For these cases, this event also contains the direct packet_number field, which can be used to more explicitly link this event to the packet_sent/received events. Data:

, // see appendix for the definitions packet_number?:uint64 } ]]>

Importance: Base Used to indicate when data moves between the different layers (for example passing from the application protocol (e.g., HTTP) to QUIC stream buffers and vice versa) or between the application protocol (e.g., HTTP) and the actual user application on top (for example a browser engine). This helps make clear the flow of data, how long data remains in various buffers and the overheads introduced by individual layers. For example, this helps make clear whether received data on a QUIC stream is moved to the application protocol immediately (for example per received packet) or in larger batches (for example, all QUIC packets are processed first and afterwards the application layer reads from the streams with newly available data). This in turn can help identify bottlenecks or scheduling problems. Data:

Note: we do not for example use a “direction” field (with values “up” and “down”) to specify the data flow. This is because in some optimized implementations, data might skip some individual layers. Additionally, using explicit “from” and “to” fields is more flexible and allows the definition of other conceptual “layers” (for example to indicate data from QUIC CRYPTO frames being passed to a TLS library (“security”) or from HTTP/3 to QPACK (“qpack”)). Note: this event type is part of the “transport” category, but really spans all the different layers. This means we have a few leaky abstractions here (for example, the stream_id or stream offset might not be available at some logging points, or the raw data might not be in a byte-array form). In these situations, implementers can decide to define new, in-context fields to aid in manual debugging.

Note: most of the events in this category are kept generic to support different recovery approaches and various congestion control algorithms. Tool creators SHOULD make an effort to support and visualize even unknown data in these events (e.g., plot unknown congestion states by name on a timeline visualization).

Importance: Base This event groups initial parameters from both loss detection and congestion control into a single event. All these settings are typically set once and never change. Implementation that do, for some reason, change these parameters during execution, MAY emit the parameters_set event twice. Data:

Additionally, this event can contain any number of unspecified fields to support different recovery approaches.

Importance: Core This event is emitted when one or more of the observable recovery metrics changes value. This event SHOULD group all possible metric updates that happen at or around the same time in a single event (e.g., if min_rtt and smoothed_rtt change at the same time, they should be bundled in a single metrics_updated entry, rather than split out into two). Consequently, a metrics_updated event is only guaranteed to contain at least one of the listed metrics. Data:

Note: to make logging easier, implementations MAY log values even if they are the same as previously reported values (e.g., two subsequent METRIC_UPDATE entries can both report the exact same value for min_rtt). However, applications SHOULD try to log only actual updates to values. Additionally, this event can contain any number of unspecified fields to support different recovery approaches.

Importance: Base This event signifies when the congestion controller enters a significant new state and changes its behaviour. This event’s definition is kept generic to support different Congestion Control algorithms. For example, for the algorithm defined in the Recovery draft (“enhanced” New Reno), the following states are defined: slow_start congestion_avoidance application_limited recovery Data:

The “trigger” field SHOULD be logged if there are multiple ways in which a state change can occur but MAY be omitted if a given state can only be due to a single event occuring (e.g., slow start is exited only when ssthresh is exceeded). Some triggers for (“enhanced” New Reno): persistent_congestion ECN

Importance: Extra This event is emitted when a recovery loss timer changes state. The three main event types are: set: the timer is set with a delta timeout for when it will trigger next expired: when the timer effectively expires after the delta timeout cancelled: when a timer is cancelled (e.g., all outstanding packets are acknowledged, start idle period) Note: to indicate an active timer’s timeout update, a new “set” event is used. Data:

TODO: how about CC algo’s that use multiple timers? How generic do these events need to be? Just support QUIC-style recovery from the spec or broader? TODO: read up on the loss detection logic in draft-27 onward and see if this suffices

Importance: Core This event is emitted when a packet is deemed lost by loss detection. Data:

// see appendix for the definitions } ]]> For this event, the “trigger” field SHOULD be set (for example to one of the values below), as this helps tremendously in debugging. Triggers: “reordering_threshold”, “time_threshold” “pto_expired” // draft-23 section 5.3.1, MAY

Importance: Extra This event indicates which data was marked for retransmit upon detecing a packet loss (see packet_lost). Similar to our reasoning for the “frames_processed” event, in order to keep the amount of different events low, we group this signal for all types of retransmittable data in a single event based on existing QUIC frame definitions. Implementations retransmitting full packets or frames directly can just log the consituent frames of the lost packet here (or do away with this event and use the contents of the packet_lost event instead). Conversely, implementations that have more complex logic (e.g., marking ranges in a stream’s data buffer as in-flight), or that do not track sent frames in full (e.g., only stream offset + length), can translate their internal behaviour into the appropriate frame instance here even if that frame was never or will never be put on the wire. Note: much of this data can be inferred if implementations log packet_sent events (e.g., looking at overlapping stream data offsets and length, one can determine when data was retransmitted). Data:

, // see appendix for the definitions } ]]>