]> Akamai

rmarx@akamai.com

Meta

lniccolini@meta.com

martenseemann@gmail.com

Apple

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. The data types that the events use are defined in .

Use of Group IDs QUIC's Original Destination Connection ID (ODCID) can be used as the value of the qlog group_id field. The ODCID is the connection ID that the client chooses for its first Initial packet. It stays the same for the whole connection, unlike the connection IDs that endpoints use, which can change. It can also link packets such as Retry and Version Negotiation to the connection. The ODCID can also be used as the qlog filename or file identifier, optionally suffixed by the vantage point type. For example, abcd1234_server.qlog would contain the server-side trace of the connection with ODCID abcd1234.

Raw Packet and Frame Information Protected QUIC packets (Initial, 0-RTT, Handshake, and 1-RTT) end with an AEAD authentication tag. Every cipher suite that QUIC version 1 can use has a 16-byte tag; see . When calculating the lengths in RawInfo fields () for these packets, the tag is treated as a 16-byte trailer.

Events without a Known Connection A qlog trace is typically associated with a single QUIC connection. However, some events cannot be tied to a specific connection, especially on the server. For example, a packet_dropped event () with the trigger "connection_unknown" is for a packet that matches no known connection. There are various ways to handle these events, each with tradeoffs between file size overhead, flexibility, ease of use, and 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 to identify the connection, for example the four-tuple in addition to the connection ID.
• Buffer events until they can be assigned to a connection, for example events about the Version Negotiation and Retry packets that a server sends before it creates connection state.

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 . This document uses the following from : the event namespace and event type concepts; the name, data, tuple, group_id, and time-related fields; and the RawInfo type. 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:stream_data_moved	Base
quic:datagram_data_moved	Base
quic:datagram_dropped	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, Transport, Security, and Recovery are purely for readability.

Connectivity Events

server_listening The server_listening event is emitted when the server starts accepting connections. It has Extra importance level.

QUICServerListening definition

Some QUIC stacks do not handle sockets directly, so they cannot log IP addresses or ports.

connection_started The connection_started event is emitted when a client attempts a new connection, or when a server accepts one. It overlaps with the connection_state_updated event, but it also logs the local and remote endpoint information. It has Base importance level.

QUICConnectionStarted definition

Some QUIC stacks do not handle sockets directly, so they cannot log IP addresses or ports. All fields of TupleEndpointInfo () are optional, so such a stack can log local and remote with only the fields it knows, such as connection_ids.

connection_closed The connection_closed event is emitted when a connection closes, typically because of an error or a timeout. It has Base importance level. This event overlaps with the connection_state_updated event and the CONNECTION_CLOSE frame. However, when analyzing large deployments, it can be useful to have a single event for each closure, with a reason field for more detail. This event can also log closures due to timeouts or explicit application actions, such as racing several connections and aborting the slowest, which the other events cannot easily capture. The connection_closed event is logged when the local endpoint does one of the following; see :

• silently discards the connection after an idle timeout;
• sends a CONNECTION_CLOSE frame, and enters the closing state;
• receives a CONNECTION_CLOSE frame, and enters the draining state; or
• receives a Stateless Reset, and enters the draining state.

Later changes, such as leaving the closing or draining state, are logged with the connection_state_updated event. QUIC has two kinds of connection error, transport errors and application errors, each with defined codes and semantics; see . An implementation can also have internal errors, which it might or might not map to these codes. So this event can carry two levels of error: connection_error or application_error for the QUIC error, and internal_code for a more specific internal error. If an error code has no known string, connection_error or application_error can be "unknown", and error_code then holds the numerical value without variable-length integer encoding.

QUICConnectionClosed definition

Implementations SHOULD use the most descriptive trigger value that they can determine. This is often clear at the endpoint that closes the connection, but can be less clear at the endpoint that receives the CONNECTION_CLOSE frame.

connection_id_updated The connection_id_updated event is emitted when either endpoint updates its current connection ID. This typically happens rarely during a connection, so logging this event is more efficient than logging the connection ID in every packet_sent or packet_received event. It has Base importance level. The connection_id_updated event is viewed from the perspective of the endpoint applying the new ID. When the endpoint receives a new connection ID from the peer, the initiator field is "remote". When the endpoint updates its own connection ID, the initiator field is "local".

