]> Akamai

rmarx@akamai.com

Meta

lniccolini@meta.com

martenseemann@gmail.com

Cloudflare

lucas@lucaspardue.com

Transport QUIC Internet-Draft This document describes a qlog event schema containing concrete qlog event definitions and their metadata for the core QUIC protocol and selected extensions. Note to Readers

• Note to RFC editor: Please remove this section before publication.

Feedback and discussion are welcome at https://github.com/quicwg/qlog. Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document.

Introduction This document defines a qlog event schema () containing concrete events for the core QUIC protocol (see , , and ) and some of its extensions (see and ). The event namespace with identifier quic is defined; see . In this namespace multiple events derive from the qlog abstract Event class (), each extending the "data" field and defining their "name" field values and semantics. Some event data fields use complex data types. These are represented as enums or re-usable definitions, which are grouped together on the bottom of this document for clarity.

Use of group IDs When the qlog group_id field is used, it is recommended to use QUIC's Original Destination Connection ID (ODCID, the CID chosen by the client when first contacting the server), as this is the only value that does not change over the course of the connection and can be used to link more advanced QUIC packets (e.g., Retry, Version Negotiation) to a given connection. Similarly, the ODCID should be used as the qlog filename or file identifier, potentially suffixed by the vantagepoint type (For example, abcd1234_server.qlog would contain the server-side trace of the connection with ODCID abcd1234).

Raw packet and frame information QUIC packets always include an AEAD authentication tag at the end. In general, the length of the AEAD tag depends on the TLS cipher suite, although all cipher suites used in QUIC v1 use a 16 byte tag. For the purposes of calculating the lengths in fields of type RawInfo (as defined in ) related to QUIC packets, the AEAD tag is regarded as a trailer with a fixed size of 16 bytes.

Events not belonging to a single connection A single qlog event trace is typically associated with a single QUIC connection. However, for several types of events (for example, a event with trigger value of connection_unknown), it can be impossible to tie them to a specific QUIC connection, especially on the server. There are various ways to handle these events, each making certain tradeoffs between file size overhead, flexibility, ease of use, or ease of implementation. Some options include:

• Log them in a separate endpoint-wide trace (or use a special group_id value) not associated with a single connection.
• Log them in the most recently used trace.
• Use additional heuristics for connection identification (for example use the four-tuple in addition to the Connection ID).
• Buffer events until they can be assigned to a connection (for example for version negotiation and retry events).

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The event and data structure definitions in this document are expressed in the Concise Data Definition Language and its extensions described in . The following fields from are imported and used: name, namespace, type, data, tuple, group_id, RawInfo, and time-related fields. Events are defined with an importance level as described in . As is the case for , the qlog schema definitions in this document are intentionally agnostic to serialization formats. The choice of format is an implementation decision.

Event Schema Definition This document describes how the core QUIC protocol and selected extensions can be expressed in qlog using a newly defined event schema. Per the requirements in , this document registers the quic namespace. The event schema URI is urn:ietf:params:qlog:events:quic.

Draft Event Schema Identification Only implementations of the final, published RFC can use the events belonging to the event schema with the URI urn:ietf:params:qlog:events:quic. Until such an RFC exists, implementations MUST NOT identify themselves using this URI. Implementations of draft versions of the event schema MUST append the string "-" and the corresponding draft number to the URI. For example, draft 07 of this document is identified using the URI urn:ietf:params:qlog:events:quic-07. The namespace identifier itself is not affected by this requirement.

QUIC Event Overview summarizes the name value of each event type that is defined in this specification. QUIC Events

Name value	Importance	Definition
quic:server_listening	Extra
quic:connection_started	Base
quic:connection_closed	Base
quic:connection_id_updated	Base
quic:spin_bit_updated	Base
quic:connection_state_updated	Base
quic:tuple_assigned	Base
quic:mtu_updated	Extra
quic:version_information	Core
quic:alpn_information	Core
quic:parameters_set	Core
quic:parameters_restored	Base
quic:packet_sent	Core
quic:packet_received	Core
quic:packet_dropped	Base
quic:packet_buffered	Base
quic:packets_acked	Extra
quic:udp_datagrams_sent	Extra
quic:udp_datagrams_received	Extra
quic:udp_datagram_dropped	Extra
quic:stream_state_updated	Base
quic:frames_created	Extra
quic:frames_parsed	Extra
quic:frames_processed	Extra
quic:stream_data_moved	Base
quic:datagram_data_moved	Base
quic:connection_data_blocked_updated	Extra
quic:stream_data_blocked_updated	Extra
quic:datagram_data_blocked_updated	Extra
quic:migration_state_updated	Extra
quic:timer_updated	Extra
quic:key_updated	Base
quic:key_discarded	Base
quic:recovery_parameters_set	Base
quic:recovery_metrics_updated	Core
quic:congestion_state_updated	Base
quic:packet_lost	Core
quic:marked_for_retransmit	Extra
quic:ecn_state_updated	Extra

