idnits 2.17.1 draft-marx-qlog-event-definitions-quic-h3-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 60 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 03, 2019) is 1760 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 466 -- Looks like a reference, but probably isn't: '120' on line 526 == Unused Reference: 'QUIC-TRANSPORT' is defined on line 454, but no explicit reference was found in the text == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-20 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-20 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC R. Marx 3 Internet-Draft Hasselt University 4 Intended status: Standards Track July 03, 2019 5 Expires: January 4, 2020 7 QUIC and HTTP/3 event definitions for qlog 8 draft-marx-qlog-event-definitions-quic-h3-00 10 Abstract 12 This document describes concrete qlog event definitions and their 13 metadata for QUIC and HTTP/3-related events. These events can then 14 be embedded in the higher level schema defined in draft-marx-quic- 15 logging-main-schema-latest. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 4, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 53 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. QUIC event definitions . . . . . . . . . . . . . . . . . . . 4 55 3.1. CONNECTIVITY . . . . . . . . . . . . . . . . . . . . . . 4 56 3.1.1. CONNECTION_ATTEMPT . . . . . . . . . . . . . . . . . 4 57 3.1.2. CONNECTION_NEW . . . . . . . . . . . . . . . . . . . 4 58 3.1.3. CONNECTION_ID_UPDATE . . . . . . . . . . . . . . . . 5 59 3.1.4. MIGRATION-related events . . . . . . . . . . . . . . 5 60 3.1.5. CONNECTION_CLOSED . . . . . . . . . . . . . . . . . . 5 61 3.2. SECURITY . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.2.1. HEADER_DECRYPT_ERROR . . . . . . . . . . . . . . . . 5 63 3.2.2. PACKET_DECRYPT_ERROR . . . . . . . . . . . . . . . . 5 64 3.2.3. KEY_UPDATE . . . . . . . . . . . . . . . . . . . . . 5 65 3.2.4. KEY_RETIRED . . . . . . . . . . . . . . . . . . . . . 5 66 3.2.5. CIPHER_UPDATE . . . . . . . . . . . . . . . . . . . . 5 67 3.3. TRANSPORT . . . . . . . . . . . . . . . . . . . . . . . . 5 68 3.3.1. PACKET_SENT . . . . . . . . . . . . . . . . . . . . . 5 69 3.3.2. PACKET_RECEIVED . . . . . . . . . . . . . . . . . . . 6 70 3.3.3. PACKET_DROPPED . . . . . . . . . . . . . . . . . . . 6 71 3.3.4. VERSION_UPDATE . . . . . . . . . . . . . . . . . . . 7 72 3.3.5. TRANSPORT_PARAMETERS_UPDATE . . . . . . . . . . . . . 7 73 3.3.6. ALPN_UPDATE . . . . . . . . . . . . . . . . . . . . . 7 74 3.3.7. STREAM_STATE_UPDATE . . . . . . . . . . . . . . . . . 7 75 3.3.8. FLOW_CONTROL_UPDATE . . . . . . . . . . . . . . . . . 8 76 3.4. RECOVERY . . . . . . . . . . . . . . . . . . . . . . . . 8 77 3.4.1. CC_STATE_UPDATE . . . . . . . . . . . . . . . . . . . 8 78 3.4.2. METRIC_UPDATE . . . . . . . . . . . . . . . . . . . . 8 79 3.4.3. LOSS_ALARM_SET . . . . . . . . . . . . . . . . . . . 9 80 3.4.4. LOSS_ALARM_FIRED . . . . . . . . . . . . . . . . . . 9 81 3.4.5. PACKET_LOST . . . . . . . . . . . . . . . . . . . . . 9 82 3.4.6. PACKET_ACKNOWLEDGED . . . . . . . . . . . . . . . . . 9 83 3.4.7. PACKET_RETRANSMIT . . . . . . . . . . . . . . . . . . 10 84 4. HTTP/3 event definitions . . . . . . . . . . . . . . . . . . 10 85 4.1. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 10 86 4.2. QPACK . . . . . . . . . . . . . . . . . . . . . . . . . . 10 87 4.3. PRIORITIZATION . . . . . . . . . . . . . . . . . . . . . 10 88 4.4. PUSH . . . . . . . . . . . . . . . . . . . . . . . . . . 10 89 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 90 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 91 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 92 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 93 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 94 Appendix A. QUIC DATA type definitions . . . . . . . . . . . . . 11 95 A.1. PacketType . . . . . . . . . . . . . . . . . . . . . . . 11 96 A.2. PacketHeader . . . . . . . . . . . . . . . . . . . . . . 11 97 A.3. QUIC Frames . . . . . . . . . . . . . . . . . . . . . . . 11 98 A.3.1. AckFrame . . . . . . . . . . . . . . . . . . . . . . 11 99 A.3.2. StreamFrame . . . . . . . . . . . . . . . . . . . . . 12 100 A.3.3. ResetStreamFrame . . . . . . . . . . . . . . . . . . 12 101 A.3.4. ConnectionCloseFrame . . . . . . . . . . . . . . . . 13 102 A.3.5. MaxDataFrame . . . . . . . . . . . . . . . . . . . . 13 103 A.3.6. MaxStreamDataFrame . . . . . . . . . . . . . . . . . 13 104 A.3.7. UnknownFrame . . . . . . . . . . . . . . . . . . . . 13 105 A.3.8. TransportError . . . . . . . . . . . . . . . . . . . 13 106 Appendix B. HTTP/3 DATA type definitions . . . . . . . . . . . . 14 107 B.1. ApplicationError . . . . . . . . . . . . . . . . . . . . 14 108 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 15 109 C.1. Since draft-marx-qlog-event-definitions-quic-h3-00-00: . 15 110 Appendix D. Design Variations . . . . . . . . . . . . . . . . . 15 111 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 15 112 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 114 1. Introduction 116 Feedback and discussion welcome at https://github.com/quiclog/ 117 internet-drafts 119 1.1. Notational Conventions 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 2. Overview 127 This document describes the values of the qlog CATEGORY, EVENT_TYPE, 128 TRIGGER and DATA fields and their semantics for the QUIC and HTTP/3 129 protocols. The definitions included in this file are assumed to be 130 used in qlog's "trace" containers, where the trace's "protocol_type" 131 field MUST be set to "QUIC_HTTP3". 133 This document is based on draft-20 of the QUIC and HTTP/3 I-Ds QUIC- 134 TRANSPORT [QUIC-HTTP]. 136 This document uses the "TypeScript" language [1] to describe its 137 schema in. We use TypeScript because it is less verbose than JSON- 138 schema and almost as expressive. It also makes it easier to include 139 these definitions directly into a web-based tool. The main 140 conventions a reader should be aware of are: 142 o obj? : this object is optional 143 o type1 | type2 : a union of these two types (object can be either 144 type1 OR type2) 146 o obj:type : this object has this concrete type 148 o obj[] : this object is an array (which can contain any type of 149 object) 151 o obj:Array : this object is an array of this type 153 o number : identifies either an integer, float or double in 154 TypeScript. In this document, number always means an integer. 156 o Unless explicity defined, the value of an enum entry is the string 157 version of its name (e.g., INITIAL = "INITIAL") 159 o Many numerical fields have type "string" instead of "number". 160 This is because many JSON implementations only support integers up 161 to 2^53-1 (MAX_INTEGER for JavaScript without BigInt support), 162 which is less than QUIC's VLIE types (2^62-1). Each VLIE field is 163 thus a string, where a number would be semantically more correct. 164 Unless mentioned otherwise (e.g., for connection IDs), numerical 165 fields that are logged as strings (e.g., packet numbers) MUST be 166 logged in decimal (base-10) format. TODO: see issue 10 168 o TODO: list all possible triggers per event type 170 o TODO: make it clear which events are "normal" and which are "only 171 if you really need this" (normal = probably TRANSPORT TX/RX and 172 RECOVERY basics and HTTP basics) 174 3. QUIC event definitions 176 o TODO: flesh out the definitions for most of these 178 o TODO: add all definitions for HTTP3 and QPACK events 180 3.1. CONNECTIVITY 182 3.1.1. CONNECTION_ATTEMPT 184 TODO: specify how this works with happy eyeballs 186 3.1.2. CONNECTION_NEW 187 3.1.3. CONNECTION_ID_UPDATE 189 TODO: mention that CIDs can be logged in hex 191 3.1.4. MIGRATION-related events 193 e.g., PATH_UPDATE 195 TODO: read up on the draft how migration works and whether to best 196 fit this here or in TRANSPORT 198 3.1.5. CONNECTION_CLOSED 200 3.2. SECURITY 202 3.2.1. HEADER_DECRYPT_ERROR 204 { mask, error } 206 3.2.2. PACKET_DECRYPT_ERROR 208 { key, error } 210 3.2.3. KEY_UPDATE 212 { type = "Initial | handshake | 1RTT", value } 214 3.2.4. KEY_RETIRED 216 { value } # initial encryption level is implicitly deleted 218 3.2.5. CIPHER_UPDATE 220 3.3. TRANSPORT 222 3.3.1. PACKET_SENT 224 Triggers: 226 o "DEFAULT" 228 o "RETRANSMIT_REORDERING" // draft-19 6.1.1 230 o "RETRANSMIT_TIMEOUT" // draft-19 6.1.2 232 o "RETRANSMIT_CRYPTO" // draft-19 6.2 234 o "RETRANSMIT_PTO" // draft-19 6.3 235 o "CC_BANDWIDTH_PROBE" // needed for some CCs to figure out 236 bandwidth allocations when there are no normal sends 238 Data: 240 { 241 packet_type:PacketType, 242 header:PacketHeader, 243 frames:Array 244 } 246 Notes: 248 o We don't explicitly log the encryption_level or 249 packet_number_space: the packet_type specifies this by inference 250 (assuming correct implementation) 252 3.3.2. PACKET_RECEIVED 254 Triggers: 256 o "DEFAULT" 258 Data: 260 { 261 packet_type:PacketType, 262 header:PacketHeader, 263 frames:Array 264 } 266 Notes: 268 o We don't explicitly log the encryption_level or 269 packet_number_space: the packet_type specifies this by inference 270 (assuming correct implementation) 272 3.3.3. PACKET_DROPPED 274 Can be due to several reasons * TODO: How does this relate to 275 HEADER_DECRYPT_ERROR and PACKET_DECRYPT_ERROR? * TODO: if a packet is 276 dropped because we don't have a connection for it, how can we add it 277 to a given trace in the overall qlog file? Need a sort of catch-call 278 trace in each file? * TODO: differentiate between DATAGRAM_DROPPED 279 and PACKET_DROPPED? Same with PACKET_RECEIVED and DATAGRAM_RECEIVED? 281 3.3.4. VERSION_UPDATE 283 TODO: maybe name VERSION_SELECTED ? 285 3.3.5. TRANSPORT_PARAMETERS_UPDATE 287 3.3.6. ALPN_UPDATE 289 TODO: should this be in HTTP? 291 { alpn:string } 293 3.3.7. STREAM_STATE_UPDATE 295 { 296 old:string, 297 new:string 298 } 300 Possible values: 302 o IDLE 304 o OPEN 306 o CLOSED 308 o HALF_CLOSED_REMOTE 310 o HALF_CLOSED_LOCAL 312 o DESTROYED // memory actually freed 314 o Ready 316 o Send 318 o Data Sent 320 o Reset Sent 322 o Data Rcvd 324 o Reset Rcvd 326 o Recv 328 o Size Known 329 o Data Rcvd 331 o Data Read 333 o Reset Read 335 TODO: do we need all of these? How do implementations actually 336 handle this in practice? 338 3.3.8. FLOW_CONTROL_UPDATE 340 o type = connection 342 o type = stream + id = streamid 344 TODO: check state machine in QUIC transport draft 346 3.4. RECOVERY 348 3.4.1. CC_STATE_UPDATE 350 { 351 old:string, 352 new:string 353 } 355 3.4.2. METRIC_UPDATE 357 { 358 cwnd?: number; 359 bytes_in_flight?:number; 361 min_rtt?:number; 362 smoothed_rtt?:number; 363 latest_rtt?:number; 364 max_ack_delay?:number; 366 rtt_variance?:number; 367 ssthresh?:number; 369 pacing_rate?:number; 370 } 372 This event SHOULD group all possible metric updates that happen at or 373 around the same time in a single event (e.g., if min_rtt and 374 smoothed_rtt change at the same time, they should be bundled in a 375 single METRIC_UPDATE entry, rather than split out into two). 377 Consequently, a METRIC_UPDATE is only guaranteed to contain at least 378 one of the listed metrics. 380 Note: to make logging easier, implementations MAY log values even if 381 they are the same as previously reported values (e.g., two subsequent 382 METRIC_UPDATE entries can both report the exact same value for 383 min_rtt). However, applications SHOULD try to log only actual 384 updates to values. 386 o TODO: split these up into separate events? e.g., CWND_UPDATE, 387 BYTES_IN_FLIGHT_UPDATE, ... 389 o TODO: move things like pacing_rate, cwnd, bytes_in_flight, 390 ssthresh, etc. to CC_STATE_UPDATE? 392 o TODO: what types of CC metrics do we need to support by default 393 (e.g., cubic vs bbr) 395 3.4.3. LOSS_ALARM_SET 397 3.4.4. LOSS_ALARM_FIRED 399 3.4.5. PACKET_LOST 401 Data: 403 { 404 packet_number:string 405 } 407 Triggers: 409 o "UNKNOWN", 411 o "REORDERING_THRESHOLD", 413 o "TIME_THRESHOLD" 415 3.4.6. PACKET_ACKNOWLEDGED 417 TODO: must this be a separate event? can't we get this from logged 418 ACK frames? (however, explicitly indicating this and logging it in 419 the ack handler is a better signal that the ACK actually had the 420 intended effect than just logging its receipt) 422 3.4.7. PACKET_RETRANSMIT 424 TODO: only if a packet is retransmit in-full, which many stacks don't 425 do. Need something more flexible. 427 4. HTTP/3 event definitions 429 4.1. HTTP 431 4.2. QPACK 433 4.3. PRIORITIZATION 435 4.4. PUSH 437 5. Security Considerations 439 TBD 441 6. IANA Considerations 443 TBD 445 7. References 447 7.1. Normative References 449 [QUIC-HTTP] 450 Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 451 (HTTP/3)", draft-ietf-quic-http-20 (work in progress), 452 April 2019. 454 [QUIC-TRANSPORT] 455 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 456 Multiplexed and Secure Transport", draft-ietf-quic- 457 transport-20 (work in progress), April 2019. 459 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 460 Requirement Levels", BCP 14, RFC 2119, 461 DOI 10.17487/RFC2119, March 1997, 462 . 464 7.2. URIs 466 [1] https://www.typescriptlang.org/ 468 Appendix A. QUIC DATA type definitions 470 A.1. PacketType 472 enum PacketType { 473 INITIAL, 474 HANDSHAKE, 475 ZERORTT = "0RTT", 476 ONERTT = "1RTT", 477 RETRY, 478 VERSION_NEGOTIATION, 479 UNKOWN 480 } 482 A.2. PacketHeader 484 class PacketHeader { 485 packet_number: string; 486 packet_size?: number; 487 payload_length?: number; 489 // only if present in the header 490 // if correctly using NEW_CONNECTION_ID events, 491 // dcid can be skipped for 1RTT packets 492 version?: string; 493 scil?: string; 494 dcil?: string; 495 scid?: string; 496 dcid?: string; 498 // Note: short vs long header is implicit through PacketType 499 } 501 A.3. QUIC Frames 503 type QuicFrame = AckFrame | StreamFrame | ResetStreamFrame | ConnetionCloseFrame | MaxDataFrame | MaxStreamDataFrame | UnknownFrame; 505 A.3.1. AckFrame 506 class AckFrame{ 507 frame_type:string = "ACK"; 509 ack_delay:string; 511 // first number is "from": lowest packet number in interval 512 // second number is "to": up to and including // highest packet number in interval 513 // e.g., looks like [[1,2],[4,5]] 514 acked_ranges:Array<[number, number]>; 516 ect1?:string; 517 ect0?:string; 518 ce?:string; 519 } 521 Note: the packet ranges in AckFrame.acked_ranges do not necessarily 522 have to be ordered (e.g., [[5,9],[1,4]] is a valid value). 524 Note: the two numbers in the packet range can be the same (e.g., 525 [120,120] means that packet with number 120 was ACKed). TODO: maybe 526 make this into just [120]? 528 A.3.2. StreamFrame 530 class StreamFrame{ 531 frame_type:string = "STREAM"; 533 id:string; 535 // These two MUST always be set 536 // If not present in the Frame type, log their default values 537 offset:string; 538 length:string; 540 // this MAY be set any time, but MUST only be set if the value is "true" 541 // if absent, the value MUST be assumed to be "false" 542 fin:boolean; 543 } 545 A.3.3. ResetStreamFrame 547 class ResetStreamFrame{ 548 frame_type:string = "RESET_STREAM"; 550 id:string; 551 error_code:ApplicationError | number; 552 final_offset:string; 553 } 555 A.3.4. ConnectionCloseFrame 557 type ErrorSpace = "TRANSPORT" | "APPLICATION"; 559 class ConnectionCloseFrame{ 560 frame_type:string = "CONNECTION_CLOSE"; 562 error_space:ErrorSpace; 563 error_code:TransportError | ApplicationError | number; 564 reason:string; 566 trigger_frame_type?:number; // TODO: should be more defined, but we don't have a FrameType enum atm... 567 } 569 A.3.5. MaxDataFrame 571 class MaxDataFrame{ 572 stream_type:string = "MAX_DATA"; 574 maximum:string; 575 } 577 A.3.6. MaxStreamDataFrame 579 class MaxStreamDataFrame{ 580 stream_type:string = "MAX_STREAM_DATA"; 582 id:string; 583 maximum:string; 584 } 586 A.3.7. UnknownFrame 588 class UnknownFrame{ 589 frame_type:string = "UNKNOWN"; 590 } 592 A.3.8. TransportError 593 enum TransportError { 594 NO_ERROR, 595 INTERNAL_ERROR, 596 SERVER_BUSY, 597 APPLICATION_FLOW_CONTROL_ERROR, // 0x3 598 STREAM_FLOW_CONTROL_ERROR, // 0x4 599 STREAM_STATE_ERROR, 600 FINAL_SIZE_ERROR, 601 FRAME_ENCODING_ERROR, 602 TRANSPORT_PARAMETER_ERROR, 603 PROTOCOL_VIOLATION, 604 INVALID_MIGRATION, 605 CRYPTO_ERROR 606 } 608 Appendix B. HTTP/3 DATA type definitions 610 B.1. ApplicationError 612 enum ApplicationError{ 613 HTTP_NO_ERROR, 614 HTTP_WRONG_SETTING_DIRECTION, 615 HTTP_PUSH_REFUSED, 616 HTTP_INTERNAL_ERROR, 617 HTTP_PUSH_ALREADY_IN_CACHE, 618 HTTP_REQUEST_CANCELLED, 619 HTTP_INCOMPLETE_REQUEST, 620 HTTP_CONNECT_ERROR, 621 HTTP_EXCESSIVE_LOAD, 622 HTTP_VERSION_FALLBACK, 623 HTTP_WRONG_STREAM, 624 HTTP_LIMIT_EXCEEDED, 625 HTTP_DUPLICATE_PUSH, 626 HTTP_UNKNOWN_STREAM_TYPE, 627 HTTP_WRONG_STREAM_COUNT, 628 HTTP_CLOSED_CRITICAL_STREAM, 629 HTTP_WRONG_STREAM_DIRECTION, 630 HTTP_EARLY_RESPONSE, 631 HTTP_MISSING_SETTINGS, 632 HTTP_UNEXPECTED_FRAME, 633 HTTP_REQUEST_REJECTED, 634 HTTP_GENERAL_PROTOCOL_ERROR, 635 HTTP_MALFORMED_FRAME 636 } 638 TODO: HTTP_MALFORMED_FRAME is not a single value, but can include the 639 frame type in its definition. This means we need more flexible error 640 logging. Best to wait until h3-draft-21, which will include 641 substantial changes to error codes. 643 Appendix C. Change Log 645 C.1. Since draft-marx-qlog-event-definitions-quic-h3-00-00: 647 o None yet. 649 Appendix D. Design Variations 651 TBD 653 Appendix E. Acknowledgements 655 Thanks to Jana Iyengar, Brian Trammell, Dmitri Tikhonov, Stephen 656 Petrides, Jari Arkko, Marcus Ihlar, Victor Vasiliev, Mirja Kuehlewind 657 and Lucas Pardue for their feedback and suggestions. 659 Author's Address 661 Robin Marx 662 Hasselt University 664 Email: robin.marx@uhasselt.be