QUICConnectionIDUpdated definition

spin_bit_updated The spin_bit_updated event is emitted when the value of the QUIC latency spin bit changes; see . It SHOULD NOT be emitted when the spin bit is set to the value it already has. It has Base importance level.

QUICSpinBitUpdated definition

connection_state_updated The connection_state_updated event is emitted when the connection changes state, to track progress through the QUIC handshake and connection close. It has Base importance level. does not define a complete set of connection states or their transitions, though it names some, such as the closing and draining states. This document defines the states most likely to be useful for debugging QUIC connections; the list is not exhaustive. QUIC implementations SHOULD log the BaseConnectionStates, and can add the GranularConnectionStates when more in-depth debugging is required. Tools SHOULD handle both kinds equally.

QUICConnectionStateUpdated definition

The connection_state_updated event overlaps with the connection_closed and connection_started events, and with the frames logged in events such as packet_received. Still, it can be useful to log state transitions separately, especially if they map to an internal state machine. Implementations can therefore use other ConnectionState values that match their internal logic. Tools SHOULD handle these custom states in a similar way to the states defined in this document.

tuple_assigned The tuple_assigned event associates a TupleID with the details of a network tuple, such as its IP addresses, ports, and connection IDs. It has Base importance level. As described in , each qlog event can be linked to a single network tuple by its top-level tuple field, whose value is a TupleID. Encoding tuple details, such as IP addresses or connection IDs, into the TupleID itself can be cumbersome. This event records them separately, so TupleIDs can stay short, and their details can be updated as the connection evolves.

QUICTupleAssigned definition

Implementations choose their own tuple_id values. For example, a TupleID can be an incrementing integer, the first Destination Connection ID associated with the tuple (or its sequence number), or the two endpoint IP addresses or a hash of them. The empty string ("") is a valid TupleID, and it is the default for events that do not set the tuple field. So the initial tuple of a QUIC connection, on which the handshake occurs (see ), is implicitly associated with the TupleID "". Details for this default tuple can be logged with a tuple_assigned event whose tuple_id is "". Because a tuple's details can change during the connection, a TupleID can appear in several tuple_assigned events, and the latest one holds its current details. The first tuple_assigned event for a TupleID indicates that the TupleID was created, and later ones indicate updates. An event with both tuple_local and tuple_remote omitted indicates that the TupleID was abandoned.

mtu_updated The mtu_updated event indicates that the estimated Path MTU was updated. This happens as part of Path MTU discovery; see . It has Extra importance level.

QUICMTUUpdated definition

The done field defaults to false.

Transport Events

version_information The version_information event supports QUIC version negotiation; see . It has Core importance level. Each QUIC endpoint supports one or more versions. The client sends its first Initial packet using one of them. A server that does not support that version can reply with a Version Negotiation packet, which lists the versions the server supports. This event records the versions that each endpoint supports, and the chosen version if there is one.

QUICVersionInformation definition

A client logs this event when it sends its first Initial packet. The event includes client_versions, and chosen_version holds the version used in that packet. If the client then processes a Version Negotiation packet, it logs this event again with client_versions. The event also includes server_versions, which holds the versions from that packet. If the client selects one of them, chosen_version holds it; otherwise, chosen_version is absent. A Version Negotiation packet can also list reserved versions, which an endpoint adds to check that its peer ignores unknown versions; see . Because server_versions holds the versions from the packet, it can include reserved versions. A server logs this event when it receives a client's first Initial packet. The event includes server_versions. If the server supports the client's version, chosen_version holds the version that the server uses for the connection. Otherwise, chosen_version is absent, and client_versions holds the version the client used.

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. During the TLS handshake, the client sends its list, and the server chooses one identifier from both lists and sends it back. If no match is found, the connection is closed. ALPN identifiers are byte sequences, which are often valid UTF-8. The ALPNIdentifier type can hold either form: byte_value holds the raw bytes, and string_value holds the identifier as text. Implementations SHOULD log at least one form and MAY log both.

QUICALPNInformation definition