QUIC events extend the $ProtocolEventData extension point defined in . Additionally, they allow for direct extensibility by their use of per-event extension points via the $$ CDDL "group socket" syntax, as also described in .

QuicEventData definition and ProtocolEventData extension

The concrete QUIC event types are further defined below, their type identifier is the heading name. The subdivisions in sections on Connectivity, Security, Transport and Recovery are purely for readability.

Connectivity events

server_listening Emitted when the server starts accepting connections. It has Extra importance level.

QUICServerListening definition

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

connection_started The connection_started event is used for both attempting (client-perspective) and accepting (server-perspective) new connections. Note that while there is overlap with the connection_state_updated event, this is a separate event in order to capture additional data that can be useful to log. It has Base importance level.

QUICConnectionStarted definition

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

connection_closed The connection_closed event is used for logging when a connection was closed, typically when an error or timeout occurred. It has Base importance level. Note that this event has overlap with the connection_state_updated event, 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 more information. Furthermore, it is useful to log closures due to timeouts or explicit application actions (such as racing multiple connections and aborting the slowest), which are difficult to reflect using the other options. The connection_closed event is intended to be logged either when the local endpoint silently discards the connection due to an idle timeout, when a CONNECTION_CLOSE frame is sent (the connection enters the 'closing' state on the sender side), when a CONNECTION_CLOSE frame is received (the connection enters the 'draining' state on the receiver side) or when a Stateless Reset packet is received (the connection is discarded at the receiver side). Connectivity-related updates after this point (e.g., exiting a 'closing' or 'draining' state), should be logged using the connection_state_updated event instead. 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, and more fine-grained internal error codes can be reflected in the internal_code field. If the error code does not map to a known error string, the connection_error or application_error value of "unknown" type can be used and the raw value captured in the error_code field; a numerical value without variable-length integer encoding.

QUICConnectionClosed definition

Loggers SHOULD use the most descriptive trigger for a connection_closed event that they are able to deduce. This is often clear at the peer closing the connection (and sending the CONNECTION_CLOSE), but can sometimes be more opaque at the receiving end.

connection_id_updated The connection_id_updated event is emitted when either party updates their current Connection ID. As this typically happens only sparingly over the course of a connection, using this event is more efficient than logging the observed CID with each and every packet_sent or packet_received events. It has Base importance level. The connection_id_updated event is viewed from the perspective of the endpoint applying the new ID. As such, when the endpoint receives a new connection ID from the peer, the initiator field will be "remote". When the endpoint updates its own connection ID, the initiator field will be "local".

QUICConnectionIDUpdated definition

spin_bit_updated The spin_bit_updated event conveys information about the QUIC latency spin bit; see . The event is emitted when the spin bit changes value, it SHOULD NOT be emitted if the spin bit is set without changing its value. It has Base importance level.

QUICSpinBitUpdated definition

connection_state_updated The connection_state_updated event is used to track progress through QUIC's complex handshake and connection close procedures. It has Base importance level. does not contain an exhaustive flow diagram with possible connection states nor their transitions (though some are explicitly mentioned, like the 'closing' and 'draining' states). As such, this document non-exhaustively defines those states that are most likely to be useful for debugging QUIC connections. QUIC implementations SHOULD mainly log the simplified BaseConnectionStates, adding the more fine-grained GranularConnectionStates when more in-depth debugging is required. Tools SHOULD be able to deal with both types equally.

QUICConnectionStateUpdated definition

The connection_state_updated event has some overlap with the connection_closed and connection_started events, and the handling of various frames (for example in a packet_received event). Still, it can be useful to log these logical state transitions separately, especially if they map to an internal implementation state machine, to explicitly track progress. As such, 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.

tuple_assigned This event is used to associate a single TupleID's value with other parameters that describe a unique network tuple. It has Base importance level. As described in , each qlog event can be linked to a single network 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:

QUICTupleAssigned definition

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 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 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 ) 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 The mtu_updated event indicates that the estimated Path MTU was updated. This happens as part of the Path MTU discovery process. It has Extra importance level.

QUICMTUUpdated definition

Transport events

version_information The version_information event supports QUIC version negotiation; see . It has Core importance level. QUIC endpoints each have their own list of QUIC versions they support. The client uses the most likely version in their first initial. If the server does not support that version, it replies with a Version Negotiation packet, which contains its supported versions. From this, the client selects a version. The version_information 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.

QUICVersionInformation definition

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. If the client receives a set of server_versions with no viable overlap with its own supported versions, this event should be logged without the chosen_version set

alpn_information The alpn_information event supports Application-Layer Protocol Negotiation (ALPN) over the QUIC transport; see and . It has Core importance level. QUIC endpoints are configured with a list of supported ALPN identifiers. Clients send the list in a TLS ClientHello, and servers match against their list. On success, a single ALPN identifier is chosen and sent back in a TLS ServerHello. If no match is found, the connection is closed. ALPN identifiers are byte sequences that may be presentable as UTF-8. The ALPNIdentifier type supports either format. Implementations SHOULD log at least one format, but MAY log both or none.

QUICALPNInformation definition

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.

