QUIC R. Marx
Internet-Draft Hasselt University
Intended status: Standards Track July 03, 2019
Expires: January 4, 2020
QUIC and HTTP/3 event definitions for qlog
draft-marx-qlog-event-definitions-quic-h3-00
Abstract
This document describes concrete qlog event definitions and their
metadata for QUIC and HTTP/3-related events. These events can then
be embedded in the higher level schema defined in draft-marx-quic-
logging-main-schema-latest.
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 January 4, 2020.
Copyright Notice
Copyright (c) 2019 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 Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Marx Expires January 4, 2020 [Page 1]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. QUIC event definitions . . . . . . . . . . . . . . . . . . . 4
3.1. CONNECTIVITY . . . . . . . . . . . . . . . . . . . . . . 4
3.1.1. CONNECTION_ATTEMPT . . . . . . . . . . . . . . . . . 4
3.1.2. CONNECTION_NEW . . . . . . . . . . . . . . . . . . . 4
3.1.3. CONNECTION_ID_UPDATE . . . . . . . . . . . . . . . . 5
3.1.4. MIGRATION-related events . . . . . . . . . . . . . . 5
3.1.5. CONNECTION_CLOSED . . . . . . . . . . . . . . . . . . 5
3.2. SECURITY . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2.1. HEADER_DECRYPT_ERROR . . . . . . . . . . . . . . . . 5
3.2.2. PACKET_DECRYPT_ERROR . . . . . . . . . . . . . . . . 5
3.2.3. KEY_UPDATE . . . . . . . . . . . . . . . . . . . . . 5
3.2.4. KEY_RETIRED . . . . . . . . . . . . . . . . . . . . . 5
3.2.5. CIPHER_UPDATE . . . . . . . . . . . . . . . . . . . . 5
3.3. TRANSPORT . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3.1. PACKET_SENT . . . . . . . . . . . . . . . . . . . . . 5
3.3.2. PACKET_RECEIVED . . . . . . . . . . . . . . . . . . . 6
3.3.3. PACKET_DROPPED . . . . . . . . . . . . . . . . . . . 6
3.3.4. VERSION_UPDATE . . . . . . . . . . . . . . . . . . . 7
3.3.5. TRANSPORT_PARAMETERS_UPDATE . . . . . . . . . . . . . 7
3.3.6. ALPN_UPDATE . . . . . . . . . . . . . . . . . . . . . 7
3.3.7. STREAM_STATE_UPDATE . . . . . . . . . . . . . . . . . 7
3.3.8. FLOW_CONTROL_UPDATE . . . . . . . . . . . . . . . . . 8
3.4. RECOVERY . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4.1. CC_STATE_UPDATE . . . . . . . . . . . . . . . . . . . 8
3.4.2. METRIC_UPDATE . . . . . . . . . . . . . . . . . . . . 8
3.4.3. LOSS_ALARM_SET . . . . . . . . . . . . . . . . . . . 9
3.4.4. LOSS_ALARM_FIRED . . . . . . . . . . . . . . . . . . 9
3.4.5. PACKET_LOST . . . . . . . . . . . . . . . . . . . . . 9
3.4.6. PACKET_ACKNOWLEDGED . . . . . . . . . . . . . . . . . 9
3.4.7. PACKET_RETRANSMIT . . . . . . . . . . . . . . . . . . 10
4. HTTP/3 event definitions . . . . . . . . . . . . . . . . . . 10
4.1. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2. QPACK . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3. PRIORITIZATION . . . . . . . . . . . . . . . . . . . . . 10
4.4. PUSH . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . 10
7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Appendix A. QUIC DATA type definitions . . . . . . . . . . . . . 11
A.1. PacketType . . . . . . . . . . . . . . . . . . . . . . . 11
A.2. PacketHeader . . . . . . . . . . . . . . . . . . . . . . 11
Marx Expires January 4, 2020 [Page 2]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
A.3. QUIC Frames . . . . . . . . . . . . . . . . . . . . . . . 11
A.3.1. AckFrame . . . . . . . . . . . . . . . . . . . . . . 11
A.3.2. StreamFrame . . . . . . . . . . . . . . . . . . . . . 12
A.3.3. ResetStreamFrame . . . . . . . . . . . . . . . . . . 12
A.3.4. ConnectionCloseFrame . . . . . . . . . . . . . . . . 13
A.3.5. MaxDataFrame . . . . . . . . . . . . . . . . . . . . 13
A.3.6. MaxStreamDataFrame . . . . . . . . . . . . . . . . . 13
A.3.7. UnknownFrame . . . . . . . . . . . . . . . . . . . . 13
A.3.8. TransportError . . . . . . . . . . . . . . . . . . . 13
Appendix B. HTTP/3 DATA type definitions . . . . . . . . . . . . 14
B.1. ApplicationError . . . . . . . . . . . . . . . . . . . . 14
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 15
C.1. Since draft-marx-qlog-event-definitions-quic-h3-00-00: . 15
Appendix D. Design Variations . . . . . . . . . . . . . . . . . 15
Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction
Feedback and discussion welcome at https://github.com/quiclog/
internet-drafts
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2. Overview
This document describes the values of the qlog CATEGORY, EVENT_TYPE,
TRIGGER and DATA fields and their semantics for the QUIC and HTTP/3
protocols. The definitions included in this file are assumed to be
used in qlog's "trace" containers, where the trace's "protocol_type"
field MUST be set to "QUIC_HTTP3".
This document is based on draft-20 of the QUIC and HTTP/3 I-Ds QUIC-
TRANSPORT [QUIC-HTTP].
This document uses the "TypeScript" language [1] to describe its
schema in. We use TypeScript because it is less verbose than JSON-
schema and almost as expressive. It also makes it easier to include
these definitions directly into a web-based tool. The main
conventions a reader should be aware of are:
o obj? : this object is optional
Marx Expires January 4, 2020 [Page 3]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
o type1 | type2 : a union of these two types (object can be either
type1 OR type2)
o obj:type : this object has this concrete type
o obj[] : this object is an array (which can contain any type of
object)
o obj:Array<type> : this object is an array of this type
o number : identifies either an integer, float or double in
TypeScript. In this document, number always means an integer.
o Unless explicity defined, the value of an enum entry is the string
version of its name (e.g., INITIAL = "INITIAL")
o Many numerical fields have type "string" instead of "number".
This is because many JSON implementations only support integers up
to 2^53-1 (MAX_INTEGER for JavaScript without BigInt support),
which is less than QUIC's VLIE types (2^62-1). Each VLIE field is
thus a string, where a number would be semantically more correct.
Unless mentioned otherwise (e.g., for connection IDs), numerical
fields that are logged as strings (e.g., packet numbers) MUST be
logged in decimal (base-10) format. TODO: see issue 10
o TODO: list all possible triggers per event type
o TODO: make it clear which events are "normal" and which are "only
if you really need this" (normal = probably TRANSPORT TX/RX and
RECOVERY basics and HTTP basics)
3. QUIC event definitions
o TODO: flesh out the definitions for most of these
o TODO: add all definitions for HTTP3 and QPACK events
3.1. CONNECTIVITY
3.1.1. CONNECTION_ATTEMPT
TODO: specify how this works with happy eyeballs
3.1.2. CONNECTION_NEW
Marx Expires January 4, 2020 [Page 4]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
3.1.3. CONNECTION_ID_UPDATE
TODO: mention that CIDs can be logged in hex
3.1.4. MIGRATION-related events
e.g., PATH_UPDATE
TODO: read up on the draft how migration works and whether to best
fit this here or in TRANSPORT
3.1.5. CONNECTION_CLOSED
3.2. SECURITY
3.2.1. HEADER_DECRYPT_ERROR
{ mask, error }
3.2.2. PACKET_DECRYPT_ERROR
{ key, error }
3.2.3. KEY_UPDATE
{ type = "Initial | handshake | 1RTT", value }
3.2.4. KEY_RETIRED
{ value } # initial encryption level is implicitly deleted
3.2.5. CIPHER_UPDATE
3.3. TRANSPORT
3.3.1. PACKET_SENT
Triggers:
o "DEFAULT"
o "RETRANSMIT_REORDERING" // draft-19 6.1.1
o "RETRANSMIT_TIMEOUT" // draft-19 6.1.2
o "RETRANSMIT_CRYPTO" // draft-19 6.2
o "RETRANSMIT_PTO" // draft-19 6.3
Marx Expires January 4, 2020 [Page 5]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
o "CC_BANDWIDTH_PROBE" // needed for some CCs to figure out
bandwidth allocations when there are no normal sends
Data:
{
packet_type:PacketType,
header:PacketHeader,
frames:Array<QuicFrame>
}
Notes:
o We don't explicitly log the encryption_level or
packet_number_space: the packet_type specifies this by inference
(assuming correct implementation)
3.3.2. PACKET_RECEIVED
Triggers:
o "DEFAULT"
Data:
{
packet_type:PacketType,
header:PacketHeader,
frames:Array<QuicFrame>
}
Notes:
o We don't explicitly log the encryption_level or
packet_number_space: the packet_type specifies this by inference
(assuming correct implementation)
3.3.3. PACKET_DROPPED
Can be due to several reasons * TODO: How does this relate to
HEADER_DECRYPT_ERROR and PACKET_DECRYPT_ERROR? * TODO: if a packet is
dropped because we don't have a connection for it, how can we add it
to a given trace in the overall qlog file? Need a sort of catch-call
trace in each file? * TODO: differentiate between DATAGRAM_DROPPED
and PACKET_DROPPED? Same with PACKET_RECEIVED and DATAGRAM_RECEIVED?
Marx Expires January 4, 2020 [Page 6]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
3.3.4. VERSION_UPDATE
TODO: maybe name VERSION_SELECTED ?
3.3.5. TRANSPORT_PARAMETERS_UPDATE
3.3.6. ALPN_UPDATE
TODO: should this be in HTTP?
{ alpn:string }
3.3.7. STREAM_STATE_UPDATE
{
old:string,
new:string
}
Possible values:
o IDLE
o OPEN
o CLOSED
o HALF_CLOSED_REMOTE
o HALF_CLOSED_LOCAL
o DESTROYED // memory actually freed
o Ready
o Send
o Data Sent
o Reset Sent
o Data Rcvd
o Reset Rcvd
o Recv
o Size Known
Marx Expires January 4, 2020 [Page 7]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
o Data Rcvd
o Data Read
o Reset Read
TODO: do we need all of these? How do implementations actually
handle this in practice?
3.3.8. FLOW_CONTROL_UPDATE
o type = connection
o type = stream + id = streamid
TODO: check state machine in QUIC transport draft
3.4. RECOVERY
3.4.1. CC_STATE_UPDATE
{
old:string,
new:string
}
3.4.2. METRIC_UPDATE
{
cwnd?: number;
bytes_in_flight?:number;
min_rtt?:number;
smoothed_rtt?:number;
latest_rtt?:number;
max_ack_delay?:number;
rtt_variance?:number;
ssthresh?:number;
pacing_rate?:number;
}
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 METRIC_UPDATE entry, rather than split out into two).
Marx Expires January 4, 2020 [Page 8]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
Consequently, a METRIC_UPDATE is only guaranteed to contain at least
one of the listed metrics.
Note: to make logging easier, implementations MAY log values even if
they are the same as previously reported values (e.g., two subsequent
METRIC_UPDATE entries can both report the exact same value for
min_rtt). However, applications SHOULD try to log only actual
updates to values.
o TODO: split these up into separate events? e.g., CWND_UPDATE,
BYTES_IN_FLIGHT_UPDATE, ...
o TODO: move things like pacing_rate, cwnd, bytes_in_flight,
ssthresh, etc. to CC_STATE_UPDATE?
o TODO: what types of CC metrics do we need to support by default
(e.g., cubic vs bbr)
3.4.3. LOSS_ALARM_SET
3.4.4. LOSS_ALARM_FIRED
3.4.5. PACKET_LOST
Data:
{
packet_number:string
}
Triggers:
o "UNKNOWN",
o "REORDERING_THRESHOLD",
o "TIME_THRESHOLD"
3.4.6. PACKET_ACKNOWLEDGED
TODO: must this be a separate event? can't we get this from logged
ACK frames? (however, explicitly indicating this and logging it in
the ack handler is a better signal that the ACK actually had the
intended effect than just logging its receipt)
Marx Expires January 4, 2020 [Page 9]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
3.4.7. PACKET_RETRANSMIT
TODO: only if a packet is retransmit in-full, which many stacks don't
do. Need something more flexible.
4. HTTP/3 event definitions
4.1. HTTP
4.2. QPACK
4.3. PRIORITIZATION
4.4. PUSH
5. Security Considerations
TBD
6. IANA Considerations
TBD
7. References
7.1. Normative References
[QUIC-HTTP]
Bishop, M., Ed., "Hypertext Transfer Protocol Version 3
(HTTP/3)", draft-ietf-quic-http-20 (work in progress),
April 2019.
[QUIC-TRANSPORT]
Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
Multiplexed and Secure Transport", draft-ietf-quic-
transport-20 (work in progress), April 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
7.2. URIs
[1] https://www.typescriptlang.org/
Marx Expires January 4, 2020 [Page 10]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
Appendix A. QUIC DATA type definitions
A.1. PacketType
enum PacketType {
INITIAL,
HANDSHAKE,
ZERORTT = "0RTT",
ONERTT = "1RTT",
RETRY,
VERSION_NEGOTIATION,
UNKOWN
}
A.2. PacketHeader
class PacketHeader {
packet_number: string;
packet_size?: number;
payload_length?: number;
// only if present in the header
// if correctly using NEW_CONNECTION_ID events,
// dcid can be skipped for 1RTT packets
version?: string;
scil?: string;
dcil?: string;
scid?: string;
dcid?: string;
// Note: short vs long header is implicit through PacketType
}
A.3. QUIC Frames
type QuicFrame = AckFrame | StreamFrame | ResetStreamFrame | ConnetionCloseFrame | MaxDataFrame | MaxStreamDataFrame | UnknownFrame;
A.3.1. AckFrame
Marx Expires January 4, 2020 [Page 11]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
class AckFrame{
frame_type:string = "ACK";
ack_delay:string;
// first number is "from": lowest packet number in interval
// second number is "to": up to and including // highest packet number in interval
// e.g., looks like [[1,2],[4,5]]
acked_ranges:Array<[number, number]>;
ect1?:string;
ect0?:string;
ce?:string;
}
Note: 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: the two numbers in the packet range can be the same (e.g.,
[120,120] means that packet with number 120 was ACKed). TODO: maybe
make this into just [120]?
A.3.2. StreamFrame
class StreamFrame{
frame_type:string = "STREAM";
id:string;
// These two MUST always be set
// If not present in the Frame type, log their default values
offset:string;
length:string;
// this MAY be set any time, but MUST only be set if the value is "true"
// if absent, the value MUST be assumed to be "false"
fin:boolean;
}
A.3.3. ResetStreamFrame
class ResetStreamFrame{
frame_type:string = "RESET_STREAM";
id:string;
error_code:ApplicationError | number;
final_offset:string;
}
Marx Expires January 4, 2020 [Page 12]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
A.3.4. ConnectionCloseFrame
type ErrorSpace = "TRANSPORT" | "APPLICATION";
class ConnectionCloseFrame{
frame_type:string = "CONNECTION_CLOSE";
error_space:ErrorSpace;
error_code:TransportError | ApplicationError | number;
reason:string;
trigger_frame_type?:number; // TODO: should be more defined, but we don't have a FrameType enum atm...
}
A.3.5. MaxDataFrame
class MaxDataFrame{
stream_type:string = "MAX_DATA";
maximum:string;
}
A.3.6. MaxStreamDataFrame
class MaxStreamDataFrame{
stream_type:string = "MAX_STREAM_DATA";
id:string;
maximum:string;
}
A.3.7. UnknownFrame
class UnknownFrame{
frame_type:string = "UNKNOWN";
}
A.3.8. TransportError
Marx Expires January 4, 2020 [Page 13]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
enum TransportError {
NO_ERROR,
INTERNAL_ERROR,
SERVER_BUSY,
APPLICATION_FLOW_CONTROL_ERROR, // 0x3
STREAM_FLOW_CONTROL_ERROR, // 0x4
STREAM_STATE_ERROR,
FINAL_SIZE_ERROR,
FRAME_ENCODING_ERROR,
TRANSPORT_PARAMETER_ERROR,
PROTOCOL_VIOLATION,
INVALID_MIGRATION,
CRYPTO_ERROR
}
Appendix B. HTTP/3 DATA type definitions
B.1. ApplicationError
enum ApplicationError{
HTTP_NO_ERROR,
HTTP_WRONG_SETTING_DIRECTION,
HTTP_PUSH_REFUSED,
HTTP_INTERNAL_ERROR,
HTTP_PUSH_ALREADY_IN_CACHE,
HTTP_REQUEST_CANCELLED,
HTTP_INCOMPLETE_REQUEST,
HTTP_CONNECT_ERROR,
HTTP_EXCESSIVE_LOAD,
HTTP_VERSION_FALLBACK,
HTTP_WRONG_STREAM,
HTTP_LIMIT_EXCEEDED,
HTTP_DUPLICATE_PUSH,
HTTP_UNKNOWN_STREAM_TYPE,
HTTP_WRONG_STREAM_COUNT,
HTTP_CLOSED_CRITICAL_STREAM,
HTTP_WRONG_STREAM_DIRECTION,
HTTP_EARLY_RESPONSE,
HTTP_MISSING_SETTINGS,
HTTP_UNEXPECTED_FRAME,
HTTP_REQUEST_REJECTED,
HTTP_GENERAL_PROTOCOL_ERROR,
HTTP_MALFORMED_FRAME
}
TODO: HTTP_MALFORMED_FRAME is not a single value, but can include the
frame type in its definition. This means we need more flexible error
Marx Expires January 4, 2020 [Page 14]
Internet-Draft QUIC and HTTP/3 event definitions for qlog July 2019
logging. Best to wait until h3-draft-21, which will include
substantial changes to error codes.
Appendix C. Change Log
C.1. Since draft-marx-qlog-event-definitions-quic-h3-00-00:
o None yet.
Appendix D. Design Variations
TBD
Appendix E. Acknowledgements
Thanks to Jana Iyengar, Brian Trammell, Dmitri Tikhonov, Stephen
Petrides, Jari Arkko, Marcus Ihlar, Victor Vasiliev, Mirja Kuehlewind
and Lucas Pardue for their feedback and suggestions.
Author's Address
Robin Marx
Hasselt University
Email: robin.marx@uhasselt.be
Marx Expires January 4, 2020 [Page 15]