A client usually logs this event twice: first with client_alpns when it offers its list, then with chosen_alpn when it learns the server's choice. It can instead log a single event with both fields once it learns the choice. A server logs this event once, after it chooses, with client_alpns, server_alpns, and chosen_alpn.

parameters_set The parameters_set event groups settings from several sources, such as transport parameters and the TLS cipher suite, into a single event. This keeps the number of events low, and lets a reader reason about what the settings do without needing to know which mechanism set each one. It has Core importance level. Most of these settings are set once and never change. However, they are often set at different times during the connection, so a trace can contain several parameters_set events with different fields set. Some settings have two values: one set by the local endpoint, and one requested by the peer. The initiator field says which side the settings in an event come from, so it MUST be correct for every setting in that event. Local and remote settings MUST be logged in separate events. If the local endpoint changes its behavior based on the peer's settings, the outcome can be logged with a new event type, or with fields added through $$quic-parametersset-extension; see . The initiator field is required. Settings that both endpoints negotiate, such as tls_cipher, are logged in both the local and the remote event. Each setting starts the connection with its default value, or with no value if it has no default. A parameters_set event that includes a setting replaces its previous value; settings that the event omits keep their values. The grease_quic_bit and reset_stream_at settings are true if the transport parameter is present, and default to false. Implementations are not required to recognize, process, or support every parameter that they receive. For example, QUIC implementations ignore transport parameters that they do not support; see . The unknown_parameters field can log the raw values of such parameters, for example reserved (GREASE) parameters, private extensions, or experiments. 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 that a QUIC packet was sent. It has Core importance level.

QUICPacketSent definition

The encryption level and packet number space are not logged explicitly, because header.packet_type implies them for the packet types that have them. The datagram_payload_checksum field is described in . The is_mtu_probe_packet field defaults to false.

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

QUICPacketReceived definition

The encryption level and packet number space are not logged explicitly, because header.packet_type implies them for the packet types that have them. The datagram_payload_checksum field is described in .

packet_dropped The packet_dropped event indicates that a QUIC packet was dropped. It has Base importance level.

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

The trigger field gives a general reason for dropping the packet, and the details field can hold additional implementation-specific information. Some example situations for each trigger value include:

• "internal_error": not initialized, out of memory
• "rejected": limits reached, DDoS protection, unwilling to track more paths
• "unsupported": unknown or unsupported version
• "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
• "keys_unavailable": decryption keys were unavailable
• "general": situations not clearly covered in the other categories

Packets dropped as "unsupported" or "connection_unknown" often cannot be tied to a connection; see . The datagram_payload_checksum field is described in .

packet_buffered The packet_buffered event is emitted when a packet is buffered because it cannot be processed yet, for example because the keys to decrypt it are not yet available. Its full contents can be logged later, in a packet_received event, once it is processed. It has Base importance level.

QUICPacketBuffered definition

The datagram_payload_checksum field is described in .

packets_acked The packets_acked event is emitted when one or more sent packets are acknowledged by the peer for the first time. It has Extra importance level. Successive ACK frames can acknowledge the same packet, but this event is emitted only for the first acknowledgment of each packet. This information can also be deduced from received ACK frames, though finding the first acknowledgment needs extra processing. Implementations that do not log frame contents can use this event instead.

QUICPacketsAcked definition

The packet_number_space field defaults to "application_data", the packet number space that most packets in a typical QUIC connection use.

udp_datagrams_sent The udp_datagrams_sent event indicates that one or more UDP datagrams were passed to the network socket. It can show how QUIC packet buffers are drained to the operating system. It has Extra importance level.

QUICUDPDatagramsSent definition

The RawInfo fields exclude UDP headers, because QUIC implementations do not always handle UDP directly. If an event omits the ecn field, the ECN bits are the same as on the last udp_datagrams_sent event. The datagram_payload_checksums field is described in .

udp_datagrams_received The udp_datagrams_received event indicates that one or more UDP datagrams were received from the network socket. It can show how the operating system passes datagrams to the user-space stack. It has Extra importance level.

QUICUDPDatagramsReceived definition

If an event omits the ecn field, the ECN bits are the same as on the last udp_datagrams_received event. The datagram_payload_checksums field is described in .