parameters_set The parameters_set 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. The event has Core importance level. Most of these settings are typically set once and never change. However, they are usually set at different times during the connection, so there will regularly 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 initiator field. As such, this field MUST be correct for all settings included in a single event instance. If the settings from two sides are required, they MUST be logged as two separate event instances. If the local peer decides to change its behavior based on remote peer's settings, a new event type can be used to reflect the outcome. By default, each setting is assumed to either be absent (has an undefined value) or have its default value (if it exists) at the start of the connection. Subsequently, each setting's value in a parameters_set event supersedes the previous value of that parameter if present. If a setting does not appear in a given parameters_set event, its value is unchanged. Implementations are not required to recognize, process or support every setting/parameter received in all situations. For example, QUIC implementations MUST discard transport parameters that they do not understand . The unknown_parameters field can be used to log the raw values of any unknown parameters (e.g., GREASE, private extensions, peer-side experimentation). 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.

QUICParametersSet definition

parameters_restored When using QUIC 0-RTT, clients are expected to remember and restore the server's transport parameters from the previous connection. The parameters_restored event is used to indicate which parameters were restored and to which values when utilizing 0-RTT. It has Base importance level. 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.

QUICParametersRestored definition

packet_sent The packet_sent event indicates a QUIC-level packet was sent. It has Core importance level.

QUICPacketSent definition

The encryption_level and packet_number_space are not logged explicitly: the header.packet_type specifies this by inference (assuming correct implementation) The datagram_id field is used to track packet coalescing, see .

packet_received The packet_received event indicates a QUIC-level packet was received. It has Core importance level.

QUICPacketReceived definition

The encryption_level and packet_number_space are not logged explicitly: the header.packet_type specifies this by inference (assuming correct implementation). The datagram_id field is used to track packet coalescing, see .

packet_dropped The packet_dropped event indicates a QUIC-level packet was dropped. It has Base importance level. The trigger field indicates a general reason category for dropping the packet, while the details field can contain additional implementation-specific information.

QUICPacketDropped definition any} ? trigger: "internal_error" / "rejected" / "unsupported" / "invalid" / "duplicate" / "connection_unknown" / "decryption_failure" / "key_unavailable" / "general" * $$quic-packetdropped-extension } ]]>

Some example situations for each of the trigger categories include:

• internal_error: not initialized, out of memory
• rejected: limits reached, DDoS protection, unwilling to track more paths, duplicate packet
• unsupported: unknown or unsupported version. See also .
• invalid: packet parsing or validation error
• duplicate: duplicate packet
• connection_unknown: packet does not relate to a known connection or Connection ID
• decryption_failure: decryption failed
• key_unavailable: decryption key was unavailable
• general: situations not clearly covered in the other categories

The datagram_id field is used to track packet coalescing, see .

packet_buffered The packet_buffered 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 only the full packet contents can be logged when it was parsed in a packet_received event. The event has Base importance level.

QUICPacketBuffered definition

The datagram_id field is used to track packet coalescing, see .

packets_acked The packets_acked event is emitted when a (group of) sent packet(s) is acknowledged by the remote peer for the first time. It has Extra importance level. 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.

QUICPacketsAcked definition

If packet_number_space is omitted, it assumes the default value of application_data, as this is by far the most prevalent packet number space a typical QUIC connection will use.

udp_datagrams_sent The udp_datagrams_sent event indicates when one or more UDP-level datagrams are passed to the underlying network socket. This is useful for determining how QUIC packet buffers are drained to the OS. The event has Extra importance level.

QUICUDPDatagramsSent definition

Since QUIC implementations rarely control UDP logic directly, the raw data excludes UDP-level headers in all RawInfo fields. The datagram_ids field is used to track packet coalescing, see .

udp_datagrams_received When one or more UDP-level datagrams are received from the socket. This is useful for determining how datagrams are passed to the user space stack from the OS. The event has Extra importance level.

QUICUDPDatagramsReceived definition

The datagram_ids field is used to track packet coalescing, see .

udp_datagram_dropped When a UDP-level datagram is dropped. This is typically done if it does not contain a valid QUIC packet. If it does, but the QUIC packet is dropped for other reasons, the packet_dropped event () should be used instead. The event has Extra importance level.

QUICUDPDatagramDropped definition

stream_state_updated The stream_state_updated event is emitted whenever the internal state of a QUIC stream is updated; see . Most of this can be inferred from several types of frames going over the wire, but it's often easier to have explicit signals for these state changes. The event has Base importance level. While QUIC stream IDs encode the type of stream, (see ), the optional stream_type field can be used to provide a more-accessible form of the information. describes streams in terms of their send and receive components, with a state machine for each. The stream_side field is used to indicate which side's state is updated in the logged event. In case both sides of the stream change state at the same time (for example both become closed), two separate events with different stream_side fields SHOULD be logged. In cases where it is useful to know which side of the connection initiated a state change (for example, closed due to either RESET_STREAM or STOP_SENDING), this can be reflected using the trigger field.

QUICStreamStateUpdated definition

