Internet-Draft | QUIC event definitions for qlog | October 2024 |
Marx, et al. | Expires 24 April 2025 | [Page] |
- Workgroup:
- QUIC
- Internet-Draft:
- draft-ietf-quic-qlog-quic-events-09
- Published:
- Intended Status:
- Standards Track
- Expires:
QUIC event definitions for qlog
Abstract
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.¶
Concrete examples of integrations of this schema in various programming languages can be found at https://github.com/quiclog/qlog/.¶
Status of This Memo
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 24 April 2025.¶
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
1. Introduction
This document defines a qlog event schema (Section 8 of [QLOG-MAIN]) containing concrete events for the core QUIC protocol (see [QUIC-TRANSPORT], [QUIC-RECOVERY], and [QUIC-TLS]) and some of its extensions (see [QUIC-DATAGRAM] and [GREASEBIT]).¶
The event namespace with identifier quic
is defined; see Section 2. In
this namespace multiple events derive from the qlog abstract Event class
(Section 7 of [QLOG-MAIN]), 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.¶
When any event from this document is included in a qlog trace, the
protocol_types
qlog array field MUST contain an entry with the value "QUIC":¶
1.1. 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).¶
1.2. 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 [QLOG-MAIN]) related to QUIC packets, the AEAD tag is regarded as a trailer.¶
1.3. 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 Section 5.7
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).¶
1.4. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The event and data structure definitions in ths document are expressed in the Concise Data Definition Language [CDDL] and its extensions described in [QLOG-MAIN].¶
The following fields from [QLOG-MAIN] are imported and used: name, namespace, type, data, group_id, protocol_types, importance, RawInfo, and time-related fields.¶
As is the case for [QLOG-MAIN], the qlog schema definitions in this document are intentionally agnostic to serialization formats. The choice of format is an implementation decision.¶
2. 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
Section 8 of [QLOG-MAIN], this document registers the quic
namespace. The
event schema URI is urn:ietf:params:qlog:events:quic
.¶
2.1. Draft Event Schema Identification
This section is to be removed before publishing as an RFC.¶
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.¶
3. QUIC Event Overview
Table 1 summarizes the name value of each event type that is defined in this specification.¶
Name value | Importance | Definition |
---|---|---|
quic:server_listening | Extra | Section 4.1 |
quic:connection_started | Base | Section 4.2 |
quic:connection_closed | Base | Section 4.3 |
quic:connection_id_updated | Base | Section 4.4 |
quic:spin_bit_updated | Base | Section 4.5 |
quic:connection_state_updated | Base | Section 4.6 |
quic:path_assigned | Base | Section 4.7 |
quic:mtu_updated | Extra | Section 4.8 |
quic:version_information | Core | Section 5.1 |
quic:alpn_information | Core | Section 5.2 |
quic:parameters_set | Core | Section 5.3 |
quic:parameters_restored | Base | Section 5.4 |
quic:packet_sent | Core | Section 5.5 |
quic:packet_received | Core | Section 5.6 |
quic:packet_dropped | Base | Section 5.7 |
quic:packet_buffered | Base | Section 5.8 |
quic:packets_acked | Extra | Section 5.9 |
quic:udp_datagrams_sent | Extra | Section 5.10 |
quic:udp_datagrams_received | Extra | Section 5.11 |
quic:udp_datagram_dropped | Extra | Section 5.12 |
quic:stream_state_updated | Base | Section 5.13 |
quic:frames_processed | Extra | Section 5.14 |
quic:stream_data_moved | Base | Section 5.15 |
quic:datagram_data_moved | Base | Section 5.16 |
quic:migration_state_updated | Extra | Section 5.17 |
quic:key_updated | Base | Section 6.1 |
quic:key_discarded | Base | Section 6.2 |
quic:recovery_parameters_set | Base | Section 7.1 |
quic:recovery_metrics_updated | Core | Section 7.2 |
quic:congestion_state_updated | Base | Section 7.3 |
quic:loss_timer_updated | Extra | Section 7.4 |
quic:packet_lost | Core | Section 7.5 |
quic:marked_for_retransmit | Extra | Section 7.6 |
quic:ecn_state_updated | Extra | Section 7.7 |
QUIC events extend the $ProtocolEventData
extension point defined in
[QLOG-MAIN]. Additionally, they allow for direct extensibility by their use of
per-event extension points via the $$
CDDL "group socket" syntax, as also
described in [QLOG-MAIN].¶
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.¶
4. Connectivity events
4.1. server_listening
Emitted when the server starts accepting connections. It has Extra importance level; see Section 9.2 of [QLOG-MAIN].¶
Some QUIC stacks do not handle sockets directly and are thus unable to log IP and/or port information.¶
4.2. 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 event is separate event
in order to capture additional data that can be useful to log. It has Base
importance level; see Section 9.2 of [QLOG-MAIN].¶
Some QUIC stacks do not handle sockets directly and are thus unable to log IP and/or port information.¶
4.3. 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; see
Section 9.2 of [QLOG-MAIN].¶
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, 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.¶
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.¶
4.4. 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; see Section 9.2 of [QLOG-MAIN].¶
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 owner field will be "remote". When the endpoint updates its
own connection ID, the owner field will be "local".¶
4.5. spin_bit_updated
The spin_bit_updated
event conveys information about the QUIC latency spin
bit; see Section 17.4 of [QUIC-TRANSPORT]. 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; see Section 9.2 of [QLOG-MAIN].¶
4.6. 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; see Section 9.2 of [QLOG-MAIN].¶
[QUIC-TRANSPORT] 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.¶
The connection_state_changed
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.¶
4.7. path_assigned
Importance: Base¶
This event is used to associate a single PathID's value with other parameters that describe a unique network path.¶
As described in [QLOG-MAIN], each qlog event can be linked to a single network path by means of the top-level "path" field, whose value is a PathID. However, since it can be cumbersome to encode additional path metadata (such as IP addresses or Connection IDs) directly into the PathID, this event allows such an association to happen separately. As such, PathIDs can be short and unique, and can even be updated to be associated with new metadata as the connection's state evolves.¶
Definition:¶
Choosing the different path_id
values is left up to the implementation. Some
options include using a uniquely incrementing integer, using the (first)
Destination Connection ID associated with a path (or its sequence number), or
using (a hash of) the two endpoint IP addresses.¶
It is important to note that the empty string ("") is a valid PathID and that it
is the default assigned to events that do not explicitly set a "path" field. Put
differently, the initial path of a QUIC connection on which the handshake occurs
(see also Section 4.2) is implicitly associated with the PathID
with value "". Associating metadata with this default path is possible by
logging the QUICPathAssigned event with a value of "" for the path_id
field.¶
As paths and their metadata can evolve over time, multiple QUICPathAssigned
events can be emitted for each unique PathID. The latest event contains the most
up-to-date information for that PathID. As such, the first time a PathID is seen
in a QUICPathAssigned event, it is an indication that the path is
created. Subsequent occurrences indicate the path is updated, while a final
occurrence with both path_local
and path_remote
fields omitted implicitly
indicates the path has been abandoned.¶
4.8. 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; see Section 9.2 of [QLOG-MAIN].¶
5. Transport events
5.1. version_information
The version_information
event supports QUIC version negotiation; see Section 6 of [QUIC-TRANSPORT]. It has Core importance level; see Section 9.2 of [QLOG-MAIN].¶
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.¶
Intended use:¶
- When sending an initial, the client logs this event with
client_versions
andchosen_version
set¶ - Upon receiving a client initial with a supported version, the server logs this
event with
server_versions
andchosen_version
set¶ - Upon receiving a client initial with an unsupported version, the server logs
this event with
server_versions
set andclient_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 andserver_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 ofserver_versions
with no viable overlap with its own supported versions, this event should be logged without thechosen_version
set¶
5.2. alpn_information
The alpn_information
event supports Application-Layer Protocol Negotiation
(ALPN) over the QUIC transport; see [RFC7301] and Section 7.4 of [QUIC-TRANSPORT]. It has Core importance level; see Section 9.2 of [QLOG-MAIN].¶
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 possible to present as UTF-8.
The ALPNIdentifier
` type supports either format. Implementations SHOULD log at
least one format, but MAY log both or none.¶
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
andchosen_alpn
set.¶
5.3. 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; see Section 9.2 of [QLOG-MAIN].¶
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 owner
field. As such, this field MUST be
correct for all settings included a single event instance. If you need to log
settings from two sides, you MUST emit two separate event instances.¶
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 Section 7.4.2 of [QUIC-TRANSPORT]. 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.¶
5.4. 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; see Section 9.2 of [QLOG-MAIN].¶
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.¶
5.5. packet_sent
The packet_sent
event indicates a QUIC-level packet was sent. It has Core
importance level; see Section 9.2 of [QLOG-MAIN].¶
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
Section 5.10.¶
5.6. packet_received
The packet_received
event indicates a QUIC-level packet was received. It has
Core importance level; see Section 9.2 of [QLOG-MAIN].¶
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
Section 5.10.¶
5.7. packet_dropped
The packet_dropped
event indicates a QUIC-level packet was dropped. It has
Base importance level; see Section 9.2 of [QLOG-MAIN].¶
The trigger field indicates a general reason category for dropping the packet, while the details field can contain additional implementation-specific information.¶
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 Section 1.3.¶ -
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
Section 5.10.¶
5.8. 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; see Section 9.2 of [QLOG-MAIN].¶
The datagram_id
field is used to track packet coalescing, see
Section 5.10.¶
5.9. 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; see Section 9.2 of [QLOG-MAIN].¶
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.¶
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.¶
5.10. udp_datagrams_sent
The 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; see
Section 9.2 of [QLOG-MAIN].¶
Since QUIC implementations rarely control UDP logic directly, the raw data excludes UDP-level headers in all RawInfo fields.¶
Multiple QUIC packets can be coalesced in a single UDP datagram, especially
during the handshake (see Section 12.2 of [QUIC-TRANSPORT]). 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.¶
5.11. 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; see Section 9.2 of [QLOG-MAIN].¶
The datagram_ids
field is used to track packet coalescing, see
Section 5.10.¶
5.12. 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 (Section 5.7) should be
used instead. The event has Extra importance level; see Section 9.2 of [QLOG-MAIN].¶
5.13. stream_state_updated
The stream_state_updated
event is emitted whenever the internal state of a
QUIC stream is updated; see Section 3 of [QUIC-TRANSPORT]. Most of this can be
inferred from several types of frames going over the wire, but it's much easier
to have explicit signals for these state changes. The event has Base importance
level; see Section 9.2 of [QLOG-MAIN].¶
QUIC implementations SHOULD mainly log the simplified (HTTP/2-alike) 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.¶
5.14. frames_processed
The frame_processed
event is intended to prevent a large proliferation of
specific purpose events (e.g., packets_acknowledged
, flow_control_updated
,
stream_data_received
). It has Extra importance level; see Section 9.2 of [QLOG-MAIN].¶
Implementations have the opportunity to (selectively) log this type of
signal without having to log packet-level details (e.g., in packet_received
).
Since for almost all cases, the effects of applying a frame to the internal state
of an implementation can be inferred from that frame's contents, these events
are aggregated into this single frames_processed
event.¶
The frame_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, then logged with
this event).¶
The packet_received
event can convey all constituent frames. It is not
expected that the frames_processed
event will also be used for a redundant
purpose. Rather, implementations can use this event to avoid having to log full
packets or to convey extra information about when frames are processed (for
example, if frame processing is deferred for any reason).¶
Note that for some events, this approach will lose some information (e.g., for which
encryption level are packets being acknowledged?). If this information is
important, the packet_received
event can be used instead.¶
In some implementations, it can be difficult to log frames directly, even when
using packet_sent
and packet_received
events. For these cases, the
frames_processed
event also contains the packet_numbers
field, which can be
used to more explicitly link this event to the packet_sent
/received events
.
The field is an array, which supports using a single frames_processed
event
for multiple frames received over multiple packets. To map between frames and
packets, the position and order of entries in the frames
and packet_numbers
is used. If the optional packet_numbers
field is used, each 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 would have the fields serialized as:¶
"frames":[ {"frame_type":"stream","stream_id":0,"offset":0,"length":500}, {"frame_type":"stream","stream_id":0,"offset":500,"length":200}, {"frame_type":"stream","stream_id":1,"offset":0,"length":300}, {"frame_type":"stream","stream_id":1,"offset":300,"length":50} ], "packet_numbers":[ 1, 1, 2, 2 ]¶
5.15. 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; see Section 9.2 of [QLOG-MAIN].¶
This event relates to stream data only. There are no packet or frame headers and
length values in the length
or raw
fields 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 reset_stream
.
In both cases, the length-carrying fields (length
or raw
) can be
omitted or contain zero values.¶
This event is only for data in QUIC streams. For data in QUIC Datagram Frames,
see the datagram_data_moved
event defined in Section 5.16.¶
5.16. datagram_data_moved
The datagram_data_moved
event is used to indicate when QUIC Datagram Frame
data (see [RFC9221]) 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;
see Section 9.2 of [QLOG-MAIN].¶
This event relates to datagram data only. There are no packet or frame headers and
length values in the length
or raw
fields 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 Section 5.15.¶
5.17. 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 QUICPathAssigned 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; see Section 9.2 of [QLOG-MAIN].¶
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 QUICPathAssigned events, to serve as a ground-truth source of information.¶
Definition:¶
6. Security Events
6.1. key_updated
The key_updated
event has Base importance level; see Section 9.2 of [QLOG-MAIN].¶
Note that the key_phase is the full value of the key phase (as indicated by @M and @N in Figure 9 of [QUIC-TLS]). The key phase bit used on the packet header is the least significant bit of the key phase.¶
6.2. key_discarded
The key_discarded
event has Base importance level; see Section 9.2 of [QLOG-MAIN].¶
7. 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).¶
7.1. 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; see Section 9.2 of [QLOG-MAIN].¶
All these settings are typically set once and never change. Implementation that
do, for some reason, change these parameters during execution, MAY emit the
recovery_parameters_set
event more than once.¶
Additionally, this event can contain any number of unspecified fields to support different recovery approaches.¶
7.2. 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; see Section 9.2 of [QLOG-MAIN].¶
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.¶
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.¶
7.3. 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; see Section 9.2 of [QLOG-MAIN].¶
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.¶
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).¶
7.4. loss_timer_updated
The loss_timer_updated
event is emitted when a recovery loss timer changes
state. It has Extra importance level; see Section 9.2 of [QLOG-MAIN].¶
The three main event types are:¶
- set: the timer is set with a delta timeout for when it will trigger next¶
- expired: when the timer effectively expires after the delta timeout¶
- cancelled: when a timer is cancelled (e.g., all outstanding packets are acknowledged, start idle period)¶
In order to indicate an active timer's timeout update, a new set
event is used.¶
7.5. packet_lost
The packet_lost
event is emitted when a packet is deemed lost by loss
detection. It has Core importance level; see Section 9.2 of [QLOG-MAIN].¶
It is RECOMMENDED to populate the optional trigger
field in order to help
disambiguate among the various possible causes of a loss declaration.¶
7.6. 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; see Section 9.2 of [QLOG-MAIN].¶
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).¶
7.7. ecn_state_updated
The ecn_state_updated
event indicates a progression in the ECN state machine
as described in section A.4 of [QUIC-TRANSPORT]. It has Extra importance
level; see Section 9.2 of [QLOG-MAIN].¶
8. QUIC data type definitions
8.5. PathEndpointInfo
PathEndpointInfo indicates a single half/direction of a path. A full path is comprised of two halves. Firstly: the server sends to the remote client IP + port using a specific destination Connection ID. Secondly: the client sends to the remote server IP + port using a different destination Connection ID.¶
As such, structures logging path information SHOULD include two different PathEndpointInfo instances, one for each half of the path.¶
8.9. Token
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.¶
8.10. Stateless Reset Token
The stateless reset token is carried in stateless reset packets, in transport parameters and in NEW_CONNECTION_ID frames.¶
8.13. 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.¶
The QUIC frame types defined in this document are as follows:¶
8.13.1. 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 payload_length property to the amount of PADDING bytes/frames included in the packet.¶
8.13.3. AckFrame
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.¶
8.13.19. 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. For unknown
frame types, the numerical value without variable-length integer encoding is
used.¶
The CONNECTION_CLOSE reason phrase is a byte sequences. 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.¶
8.13.21. UnknownFrame
The frame_type_bytes field is the numerical value without variable-length integer encoding.¶
8.13.22. DatagramFrame
The QUIC DATAGRAM frame is defined in Section 4 of [RFC9221].¶
8.13.23. TransportError
The generic $TransportError
is defined here as a CDDL "type socket" extension
point. It can be extended to support additional Transport errors.¶
8.13.24. 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 directly. It is instead defined as an empty CDDL "type socket" extension point.¶
Application-level qlog definitions that wish to define new ApplicationError strings MUST do so by extending the $ApplicationError socket as such:¶
$ApplicationError /= "new_error_name" / "another_new_error_name"¶
8.13.25. 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.¶
9. Security and Privacy Considerations
The security and privacy considerations discussed in [QLOG-MAIN] apply to this document as well.¶
10. IANA Considerations
This document registers a new entry in the "qlog event schema URIs" registry:¶
- 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,path_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_processed,stream_data_moved,datagram_data_moved,migration_state_updated,key_updated,key_discarded,recovery_parameters_set,recovery_metrics_updated,congestion_state_updated,loss_timer_updated,packet_lost,marked_for_retransmit,ecn_state_updated¶
- Description:
-
Event definitions related to the QUIC transport protocol.¶
- Reference:
-
This Document¶
11. References
11.1. Normative References
- [CDDL]
- Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, , <https://www.rfc-editor.org/rfc/rfc8610>.
- [GREASEBIT]
- Thomson, M., "Greasing the QUIC Bit", RFC 9287, DOI 10.17487/RFC9287, , <https://www.rfc-editor.org/rfc/rfc9287>.
- [QLOG-MAIN]
- Marx, R., Niccolini, L., Seemann, M., and L. Pardue, "qlog: Structured Logging for Network Protocols", Work in Progress, Internet-Draft, draft-ietf-quic-qlog-main-schema-09, , <https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-main-schema-09>.
- [QUIC-DATAGRAM]
- Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable Datagram Extension to QUIC", RFC 9221, DOI 10.17487/RFC9221, , <https://www.rfc-editor.org/rfc/rfc9221>.
- [QUIC-RECOVERY]
- Iyengar, J., Ed. and I. Swett, Ed., "QUIC Loss Detection and Congestion Control", RFC 9002, DOI 10.17487/RFC9002, , <https://www.rfc-editor.org/rfc/rfc9002>.
- [QUIC-TLS]
- Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure QUIC", RFC 9001, DOI 10.17487/RFC9001, , <https://www.rfc-editor.org/rfc/rfc9001>.
- [QUIC-TRANSPORT]
- Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, , <https://www.rfc-editor.org/rfc/rfc9000>.
- [RFC2119]
- Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
- [RFC8174]
- Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
- [RFC9221]
- Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable Datagram Extension to QUIC", RFC 9221, DOI 10.17487/RFC9221, , <https://www.rfc-editor.org/rfc/rfc9221>.
11.2. Informative References
- [RFC7301]
- Friedl, S., Popov, A., Langley, A., and E. Stephan, "Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, , <https://www.rfc-editor.org/rfc/rfc7301>.
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 and Jonathan Lennox for their feedback and suggestions.¶
Change Log
This section is to be removed before publishing as an RFC.¶
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
toquic:recovery_metrics_updated
andrecovery:parameters_set
toquic:recovery_parameters_set
(#439)¶ - Added
unknown_parameters
field toparameters_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-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)¶