udp_datagram_dropped The udp_datagram_dropped event indicates that a UDP datagram was dropped, typically because it does not contain a valid QUIC packet. If the datagram contains a valid QUIC packet that is dropped for another reason, the packet_dropped event () is used instead. It has Extra importance level.

QUICUDPDatagramDropped definition

stream_state_updated The stream_state_updated event is emitted when the state of a QUIC stream changes; see . Most state changes can be inferred from the frames that are sent and received, but an explicit event can be easier to use. It has Base importance level. QUIC stream IDs encode whether a stream is unidirectional or bidirectional (see ), but the optional stream_type field states it directly. describes the sending and receiving parts of a stream, each with its own state machine. The stream_side field says which part's state changed. If both parts change state at the same time, for example when both become "closed", two events with different stream_side values SHOULD be logged.

QUICStreamStateUpdated definition

QUIC implementations SHOULD log the BaseStreamStates, and can add the GranularStreamStates when more in-depth debugging is required. Tools SHOULD handle both kinds equally. The trigger field can show which endpoint initiated a state change, for example when a stream is closed because of a RESET_STREAM or STOP_SENDING frame.

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. The frames_created and frames_parsed events log frames independently of packets. 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 link frames to packets explicitly. The field is an array so that a single event can log frames that belong to different packets. The frames and packet_numbers arrays are mapped to each other by the position and order of their entries. If the packet_numbers field is logged, every frame MUST have a corresponding packet number at the same index. For example, an instance of the frames_parsed 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, such as the packet's encryption level. Use cases that need such information are better served by those events. Extensions can use frame-related events to log information that is not available when a packet event is logged, for example because frame processing was deferred.

frames_created The frames_created event indicates that a set of QUIC frames was created. It has Extra importance level.

QUICFramesCreated definition

frames_parsed The frames_parsed event indicates that a set of QUIC frames was parsed. It has Extra importance level.

QUICFramesParsed definition

stream_data_moved The stream_data_moved event indicates that QUIC stream data moved between layers. It has Base importance level. For example, data can move from an application protocol such as HTTP/3 to QUIC stream buffers, or the other way. Logging these moves can show the flow of data, how long data stays in each buffer, and the overhead introduced by each layer. This event can also show whether received stream data is passed to the application protocol immediately or in batches. Data can be passed, for example, once per received packet, or in a batch after all received packets are processed. This can help identify bottlenecks, flow control issues, or scheduling problems. The raw.length field gives the number of bytes moved. Because this event covers stream data only, there are no packet or frame headers, and raw.length MUST reflect that. The additional_info field can log information about the stream state. For example, an application that moves data into the transport and ends the stream at the same time can log "fin_set". A transport that has received an instruction to reset a stream can tell the application with "stream_reset". In both cases, raw.length can be omitted or be zero. This event covers only data in QUIC streams. For data in QUIC datagrams, see the datagram_data_moved event ().

QUICStreamDataMoved definition

datagram_data_moved The datagram_data_moved event indicates that QUIC datagram data (see ) moved between layers. It has Base importance level. For example, data can move from an application protocol such as WebTransport to QUIC buffers, or the other way. Logging these moves can show the flow of data, how long data stays in each buffer, and the overhead introduced by each layer. This event can also show whether received datagram data is passed to the application protocol immediately or in batches. Data can be passed, for example, once per received packet, or in a batch after all received packets are processed. This can help identify bottlenecks or scheduling problems. The raw.length field gives the number of bytes moved. Because this event covers datagram data only, there are no packet or frame headers, and raw.length MUST reflect that. This event covers only data in QUIC datagrams. For data in QUIC streams, see the stream_data_moved event ().

QUICDatagramDataMoved definition

datagram_dropped The datagram_dropped event indicates that QUIC DATAGRAM data (see ) was discarded locally, before sending or after reception. It has Base importance level. The direction field identifies the sending or receiving side, and trigger indicates the reason for discarding the data. The raw.length field MUST count discarded payload bytes, excluding packet and frame headers. Received DATAGRAM data can be discarded while its packet is still acknowledged. For drops of entire QUIC packets, use packet_dropped ().