QUIC implementations SHOULD mainly log the simplified BaseStreamStates instead of the more fine-grained GranularStreamStates. These latter ones are mainly for more in-depth debugging. Tools SHOULD be able to deal with both types equally.

Frame-related events While the packet_sent () and packet_received () events can convey all frames contained in a single QUIC packet, some implementations might not be able or willing to include frame information at the moment either event is logged. In order to support logging frame-related operations independent of packets, the frames_created, frames_parsed, and frames_processed events are defined. A qlog trace can contain both packet and frame-related events. However, it is RECOMMENDED that implementations avoid generating events with duplicate or redundant frame information, since doing so inflates the size of logs. Where an implementation logs both packet and frame-related events, the optional packet_numbers field in frame-related events can be used to explicitly link frames to packets. The field is an array, which supports using a single event for multiple frames related to multiple packets. To map between the two, the position and order of entries in the frames and packet_numbers is used. If the packet_numbers field is logged, each and every frame MUST have a corresponding packet number at the same index. For example, an instance of the frames_processed event that represents four STREAM frames received over two packets can be serialized as: Frame-related events omit information that is available in the packet_received or packet_sent event. For instance, the packet encryption level. For use cases that require such information, the packet events are preferable. Frame-related events make it possible to log, in extensions, information that is otherwise not available at the moment a packet event occurs. For instance, if frame processing was deferred for any reason.

frames_created The frames_created event indicates when a set of QUIC frames have been created. It has Extra importance level.

QUICFramesCreated definition

frames_parsed The frames_parsed event indicates when a set of QUIC frames have been parsed. It has Extra importance level.

QUICFramesParsed definition

frames_processed The frames_processed event indicates when a set of QUIC frames have been processed at the receiver. It has Extra importance level. This event exists to eliminate the need to define specific-purpose events, where the effect of processing a frame can be easily inferred from its contents. For example, there would be no need to define a hypothetical packets_acknowledged event, when an ACK frame contains all relevant information. The frames_processed 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 and logged). Using frames_processed in additional to packet_received and/or frames_parsed allows an implementation to log its full sequence of events.

QUICFramesProcessed definition

stream_data_moved The stream_data_moved event is used to indicate when QUIC stream data moves between the different layers. This helps make clear the flow of data, how long data remains in various buffers, and the overheads introduced by individual layers. The event has Base importance level. The raw.length field is used to reflect how many bytes were moved. As this event relates to stream data only, there are no packet or frame headers and the raw.length field MUST reflect that. For example, it can be useful to understand when data moves from an application protocol (e.g., HTTP) to QUIC stream buffers and vice versa. The stream_data_moved event can provide insight into 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 can help identify bottlenecks, flow control issues, or scheduling problems. The additional_info field supports optional logging of information related to the stream state. For example, an application layer that moves data into transport and simultaneously ends the stream, can log fin_set. As another example, a transport layer that has received an instruction to reset a stream can indicate this to the application layer using stream_reset. In both cases, the raw.length field can be omitted or have a zero value. This event is only for data in QUIC streams. For data in QUIC Datagram Frames, see the datagram_data_moved event defined in .

QUICStreamDataMoved definition

datagram_data_moved The datagram_data_moved event is used to indicate when QUIC Datagram Frame data (see ) moves between the different layers. This helps make clear the flow of data, how long data remains in various buffers, and the overheads introduced by individual layers. The event has Base importance level. The raw.length field is used to reflect how many bytes were moved. As this event relates to datagram data only, there are no packet or frame headers and the raw.length field MUST reflect that. For example, passing from the application protocol (e.g., WebTransport) to QUIC Datagram Frame buffers and vice versa. The datagram_data_moved event can provide insight into whether received data in a QUIC Datagram Frame 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 all Datagrams at once). This can help identify bottlenecks, flow control issues, or scheduling problems. This event is only for data in QUIC Datagram Frames. For data in QUIC streams, see the stream_data_moved event defined in .

QUICDatagramDataMoved definition

connection_data_blocked_updated The connection_data_blocked_updated event is used to indicate when the QUIC connection becomes blocked or unblocked for sending data. When a connection is "blocked", data can't be sent in streams and/or datagrams until the blocking reason has been resolved. The event has Extra importance level. Use the stream_data_blocked_updated or datagram_data_blocked_updated event to provide more fine-grained information for individual data types.

QUICConnectionDataBlockedUpdated definition

stream_data_blocked_updated The stream_data_blocked_updated event is used to indicate when a QUIC stream becomes blocked or unblocked for sending. The event has Extra importance level.

QUICStreamDataBlockedUpdated definition

datagram_data_blocked_updated The datagram_data_blocked_updated event is used to indicate when QUIC datagrams become blocked or unblocked for sending. The event has Extra importance level.

QUICDatagramDataBlockedUpdated definition

migration_state_updated 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 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. Generally speaking, connection migration goes through two phases: a probing 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 QUICTupleAssigned events, to serve as a ground-truth source of information. Definition:

QUICMigrationStateUpdated definition