QUICDatagramDropped definition

connection_data_blocked_updated The connection_data_blocked_updated event indicates that the QUIC connection became blocked or unblocked for sending data. It has Extra importance level. Depending on the reason, a blocked connection cannot send stream data, datagram data, or both, until that reason is resolved. The stream_data_blocked_updated and datagram_data_blocked_updated events give more detail for each type of data.

QUICConnectionDataBlockedUpdated definition

stream_data_blocked_updated The stream_data_blocked_updated event indicates that a QUIC stream became blocked or unblocked for sending. It has Extra importance level.

QUICStreamDataBlockedUpdated definition

datagram_data_blocked_updated The datagram_data_blocked_updated event indicates that QUIC datagrams became blocked or unblocked for sending. It has Extra importance level.

QUICDatagramDataBlockedUpdated definition

migration_state_updated The migration_state_updated event logs the progress of a connection migration by a client; see . It has Extra importance level. Most details of a migration can be inferred from PATH_CHALLENGE and PATH_RESPONSE frames, together with tuple_assigned events. However, it can be useful to log the progress of the migration, and any decisions made, in a single event. The MigrationState values follow the steps in : the probing_* values cover probing a new path (), and the migration_* values cover migrating the connection (). Implementations that log per-path information in migration_state_updated events SHOULD also emit tuple_assigned events, to serve as the ground truth for tuple information.

QUICMigrationStateUpdated definition

timer_updated The timer_updated event is emitted when a timer changes state. It has Extra importance level. The event_type field takes one of three values:

• "set": the timer is set, and delta gives the time until it triggers
• "expired": the timer expired
• "cancelled": the timer was cancelled

An update to an active timer's timeout is logged as a new "set" event. The recovery timer types correspond to timers in and :

• "ack": the time threshold loss detection timeout
• "pto": the probe timeout
• "loss_timeout": the single, multi-modal loss detection timer that covers both

QUIC uses a variety of timers, and how they are used can depend on the implementation. Implementers can add fields to this event through $$quic-timerupdated-extension, or add timer types through $TimerType.

QUICTimerUpdated definition

Security Events

key_updated The key_updated event indicates that a key was installed or updated. It has Base importance level. This happens when TLS provides new keys during the handshake, and at each 1-RTT key update; see .

QUICKeyUpdated definition

The key_phase field holds the full key phase, which identifies the generation of keys; it corresponds to @M and @N in Figure 9 of . The Key Phase bit in the packet header is the least significant bit of this value.

key_discarded The key_discarded event indicates that a key was discarded. It has Base importance level. Keys are discarded, for example, when the connection moves to a new encryption level during the handshake, or after a key update; see .

QUICKeyDiscarded definition

Recovery Events Most of the events in this section are kept generic to support different recovery approaches and congestion control algorithms. The old, new, and trigger fields of congestion_state_updated, for instance, are free text, so their values depend on the algorithm. Tools that process these events SHOULD try to handle such values even when they don't recognize them. For example, a tool that plots congestion states on a timeline can label an unknown state with the value of the new field.

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. These parameters are typically set once and never change. Implementations that change them during the connection MAY emit the recovery_parameters_set event more than once. The reordering_threshold field contains the packet threshold for loss detection, or "disabled" if packet-threshold loss detection is disabled.

QUICRecoveryParametersSet definition

Parameters that this document does not define, such as those of other loss detection and recovery algorithms, can be added through $$quic-recoveryparametersset-extension.

recovery_metrics_updated The recovery_metrics_updated event is emitted when one or more of the observable recovery metrics change value. It has Core importance level. Implementations SHOULD group all metric updates that happen at or around the same time into a single recovery_metrics_updated event. For example, if min_rtt and smoothed_rtt change at the same time, they are logged in one event, not two. Each event is only guaranteed to contain at least one of the listed metrics.

QUICRecoveryMetricsUpdated definition

To make logging easier, implementations MAY log values that are the same as previously reported values; for example, two consecutive recovery_metrics_updated events can report the same min_rtt. However, implementations SHOULD try to log only values that changed. Metrics that this document does not define, such as those of other loss detection and recovery algorithms, can be added through $$quic-recoverymetricsupdated-extension.

congestion_state_updated The congestion_state_updated event indicates when the congestion controller enters a new state that changes its behavior. It has Base importance level. This document does not define values for the event's fields. Congestion control algorithms have different states and different causes for moving between them, and stacks can implement the same algorithm differently. For example, the NewReno controller in has three states: slow start, recovery, and congestion avoidance.

QUICCongestionStateUpdated definition

The trigger field SHOULD be logged if a state change can have more than one cause. For example, NewReno enters recovery when it detects packet loss or when the ECN-CE count increases, so the trigger field shows which of the two caused the change.

packet_lost The packet_lost event is emitted when loss detection declares a packet lost. It has Core importance level.

QUICPacketLost definition

The frames field lists the frames that the lost packet carried. It is optional, because not all implementations keep sent packets in full. The data that is then marked for retransmission can be logged with the marked_for_retransmit event (). The is_mtu_probe_packet field marks a packet that was sent as a Path MTU probe. The loss of such a packet is not a reliable sign of congestion; see . It defaults to false. The trigger field SHOULD be logged. Its value shows how loss detection declared the packet lost:

• reordering_threshold: the packet threshold was exceeded; see .
• time_threshold: the time threshold was exceeded; see .
• pto_expired: the probe timeout expired, and the sender declared the packet lost instead of sending a probe; see .

marked_for_retransmit The marked_for_retransmit event indicates which data was marked for retransmission after packet loss was detected. It has Extra importance level. This single event covers all types of retransmittable data, which it logs using the existing QUIC frame definitions. A packet_lost event () records that a packet was declared lost, and can list the frames it carried. A marked_for_retransmit event records what the implementation then marks for retransmission. The two can differ, because not every frame is retransmitted (ACK and PADDING frames never are), and retransmitted data need not be sent in the same frames; see . An implementation that retransmits the frames of a lost packet unchanged can log them here, or skip this event and use the frames in the packet_lost event instead. An implementation with more complex logic, such as one that marks ranges of a stream's send buffer as in flight, or one that does not keep sent frames in full, can log frames that describe the data it marked for retransmission. These frames need not match any frame that was sent or will be sent. If an implementation logs packet_sent events, tools can infer much of this data from them. For example, overlapping stream offsets and lengths show 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

The trigger field can be used to log why the state changed, for example which ECN validation check in failed.

QUIC Data Type Definitions

QuicVersion

QuicVersion definition

ConnectionID

ConnectionID definition

Initiator

Initiator definition

IPAddressPort

IPAddressPort definition

TupleEndpointInfo TupleEndpointInfo describes one half, or direction, of a four-tuple. A full tuple has two halves: the server sends to the client's IP address and port, and the client sends to the server's IP address and port. Each direction uses its own destination connection ID. Structures that log tuple information SHOULD therefore include two TupleEndpointInfo instances, one for each half of the tuple.

TupleEndpointInfo definition

PacketType

PacketType definition

PacketNumberSpace

PacketNumberSpace definition

PacketHeader If a packet type has no known $PacketType string, packet_type can be "unknown", and packet_type_bytes then holds the numerical value without variable-length integer encoding. PacketHeader omits the fixed bit and the reserved bits because QUIC version 1 gives them fixed values; see . Their values can be logged in the raw.data field of the event that logs the PacketHeader. QUIC extensions that use these bits, such as the QUIC Bit greasing extension (), can log that use with new events, similar to spin_bit_updated, or with fields added to PacketHeader through $$quic-packetheader-extension. 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 is either a token from a Retry packet, or one that the server provided earlier in a NEW_TOKEN frame, for address validation in a later connection; see . Both kinds typically encode metadata that the server uses to check the token, but the metadata and its format are implementation-specific. The details field can log that metadata.

StatelessResetToken

StatelessResetToken definition

The stateless reset token is defined in .

KeyType

KeyType definition

ECN ECN holds the ECN codepoint carried in the IP header; see .

ECN definition

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 A PADDING frame is a single byte with the value 0, so each padding byte is its own frame; see . Logging each one as a separate PaddingFrame could add hundreds of entries to a single packet event, for example when a client pads an Initial packet to 1200 bytes. Implementations SHOULD instead log a single PaddingFrame for the packet, and set its raw.payload_length field to the number of PADDING frames in the packet.