timer_updated The timer_updated event is emitted when a timer changes state. It has Extra importance level. 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

In order to indicate an active timer's timeout update, a new set event is used. QUICTimerUpdated events with the timer_type set to ack or pto indicate changes to the individual timeouts defined by RFC 9002: the threshold loss detection timeout (see ) and the probe timeout (see ). Those set to loss_timeout represent changes to the multi-modal loss detection timer (see ). The QUIC protocol conceptually employs a variety of timers, but their usage can be implementation-dependent. Implementers can add additional fields to this event if needed via $$quic-timerupdated-extension or specify other/additional timer types via $TimerType.

QUICTimerUpdated definition

Security Events

key_updated The key_updated event has Base importance level.

QUICKeyUpdated definition

Note that the key_phase is the full value of the key phase (as indicated by @M and @N in Figure 9 of ). The key phase bit used on the packet header is the least significant bit of the key phase.

key_discarded The key_discarded event has Base importance level.

QUICKeyDiscarded definition

Recovery events 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).

recovery_parameters_set The recovery_parameters_set event groups initial parameters from both loss detection and congestion control into a single event. It has Base importance level. All these settings are typically set once and never change. Implementations that do, for some reason, change these parameters during execution, MAY emit the recovery_parameters_set event more than once.

QUICRecoveryParametersSet definition

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

recovery_metrics_updated The recovery_metrics_updated event is emitted when one or more of the observable recovery metrics changes value. It has Core importance level. 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 recovery_metrics_updated entry, rather than split out into two). Consequently, a recovery_metrics_updated event is only guaranteed to contain at least one of the listed metrics.

QUICRecoveryMetricsUpdated definition

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

congestion_state_updated The congestion_state_updated event indicates when the congestion controller enters a significant new state and changes its behaviour. It has Base importance level. The values of the event's fields are intentionally unspecified here in order to support different Congestion Control algorithms, as these typically have different states and even different implementations of these states across stacks. For example, for the algorithm defined in the QUIC Recovery RFC ("enhanced" New Reno), the following states are used: Slow Start, Congestion Avoidance, Application Limited and Recovery. Similarly, states can be triggered by a variety of events, including detection of Persistent Congestion or receipt of ECN markings.

QUICCongestionStateUpdated definition

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 occurring (for example Slow Start is often exited only when ssthresh is exceeded).

packet_lost The packet_lost event is emitted when a packet is deemed lost by loss detection. It has Core importance level. It is RECOMMENDED to populate the optional trigger field in order to help disambiguate among the various possible causes of a loss declaration.

QUICPacketLost definition

marked_for_retransmit The marked_for_retransmit event indicates which data was marked for retransmission upon detection of packet loss (see packet_lost). It has Extra importance level. Similar to the reasoning for the frames_processed event, in order to keep the amount of different events low, this signal is grouped into in a single event based on existing QUIC frame definitions for all types of retransmittable data. Implementations retransmitting full packets or frames directly can just log the constituent 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. 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).

QUICMarkedForRetransmit definition

ecn_state_updated The ecn_state_updated event indicates a progression in the ECN state machine as described in . It has Extra importance level.

QUICECNStateUpdated definition

QUIC data type definitions

QuicVersion

QuicVersion definition

ConnectionID

ConnectionID definition

Initiator

Initiator definition

IPAddress

IPAddress definition

TupleEndpointInfo 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 tuple information SHOULD include two different TupleEndpointInfo instances, one for each half of the tuple.

TupleEndpointInfo definition

PacketType

PacketType definition

PacketNumberSpace

PacketNumberSpace definition

PacketHeader If the packet_type numerical value does not map to a known $PacketType string, the packet_type value of "unknown" can be used and the raw value captured in the packet_type_bytes field; a numerical value without variable-length integer encoding. The fixed and reserved bits are omitted here because they must be 0; see . If these bits have an invalid value, the raw values can be captured in the raw.data field of the event logging the PacketHeader. QUIC extensions that do utilize these bits are expected to create new events (analogous to spin_bit_updated) or use qlog extension mechanisms to reflect that usage. For long header packets of type initial, handshake, and 0RTT, the length field of the packet header is logged in the qlog raw.length field, and the value signifies the length of the packet number plus the payload.

PacketHeader definition

Token

Token definition any } ? raw: RawInfo * $$quic-token-extension } $TokenType /= "retry" / "resumption" ]]>

The token carried in an Initial packet can either be a retry token from a Retry packet, or one originally provided by the server in a NEW_TOKEN frame used when resuming a connection (e.g., for address validation purposes). Retry and resumption tokens typically contain encoded metadata to check the token's validity when it is used, but this metadata and its format is implementation specific. For that, Token includes a general-purpose details field.

Stateless Reset Token

Stateless Reset Token definition

The stateless reset token is carried in stateless reset packets, in transport parameters and in NEW_CONNECTION_ID frames.

KeyType

KeyType definition

ECN

ECN definition

The ECN bits carried in the IP header.

QUIC Frames The generic $QuicFrame is defined here as a CDDL "type socket" extension point. It can be extended to support additional QUIC frame types.

QuicFrame type socket definition any } ]]>

The QUIC frame types defined in this document are as follows:

QuicBaseFrames definition

PaddingFrame In QUIC, PADDING frames are simply identified as a single byte of value 0. As such, each padding byte could be theoretically interpreted and logged as an individual PaddingFrame. However, as this leads to heavy logging overhead, implementations SHOULD instead emit just a single PaddingFrame and set the raw.payload_length property to the amount of PADDING bytes/frames included in the packet.

PaddingFrame definition

PingFrame

PingFrame definition

AckFrame

AckFrame definition

Note that the packet ranges in AckFrame.acked_ranges do not necessarily have to be ordered (e.g., [[5,9],[1,4]] is a valid value). Note that the two numbers in the packet range can be the same (e.g., [120,120] means that packet with number 120 was ACKed). However, in that case, implementers SHOULD log [120] instead and tools MUST be able to deal with both notations.

ResetStreamFrame If the error numerical value does not map to a known ApplicationError string, the error value of "unknown" can be used and the raw value captured in the error_code field; a numerical value without variable-length integer encoding.

ResetStreamFrame definition

ResetStreamAtFrame If the error_code numerical value does not map to a known ApplicationError string, the error_code value of "unknown" can be used and the raw value captured in the error_code_bytes field; a numerical value without variable-length integer encoding.

ResetStreamAtFrame definition

StopSendingFrame If the error numerical value does not map to a known ApplicationError string, the error value of "unknown" can be used and the raw value captured in the error_code field; a numerical value without variable-length integer encoding.

StopSendingFrame definition

CryptoFrame The length field of the Crypto frame MUST be logged in the qlog raw.length field. The other sub-fields of the raw field are optional.

CryptoFrame definition

NewTokenFrame

NewTokenFrame definition

StreamFrame If the stream frame contains a length field, it MUST be logged in the qlog raw.length field. If it does not, the implementation MAY calculate the actual frame byte length itself and log that in raw.length if necessary.

StreamFrame definition

MaxDataFrame

MaxDataFrame definition

MaxStreamDataFrame

MaxStreamDataFrame definition

MaxStreamsFrame

MaxStreamsFrame definition

DataBlockedFrame

DataBlockedFrame definition

StreamDataBlockedFrame

StreamDataBlockedFrame definition

StreamsBlockedFrame

StreamsBlockedFrame definition

NewConnectionIDFrame

NewConnectionIDFrame definition

RetireConnectionIDFrame

RetireConnectionIDFrame definition

PathChallengeFrame

PathChallengeFrame definition

PathResponseFrame

PathResponseFrame definition

ConnectionCloseFrame An endpoint that receives unknown error codes can record it in the error_code field using the numerical value without variable-length integer encoding. When the connection is closed due a connection-level error, the trigger_frame_type field can be used to log the frame that triggered the error. For known frame types, the appropriate string value is used in the error field. For unknown frame types, the error field has the value "unknown" and the numerical value without variable-length integer encoding can be logged in error_code. The CONNECTION_CLOSE reason phrase is a byte sequence. It is likely that this sequence is presentable as UTF-8, in which case it can be logged in the reason field. The reason_bytes field supports logging the raw bytes, which can be useful when the value is not UTF-8 or when an endpoint does not want to decode it. Implementations SHOULD log at least one format, but MAY log both or none.

ConnectionCloseFrame definition

HandshakeDoneFrame

HandshakeDoneFrame definition

UnknownFrame The frame_type_bytes field is the numerical value without variable-length integer encoding.

UnknownFrame definition

DatagramFrame The QUIC DATAGRAM frame is defined in . If the datagram frame contains a length field, it MUST be logged in the qlog raw.length field. If it does not, the implementation MAY calculate the actual datagram byte length itself and log that in raw.length if necessary.

DatagramFrame definition

TransportError The generic $TransportError is defined here as a CDDL "type socket" extension point. It can be extended to support additional Transport errors.

TransportError definition

ApplicationError By definition, an application error is defined by the application-level protocol running on top of QUIC (e.g., HTTP/3). As such, it cannot be defined here completely. It is instead defined as a CDDL "type socket" extension point, with a single "unknown" value.

ApplicationError definition

Application-level qlog definitions that wish to define new ApplicationError strings MUST do so by extending the $ApplicationError socket as such:

CryptoError These errors are defined in the TLS document as "A TLS alert is turned into a QUIC connection error by converting the one-byte alert description into a QUIC error code. The alert description is added to 0x100 to produce a QUIC error code from the range reserved for CRYPTO_ERROR." This approach maps badly to a pre-defined enum. As such, the crypto_error string is defined as having a dynamic component here, which should include the hex-encoded and zero-padded value of the TLS alert description.

CryptoError definition