PaddingFrame definition

PingFrame

PingFrame definition

AckFrame

AckFrame definition

The ranges in acked_ranges do not have to be in order; for example, [[5,9],[1,4]] is valid. The two numbers in a range can be equal; for example, [120,120] means that packet 120 was acknowledged. In that case, implementations SHOULD log [120] instead, and tools MUST handle both forms.

ResetStreamFrame If an error code has no known ApplicationError string, error can be "unknown", and error_code then holds the numerical value without variable-length integer encoding.

ResetStreamFrame definition

ResetStreamAtFrame The RESET_STREAM_AT frame is defined in . If an error code has no known ApplicationError string, error can be "unknown", and error_code then holds the numerical value without variable-length integer encoding.

ResetStreamAtFrame definition

StopSendingFrame If an error code has no known ApplicationError string, error can be "unknown", and error_code then holds the 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. The offset field defaults to 0, and the fin field defaults to false.

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 If an error code has no known string, error can be "unknown", and error_code then holds the numerical value without variable-length integer encoding. The trigger_frame_type field logs the Frame Type field, which only the transport variant of CONNECTION_CLOSE (type 0x1c) carries; see . A known frame type is logged as its frame type string, such as "stream". An unknown frame type is logged as the numerical value without variable-length integer encoding. The reason phrase in a CONNECTION_CLOSE frame is a byte sequence, which RFC 9000 recommends be UTF-8; see . The reason field holds the reason phrase as text, and reason_bytes holds the raw bytes, for example when the value is not UTF-8 or when an endpoint does not want to decode it. Implementations SHOULD log at least one form and MAY log both.

ConnectionCloseFrame definition

HandshakeDoneFrame

HandshakeDoneFrame definition

UnknownFrame The frame_type_bytes field holds the numerical value of the frame type 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 Application errors are defined by the application protocol that runs on top of QUIC, such as HTTP/3, so this document cannot list them. $ApplicationError is instead defined as a CDDL "type socket" extension point, with a single "unknown" value.

ApplicationError definition

Event schemas for application protocols MUST add their error strings by extending the $ApplicationError socket; see .

CryptoError RFC 9001 converts a TLS alert into a QUIC error code by adding the alert's AlertDescription value to 0x0100; see . A fixed list of strings does not fit this range well, so a CryptoError value is crypto_error_ followed by the resulting QUIC error code in lowercase hexadecimal, from crypto_error_0x100 to crypto_error_0x1ff. For example, a handshake_failure alert, which is 0x0128 in QUIC, is logged as crypto_error_0x128.

CryptoError definition

Handling Packet Coalescing Multiple QUIC packets can be coalesced into a single UDP datagram, especially during the handshake; see . Neither QUIC nor UDP provides a way to tell which packets shared a datagram. To let tools match QUIC packet events to UDP datagram events, the optional datagram_payload_checksum field carries a 32-bit CRC32c of the UDP payload, calculated as described in . The UDP datagram events carry one checksum per datagram, in their datagram_payload_checksums field.

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, which was 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, stream_data_moved, datagram_data_moved, datagram_dropped, connection_data_blocked_updated, stream_data_blocked_updated, datagram_data_blocked_updated, migration_state_updated, timer_updated, key_updated, key_discarded, recovery_parameters_set, recovery_metrics_updated, congestion_state_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. Fastly QUIC defines a RESET_STREAM frame to abort sending on a stream. When a sender resets a stream, it also stops retransmitting STREAM frames for this stream in the event of packet loss. On the receiving side, there is no guarantee that any data sent on that stream is delivered. This document defines a new QUIC frame, the RESET_STREAM_AT frame, that allows resetting a stream, while guaranteeing delivery of stream data up to a certain byte offset. 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. Transport protocols are extended through the use of transport header options. This document updates RFC 768 (UDP) by indicating the location, syntax, and semantics for UDP transport layer options within the surplus area after the end of the UDP user data but before the end of the IP datagram. 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-13:

• Added datagram_dropped (#550)
• Wide range of editorial and consistency changes

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)