Handling Packet Coalescing Multiple QUIC packets can be coalesced in a single UDP datagram, especially during the handshake (see ). However, neither QUIC nor UDP themselves provide an explicit mechanism to track this behaviour. To make it possible for implementations to track coalescing across packet-level and datagram-level qlog events, this document defines a qlog-specific mechanism for tracking coalescing across packet-level and datagram-level qlog events: a "datagram identifier" carried in datagram_id fields. qlog implementations that want to track coalescing can use this mechanism, where multiple events sharing the same datagram_id indicate they were coalesced in the same UDP datagram. The selection of specific and locally-unique datagram_id values is an implementation choice.

Security and Privacy Considerations The security and privacy considerations discussed in apply to this document as well.

IANA Considerations This document registers a new entry in the "qlog event schema URIs" registry (created in ):

Event schema URI:

urn:ietf:params:qlog:events:quic

Namespace

quic

Event Types

server_listening, connection_started, connection_closed, connection_id_updated, spin_bit_updated, connection_state_updated, tuple_assigned, mtu_updated, version_information, alpn_information, parameters_set, parameters_restored, packet_sent, packet_received, packet_dropped, packet_buffered, packets_acked, udp_datagrams_sent, udp_datagrams_received, udp_datagram_dropped, stream_state_updated, frames_created, frames_parsed, frames_processed, stream_data_moved, datagram_data_moved, connection_data_blocked_updated, stream_data_blocked_updated, datagram_data_blocked_updated, migration_state_updated, key_updated, key_discarded, recovery_parameters_set, recovery_metrics_updated, congestion_state_updated, timer_updated, packet_lost, marked_for_retransmit, ecn_state_updated

Description:

Event definitions related to the QUIC transport protocol.

Reference:

This Document

References Normative References Akamai Meta Cloudflare qlog provides extensible structured logging for network protocols, allowing for easy sharing of data that benefits common debug and analysis methods and tooling. This document describes key concepts of qlog: formats, files, traces, events, and extension points. This definition includes the high-level log file schemas, and generic event schemas. Requirements and guidelines for creating protocol- specific event schemas are also presented. All schemas are defined independent of serialization format, allowing logs to be represented in various ways such as JSON, CSV, or protobuf. Note to Readers Note to RFC editor: Please remove this section before publication. Feedback and discussion are welcome at https://github.com/quicwg/qlog (https://github.com/quicwg/qlog). Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document. This document defines the core of the QUIC transport protocol. QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment, and network path migration. QUIC includes security measures that ensure confidentiality, integrity, and availability in a range of deployment circumstances. Accompanying documents describe the integration of TLS for key negotiation, loss detection, and an exemplary congestion control algorithm. This document describes loss detection and congestion control mechanisms for QUIC. This document describes how Transport Layer Security (TLS) is used to secure QUIC. This document defines an extension to the QUIC transport protocol to add support for sending and receiving unreliable datagrams over a QUIC connection. This document describes a method for negotiating the ability to send an arbitrary value for the second-most significant bit in QUIC packets. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. This document defines an extension to the QUIC transport protocol to add support for sending and receiving unreliable datagrams over a QUIC connection. Informative References This document describes a Transport Layer Security (TLS) extension for application-layer protocol negotiation within the TLS handshake. For instances in which multiple application protocols are supported on the same TCP or UDP port, this extension allows the application layer to negotiate which protocol will be used within the TLS connection.

Acknowledgements Much of the initial work by Robin Marx was done at the Hasselt and KU Leuven Universities. Thanks to Jana Iyengar, Brian Trammell, Dmitri Tikhonov, Stephen Petrides, Jari Arkko, Marcus Ihlar, Victor Vasiliev, Mirja Kuehlewind, Jeremy Laine, Kazu Yamamoto, Christian Huitema, Hugo Landau, Will Hawkins, Mathis Engelbart, Kazuho Oku, and Jonathan Lennox for their feedback and suggestions.

Change Log

Since draft-ietf-qlog-quic-events-12:

• Split frames_processed into 3 events (#513)
• Wide range of editorial changes

Since draft-ietf-qlog-quic-events-11:

• Updated several fields to be uint64 per QUIC spec
• Renamed error and error_code fields and logic (#473)
• Clarified parameters_set usage (#493)
• Replaced all length fields with raw.length (#495)
• Change loss_timer_updated to timer_updated (#496)
• Renamed path_assigned to tuple_assigned (#491)
• Reworked stream_state_updated (#497)
• Renamed owner to initiator (#498)
• Split up flags in PacketHeader (#478)

Since draft-ietf-qlog-quic-events-09:

• Several editorial changes
• Reworked QUICConnectionStarted to use PathEndpointInfo (#453)
• Consistent use of RawInfo and _bytes fields to log raw data (#450)

Since draft-ietf-qlog-quic-events-08:

• Removed individual categories and put every event in the single quic event schema namespace. Major change (#439)
• Renamed recovery:metrics_updated to quic:recovery_metrics_updated and recovery:parameters_set to quic:recovery_parameters_set (#439)
• Added unknown_parameters field to parameters_set (#438)
• Added extra parameters to parameters_restored (#441)

Since draft-ietf-qlog-quic-events-07:

• TODO (we forgot...)

Since draft-ietf-qlog-quic-events-06:

• Added PathAssigned and MigrationStateUpdated events (#336)
• Added extension points to parameters_set and parameters_restored (#400)
• Removed error_code_value from connection_closed (#386, #392)
• Renamed generation to key_phase for key_updated and key_discarded (#390)
• Removed retry_token from packet_sent and packet_received (#389)
• Updated ALPN handling (#385)
• Added key_unavailable trigger to packet_dropped (#381)
• Updated several uint32 to uint64
• ProtocolEventBody is now called ProtocolEventData (#352)
• Editorial changes (#402, #404, #394, #393)

Since draft-ietf-qlog-quic-events-05:

• SecurityKeyUpdated: the new key is no longer mandatory to log (#294)
• Added ECN related events and metadata (#263)

Since draft-ietf-qlog-quic-events-04:

• Updated guidance on logging events across connections (#279)
• Renamed 'transport' category to 'quic' (#302)
• Added support for multiple packet numbers in 'quic:frames_processed' (#307)
• Added definitions for RFC9287 (QUIC GREASE Bit extension) (#311)
• Added definitions for RFC9221 (QUIC Datagram Frame extension) (#310)
• (Temporarily) removed definitions for connection migration events (#317)
• Editorial and formatting changes (#298, #299, #304, #306, #327)

Since draft-ietf-qlog-quic-events-03:

• Ensured consistent use of RawInfo to indicate raw wire bytes (#243)
• Renamed UnknownFrame:raw_frame_type to :frame_type_value (#54)
• Renamed ConnectionCloseFrame:raw_error_code to :error_code_value (#54)
• Changed triggers for packet_dropped (#278)
• Added entries to TransportError enum (#285)
• Changed minimum_congestion_window to uint64 (#288)

Since draft-ietf-qlog-quic-events-02:

• Renamed key_retired to key_discarded (#185)
• Added fields and events for DPLPMTUD (#135)
• Made packet_number optional in PacketHeader (#244)
• Removed connection_retried event placeholder (#255)
• Changed QuicFrame to a CDDL plug type (#257)
• Moved data definitions out of the appendix into separate sections
• Added overview Table of Contents

Since draft-ietf-qlog-quic-events-01:

• Added Stateless Reset Token type (#122)

Since draft-ietf-qlog-quic-events-00:

• Change the data definition language from TypeScript to CDDL (#143)

Since draft-marx-qlog-event-definitions-quic-h3-02:

• These changes were done in preparation of the adoption of the drafts by the QUIC working group (#137)
• Split QUIC and HTTP/3 events into two separate documents
• Moved RawInfo, Importance, Generic events and Simulation events to the main schema document.
• Changed to/from value options of the data_moved event

Since draft-marx-qlog-event-definitions-quic-h3-01: Major changes:

• Moved data_moved from http to transport. Also made the "from" and "to" fields flexible strings instead of an enum (#111,#65)
• Moved packet_type fields to PacketHeader. Moved packet_size field out of PacketHeader to RawInfo:length (#40)
• Made events that need to log packet_type and packet_number use a header field instead of logging these fields individually
• Added support for logging retry, stateless reset and initial tokens (#94,#86,#117)
• Moved separate general event categories into a single category "generic" (#47)
• Added "transport:connection_closed" event (#43,#85,#78,#49)
• Added version_information and alpn_information events (#85,#75,#28)
• Added parameters_restored events to help clarify 0-RTT behaviour (#88)

Smaller changes:

• Merged loss_timer events into one loss_timer_updated event
• Field data types are now strongly defined (#10,#39,#36,#115)
• Renamed qpack instruction_received and instruction_sent to instruction_created and instruction_parsed (#114)
• Updated qpack:dynamic_table_updated.update_type. It now has the value "inserted" instead of "added" (#113)
• Updated qpack:dynamic_table_updated. It now has an "owner" field to differentiate encoder vs decoder state (#112)
• Removed push_allowed from http:parameters_set (#110)
• Removed explicit trigger field indications from events, since this was moved to be a generic property of the "data" field (#80)
• Updated transport:connection_id_updated to be more in line with other similar events. Also dropped importance from Core to Base (#45)
• Added length property to PaddingFrame (#34)
• Added packet_number field to transport:frames_processed (#74)
• Added a way to generically log packet header flags (first 8 bits) to PacketHeader
• Added additional guidance on which events to log in which situations (#53)
• Added "simulation:scenario" event to help indicate simulation details
• Added "packets_acked" event (#107)
• Added "datagram_ids" to the datagram_X and packet_X events to allow tracking of coalesced QUIC packets (#91)
• Extended connection_state_updated with more fine-grained states (#49)

Since draft-marx-qlog-event-definitions-quic-h3-00:

• Event and category names are now all lowercase
• Added many new events and their definitions
• "type" fields have been made more specific (especially important for PacketType fields, which are now called packet_type instead of type)
• Events are given an importance indicator (issue #22)
• Event names are more consistent and use past tense (issue #21)
• Triggers have been redefined as properties of the "data" field and updated for most events (issue #23)