idnits 2.17.1 draft-ietf-quic-qlog-h3-events-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 15 instances of too long lines in the document, the longest one being 188 characters in excess of 72. ** The abstract seems to contain references ([QLOG-MAIN]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (10 June 2021) is 1022 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) == Outdated reference: A later version (-08) exists of draft-ietf-quic-qlog-main-schema-00 == Outdated reference: A later version (-07) exists of draft-ietf-quic-qlog-quic-events-00 -- No information found for draft-ietf-quic-http-latest - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'QUIC-HTTP' -- No information found for draft-ietf-quic-qpack-latest - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'QUIC-QPACK' Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC R. Marx 3 Internet-Draft KU Leuven 4 Intended status: Standards Track L. Niccolini, Ed. 5 Expires: 12 December 2021 Facebook 6 M. Seemann, Ed. 7 Protocol Labs 8 10 June 2021 10 HTTP/3 and QPACK event definitions for qlog 11 draft-ietf-quic-qlog-h3-events-00 13 Abstract 15 This document describes concrete qlog event definitions and their 16 metadata for HTTP/3 and QPACK-related events. These events can then 17 be embedded in the higher level schema defined in [QLOG-MAIN]. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 12 December 2021. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 54 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Usage with QUIC . . . . . . . . . . . . . . . . . . . . . 4 56 2.2. Links to the main schema . . . . . . . . . . . . . . . . 4 57 2.2.1. Raw packet and frame information . . . . . . . . . . 4 58 3. HTTP/3 and QPACK event definitions . . . . . . . . . . . . . 5 59 3.1. http . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3.1.1. parameters_set . . . . . . . . . . . . . . . . . . . 5 61 3.1.2. parameters_restored . . . . . . . . . . . . . . . . . 6 62 3.1.3. stream_type_set . . . . . . . . . . . . . . . . . . . 6 63 3.1.4. frame_created . . . . . . . . . . . . . . . . . . . . 7 64 3.1.5. frame_parsed . . . . . . . . . . . . . . . . . . . . 8 65 3.1.6. push_resolved . . . . . . . . . . . . . . . . . . . . 8 66 3.2. qpack . . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 3.2.1. state_updated . . . . . . . . . . . . . . . . . . . . 9 68 3.2.2. stream_state_updated . . . . . . . . . . . . . . . . 9 69 3.2.3. dynamic_table_updated . . . . . . . . . . . . . . . . 10 70 3.2.4. headers_encoded . . . . . . . . . . . . . . . . . . . 10 71 3.2.5. headers_decoded . . . . . . . . . . . . . . . . . . . 11 72 3.2.6. instruction_created . . . . . . . . . . . . . . . . . 11 73 3.2.7. instruction_parsed . . . . . . . . . . . . . . . . . 12 74 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 75 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 76 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 6.1. Normative References . . . . . . . . . . . . . . . . . . 12 78 6.2. Informative References . . . . . . . . . . . . . . . . . 13 79 Appendix A. HTTP/3 data field definitions . . . . . . . . . . . 13 80 A.1. HTTP/3 Frames . . . . . . . . . . . . . . . . . . . . . . 13 81 A.1.1. DataFrame . . . . . . . . . . . . . . . . . . . . . . 13 82 A.1.2. HeadersFrame . . . . . . . . . . . . . . . . . . . . 14 83 A.1.3. CancelPushFrame . . . . . . . . . . . . . . . . . . . 14 84 A.1.4. SettingsFrame . . . . . . . . . . . . . . . . . . . . 14 85 A.1.5. PushPromiseFrame . . . . . . . . . . . . . . . . . . 14 86 A.1.6. GoAwayFrame . . . . . . . . . . . . . . . . . . . . . 15 87 A.1.7. MaxPushIDFrame . . . . . . . . . . . . . . . . . . . 15 88 A.1.8. DuplicatePushFrame . . . . . . . . . . . . . . . . . 15 89 A.1.9. ReservedFrame . . . . . . . . . . . . . . . . . . . . 15 90 A.1.10. UnknownFrame . . . . . . . . . . . . . . . . . . . . 15 91 A.2. ApplicationError . . . . . . . . . . . . . . . . . . . . 15 92 Appendix B. QPACK DATA type definitions . . . . . . . . . . . . 16 93 B.1. QPACK Instructions . . . . . . . . . . . . . . . . . . . 16 94 B.1.1. SetDynamicTableCapacityInstruction . . . . . . . . . 16 95 B.1.2. InsertWithNameReferenceInstruction . . . . . . . . . 16 96 B.1.3. InsertWithoutNameReferenceInstruction . . . . . . . . 17 97 B.1.4. DuplicateInstruction . . . . . . . . . . . . . . . . 17 98 B.1.5. HeaderAcknowledgementInstruction . . . . . . . . . . 17 99 B.1.6. StreamCancellationInstruction . . . . . . . . . . . . 17 100 B.1.7. InsertCountIncrementInstruction . . . . . . . . . . . 18 101 B.2. QPACK Header compression . . . . . . . . . . . . . . . . 18 102 B.2.1. IndexedHeaderField . . . . . . . . . . . . . . . . . 18 103 B.2.2. LiteralHeaderFieldWithName . . . . . . . . . . . . . 18 104 B.2.3. LiteralHeaderFieldWithoutName . . . . . . . . . . . . 19 105 B.2.4. QPackHeaderBlockPrefix . . . . . . . . . . . . . . . 19 106 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 19 107 C.1. Since draft-marx-qlog-event-definitions-quic-h3-02: . . . 19 108 C.2. Since draft-marx-qlog-event-definitions-quic-h3-01: . . . 20 109 C.3. Since draft-marx-qlog-event-definitions-quic-h3-00: . . . 21 110 Appendix D. Design Variations . . . . . . . . . . . . . . . . . 22 111 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 22 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 114 1. Introduction 116 This document describes the values of the qlog name ("category" + 117 "event") and "data" fields and their semantics for the HTTP/3 and 118 QPACK protocols. This document is based on draft-34 of the HTTP/3 119 I-D [QUIC-HTTP] and draft-21 of the QPACK I-D [QUIC-QPACK]. QUIC 120 events are defined in a separate document [QLOG-QUIC]. 122 Feedback and discussion are welcome at https://github.com/quicwg/qlog 123 (https://github.com/quicwg/qlog). Readers are advised to refer to 124 the "editor's draft" at that URL for an up-to-date version of this 125 document. 127 Concrete examples of integrations of this schema in various 128 programming languages can be found at https://github.com/quiclog/ 129 qlog/ (https://github.com/quiclog/qlog/). 131 1.1. Notational Conventions 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in [RFC2119]. 137 The examples and data definitions in ths document are expressed in a 138 custom data definition language, inspired by JSON and TypeScript, and 139 described in [QLOG-MAIN]. 141 2. Overview 143 This document describes the values of the qlog "name" ("category" + 144 "event") and "data" fields and their semantics for the HTTP/3 and 145 QPACK protocols. 147 This document assumes the usage of the encompassing main qlog schema 148 defined in [QLOG-MAIN]. Each subsection below defines a separate 149 category (for example http, qpack) and each subsubsection is an event 150 type (for example "frame_created"). 152 For each event type, its importance and data definition is laid out, 153 often accompanied by possible values for the optional "trigger" 154 field. For the definition and semantics of "importance" and 155 "trigger", see the main schema document. 157 Most of the complex datastructures, enums and re-usable definitions 158 are grouped together on the bottom of this document for clarity. 160 2.1. Usage with QUIC 162 The events described in this document can be used with or without 163 logging the related QUIC events defined in [QLOG-QUIC]. If used with 164 QUIC events, the QUIC document takes precedence in terms of 165 recommended filenames and trace separation setups. 167 If used without QUIC events, it is recommended that the 168 implementation assign a globally unique identifier to each HTTP/3 169 connection. This ID can then be used as the value of the qlog 170 "group_id" field, as well as the qlog filename or file identifier, 171 potentially suffixed by the vantagepoint type (For example, 172 abcd1234_server.qlog would contain the server-side trace of the 173 connection with GUID abcd1234). 175 2.2. Links to the main schema 177 This document re-uses all the fields defined in the main qlog schema 178 (e.g., name, category, type, data, group_id, protocol_type, the time- 179 related fields, importance, RawInfo, etc.). 181 One entry in the "protocol_type" qlog array field MUST be "HTTP3" if 182 events from this document are included in a qlog trace. 184 2.2.1. Raw packet and frame information 186 This document re-uses the definition of the RawInfo data class from 187 [QLOG-MAIN]. 189 Note: As HTTP/3 does not use trailers in frames, each HTTP/3 frame 190 header_length can be calculated as header_length = RawInfo:length 191 - RawInfo:payload_length 193 Note: In some cases, the length fields are also explicitly reflected 194 inside of frame headers. For example, all HTTP/3 frames include 195 their explicit payload lengths in the frame header. In these 196 cases, those fields are intentionally preserved in the event 197 definitions. Even though this can lead to duplicate data when the 198 full RawInfo is logged, it allows a more direct mapping of the 199 HTTP/3 specifications to qlog, making it easier for users to 200 interpret. In this case, both fields MUST have the same value. 202 3. HTTP/3 and QPACK event definitions 204 Each subheading in this section is a qlog event category, while each 205 sub-subheading is a qlog event type. 207 For example, for the following two items, we have the category "http" 208 and event type "parameters_set", resulting in a concatenated qlog 209 "name" field value of "http:parameters_set". 211 3.1. http 213 Note: like all category values, the "http" category is written in 214 lowercase. 216 3.1.1. parameters_set 218 Importance: Base 220 This event contains HTTP/3 and QPACK-level settings, mostly those 221 received from the HTTP/3 SETTINGS frame. All these parameters are 222 typically set once and never change. However, they are typically set 223 at different times during the connection, so there can be several 224 instances of this event with different fields set. 226 Note that some settings have two variations (one set locally, one 227 requested by the remote peer). This is reflected in the "owner" 228 field. As such, this field MUST be correct for all settings included 229 a single event instance. If you need to log settings from two sides, 230 you MUST emit two separate event instances. 232 Data: 234 { 235 owner?:"local" | "remote", 237 max_header_list_size?:uint64, // from SETTINGS_MAX_HEADER_LIST_SIZE 238 max_table_capacity?:uint64, // from SETTINGS_QPACK_MAX_TABLE_CAPACITY 239 blocked_streams_count?:uint64, // from SETTINGS_QPACK_BLOCKED_STREAMS 241 // qlog-defined 242 waits_for_settings?:boolean // indicates whether this implementation waits for a SETTINGS frame before processing requests 243 } 245 Note: enabling server push is not explicitly done in HTTP/3 by use of 246 a setting or parameter. Instead, it is communicated by use of the 247 MAX_PUSH_ID frame, which should be logged using the frame_created and 248 frame_parsed events below. 250 Additionally, this event can contain any number of unspecified 251 fields. This is to reflect setting of for example unknown (greased) 252 settings or parameters of (proprietary) extensions. 254 3.1.2. parameters_restored 256 Importance: Base 258 When using QUIC 0-RTT, HTTP/3 clients are expected to remember and 259 reuse the server's SETTINGs from the previous connection. This event 260 is used to indicate which HTTP/3 settings were restored and to which 261 values when utilizing 0-RTT. 263 Data: 265 { 266 max_header_list_size?:uint64, 267 max_table_capacity?:uint64, 268 blocked_streams_count?:uint64 269 } 271 Note that, like for parameters_set above, this event can contain any 272 number of unspecified fields to allow for additional and custom 273 settings. 275 3.1.3. stream_type_set 277 Importance: Base 279 Emitted when a stream's type becomes known. This is typically when a 280 stream is opened and the stream's type indicator is sent or received. 282 Note: most of this information can also be inferred by looking at a 283 stream's id, since id's are strictly partitioned at the QUIC level. 284 Even so, this event has a "Base" importance because it helps a lot in 285 debugging to have this information clearly spelled out. 287 Data: 289 { 290 stream_id:uint64, 292 owner?:"local"|"remote" 294 old?:StreamType, 295 new:StreamType, 297 associated_push_id?:uint64 // only when new == "push" 298 } 300 enum StreamType { 301 data, // bidirectional request-response streams 302 control, 303 push, 304 reserved, 305 qpack_encode, 306 qpack_decode 307 } 309 3.1.4. frame_created 311 Importance: Core 313 HTTP equivalent to the packet_sent event. This event is emitted when 314 the HTTP/3 framing actually happens. Note: this is not necessarily 315 the same as when the HTTP/3 data is passed on to the QUIC layer. For 316 that, see the "data_moved" event in [QLOG-QUIC]. 318 Data: 320 { 321 stream_id:uint64, 322 length?:uint64, // payload byte length of the frame 323 frame:HTTP3Frame, // see appendix for the definitions, 325 raw?:RawInfo 326 } 327 Note: in HTTP/3, DATA frames can have arbitrarily large lengths to 328 reduce frame header overhead. As such, DATA frames can span many 329 QUIC packets and can be created in a streaming fashion. In this 330 case, the frame_created event is emitted once for the frame header, 331 and further streamed data is indicated using the data_moved event. 333 3.1.5. frame_parsed 335 Importance: Core 337 HTTP equivalent to the packet_received event. This event is emitted 338 when we actually parse the HTTP/3 frame. Note: this is not 339 necessarily the same as when the HTTP/3 data is actually received on 340 the QUIC layer. For that, see the "data_moved" event in [QLOG-QUIC]. 342 Data: 344 { 345 stream_id:uint64, 346 length?:uint64, // payload byte length of the frame 347 frame:HTTP3Frame, // see appendix for the definitions, 349 raw?:RawInfo 350 } 352 Note: in HTTP/3, DATA frames can have arbitrarily large lengths to 353 reduce frame header overhead. As such, DATA frames can span many 354 QUIC packets and can be processed in a streaming fashion. In this 355 case, the frame_parsed event is emitted once for the frame header, 356 and further streamed data is indicated using the data_moved event. 358 3.1.6. push_resolved 360 Importance: Extra 362 This event is emitted when a pushed resource is successfully claimed 363 (used) or, conversely, abandoned (rejected) by the application on top 364 of HTTP/3 (e.g., the web browser). This event is added to help debug 365 problems with unexpected PUSH behaviour, which is commonplace with 366 HTTP/2. 368 { 369 push_id?:uint64, 370 stream_id?:uint64, // in case this is logged from a place that does not have access to the push_id 372 decision:"claimed"|"abandoned" 373 } 374 3.2. qpack 376 Note: like all category values, the "qpack" category is written in 377 lowercase. 379 The QPACK events mainly serve as an aid to debug low-level QPACK 380 issues. The higher-level, plaintext header values SHOULD (also) be 381 logged in the http.frame_created and http.frame_parsed event data 382 (instead). 384 Note: qpack does not have its own parameters_set event. This was 385 merged with http.parameters_set for brevity, since qpack is a 386 required extension for HTTP/3 anyway. Other HTTP/3 extensions MAY 387 also log their SETTINGS fields in http.parameters_set or MAY define 388 their own events. 390 3.2.1. state_updated 392 Importance: Base 394 This event is emitted when one or more of the internal QPACK 395 variables changes value. Note that some variables have two 396 variations (one set locally, one requested by the remote peer). This 397 is reflected in the "owner" field. As such, this field MUST be 398 correct for all variables included a single event instance. If you 399 need to log settings from two sides, you MUST emit two separate event 400 instances. 402 Data: 404 { 405 owner:"local" | "remote", 407 dynamic_table_capacity?:uint64, 408 dynamic_table_size?:uint64, // effective current size, sum of all the entries 410 known_received_count?:uint64, 411 current_insert_count?:uint64 412 } 414 3.2.2. stream_state_updated 416 Importance: Core 418 This event is emitted when a stream becomes blocked or unblocked by 419 header decoding requests or QPACK instructions. 421 Note: This event is of "Core" importance, as it might have a large 422 impact on HTTP/3's observed performance. 424 Data: 426 { 427 stream_id:uint64, 429 state:"blocked"|"unblocked" // streams are assumed to start "unblocked" until they become "blocked" 430 } 432 3.2.3. dynamic_table_updated 434 Importance: Extra 436 This event is emitted when one or more entries are inserted or 437 evicted from QPACK's dynamic table. 439 Data: 441 { 442 owner:"local" | "remote", // local = the encoder's dynamic table. remote = the decoder's dynamic table 444 update_type:"inserted"|"evicted", 446 entries:Array 447 } 449 class DynamicTableEntry { 450 index:uint64; 451 name?:string | bytes; 452 value?:string | bytes; 453 } 455 3.2.4. headers_encoded 457 Importance: Base 459 This event is emitted when an uncompressed header block is encoded 460 successfully. 462 Note: this event has overlap with http.frame_created for the 463 HeadersFrame type. When outputting both events, implementers MAY 464 omit the "headers" field in this event. 466 Data: 468 { 469 stream_id?:uint64, 471 headers?:Array, 473 block_prefix:QPackHeaderBlockPrefix, 474 header_block:Array, 476 length?:uint32, 477 raw?:bytes 478 } 480 3.2.5. headers_decoded 482 Importance: Base 484 This event is emitted when a compressed header block is decoded 485 successfully. 487 Note: this event has overlap with http.frame_parsed for the 488 HeadersFrame type. When outputting both events, implementers MAY 489 omit the "headers" field in this event. 491 Data: 493 { 494 stream_id?:uint64, 496 headers?:Array, 498 block_prefix:QPackHeaderBlockPrefix, 499 header_block:Array, 501 length?:uint32, 502 raw?:bytes 503 } 505 3.2.6. instruction_created 507 Importance: Base 509 This event is emitted when a QPACK instruction (both decoder and 510 encoder) is created and added to the encoder/decoder stream. 512 Data: 514 { 515 instruction:QPackInstruction // see appendix for the definitions, 517 length?:uint32, 518 raw?:bytes 519 } 521 Note: encoder/decoder semantics and stream_id's are implicit in 522 either the instruction types or can be logged via other events (e.g., 523 http.stream_type_set) 525 3.2.7. instruction_parsed 527 Importance: Base 529 This event is emitted when a QPACK instruction (both decoder and 530 encoder) is read from the encoder/decoder stream. 532 Data: 534 { 535 instruction:QPackInstruction // see appendix for the definitions, 537 length?:uint32, 538 raw?:bytes 539 } 541 Note: encoder/decoder semantics and stream_id's are implicit in 542 either the instruction types or can be logged via other events (e.g., 543 http.stream_type_set) 545 4. Security Considerations 547 TBD 549 5. IANA Considerations 551 TBD 553 6. References 555 6.1. Normative References 557 [QLOG-MAIN] 558 Marx, R., Ed., Niccolini, L., Ed., and M. Seemann, Ed., 559 "Main logging schema for qlog", Work in Progress, 560 Internet-Draft, draft-ietf-quic-qlog-main-schema-00, 561 . 564 [QLOG-QUIC] 565 Marx, R., Ed., Niccolini, L., Ed., and M. Seemann, Ed., 566 "QUIC event definitions for qlog", Work in Progress, 567 Internet-Draft, draft-ietf-quic-qlog-quic-events-00, 568 . 571 [QUIC-HTTP] 572 Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 573 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 574 quic-http-latest, 575 . 577 [QUIC-QPACK] 578 Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 579 Header Compression for HTTP over QUIC", Work in Progress, 580 Internet-Draft, draft-ietf-quic-qpack-latest, 581 . 584 6.2. Informative References 586 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 587 Requirement Levels", BCP 14, RFC 2119, 588 DOI 10.17487/RFC2119, March 1997, 589 . 591 Appendix A. HTTP/3 data field definitions 593 A.1. HTTP/3 Frames 595 type HTTP3Frame = DataFrame | HeadersFrame | PriorityFrame | CancelPushFrame | SettingsFrame | PushPromiseFrame | GoAwayFrame | MaxPushIDFrame | DuplicatePushFrame | ReservedFrame | UnknownFrame; 597 A.1.1. DataFrame 599 class DataFrame{ 600 frame_type:string = "data"; 602 raw?:bytes; 603 } 605 A.1.2. HeadersFrame 607 This represents an _uncompressed_, plaintext HTTP Headers frame 608 (e.g., no QPACK compression is applied). 610 For example: 612 headers: [{"name":":path","value":"/"},{"name":":method","value":"GET"},{"name":":authority","value":"127.0.0.1:4433"},{"name":":scheme","value":"https"}] 614 class HeadersFrame{ 615 frame_type:string = "header"; 616 headers:Array; 617 } 619 class HTTPHeader { 620 name:string; 621 value:string; 622 } 624 A.1.3. CancelPushFrame 626 class CancelPushFrame{ 627 frame_type:string = "cancel_push"; 628 push_id:uint64; 629 } 631 A.1.4. SettingsFrame 633 class SettingsFrame{ 634 frame_type:string = "settings"; 635 settings:Array; 636 } 638 class Setting{ 639 name:string; 640 value:string; 641 } 643 A.1.5. PushPromiseFrame 645 class PushPromiseFrame{ 646 frame_type:string = "push_promise"; 647 push_id:uint64; 649 headers:Array; 650 } 652 A.1.6. GoAwayFrame 654 class GoAwayFrame{ 655 frame_type:string = "goaway"; 656 stream_id:uint64; 657 } 659 A.1.7. MaxPushIDFrame 661 class MaxPushIDFrame{ 662 frame_type:string = "max_push_id"; 663 push_id:uint64; 664 } 666 A.1.8. DuplicatePushFrame 668 class DuplicatePushFrame{ 669 frame_type:string = "duplicate_push"; 670 push_id:uint64; 671 } 673 A.1.9. ReservedFrame 675 class ReservedFrame{ 676 frame_type:string = "reserved"; 677 } 679 A.1.10. UnknownFrame 681 HTTP/3 re-uses QUIC's UnknownFrame definition, since their values and 682 usage overlaps. See [QLOG-QUIC]. 684 A.2. ApplicationError 685 enum ApplicationError{ 686 http_no_error, 687 http_general_protocol_error, 688 http_internal_error, 689 http_stream_creation_error, 690 http_closed_critical_stream, 691 http_frame_unexpected, 692 http_frame_error, 693 http_excessive_load, 694 http_id_error, 695 http_settings_error, 696 http_missing_settings, 697 http_request_rejected, 698 http_request_cancelled, 699 http_request_incomplete, 700 http_early_response, 701 http_connect_error, 702 http_version_fallback 703 } 705 Appendix B. QPACK DATA type definitions 707 B.1. QPACK Instructions 709 Note: the instructions do not have explicit encoder/decoder types, 710 since there is no overlap between the insturctions of both types in 711 neither name nor function. 713 type QPackInstruction = SetDynamicTableCapacityInstruction | InsertWithNameReferenceInstruction | InsertWithoutNameReferenceInstruction | DuplicateInstruction | HeaderAcknowledgementInstruction | StreamCancellationInstruction | InsertCountIncrementInstruction; 715 B.1.1. SetDynamicTableCapacityInstruction 717 class SetDynamicTableCapacityInstruction { 718 instruction_type:string = "set_dynamic_table_capacity"; 720 capacity:uint32; 721 } 723 B.1.2. InsertWithNameReferenceInstruction 724 class InsertWithNameReferenceInstruction { 725 instruction_type:string = "insert_with_name_reference"; 727 table_type:"static"|"dynamic"; 729 name_index:uint32; 731 huffman_encoded_value:boolean; 733 value_length?:uint32; 734 value?:string; 735 } 737 B.1.3. InsertWithoutNameReferenceInstruction 739 class InsertWithoutNameReferenceInstruction { 740 instruction_type:string = "insert_without_name_reference"; 742 huffman_encoded_name:boolean; 744 name_length?:uint32; 745 name?:string; 747 huffman_encoded_value:boolean; 749 value_length?:uint32; 750 value?:string; 751 } 753 B.1.4. DuplicateInstruction 755 class DuplicateInstruction { 756 instruction_type:string = "duplicate"; 758 index:uint32; 759 } 761 B.1.5. HeaderAcknowledgementInstruction 763 class HeaderAcknowledgementInstruction { 764 instruction_type:string = "header_acknowledgement"; 766 stream_id:uint64; 767 } 769 B.1.6. StreamCancellationInstruction 770 class StreamCancellationInstruction { 771 instruction_type:string = "stream_cancellation"; 773 stream_id:uint64; 774 } 776 B.1.7. InsertCountIncrementInstruction 778 class InsertCountIncrementInstruction { 779 instruction_type:string = "insert_count_increment"; 781 increment:uint32; 782 } 784 B.2. QPACK Header compression 786 type QPackHeaderBlockRepresentation = IndexedHeaderField | LiteralHeaderFieldWithName | LiteralHeaderFieldWithoutName; 788 B.2.1. IndexedHeaderField 790 Note: also used for "indexed header field with post-base index" 792 class IndexedHeaderField { 793 header_field_type:string = "indexed_header"; 795 table_type:"static"|"dynamic"; // MUST be "dynamic" if is_post_base is true 796 index:uint32; 798 is_post_base:boolean = false; // to represent the "indexed header field with post-base index" header field type 799 } 801 B.2.2. LiteralHeaderFieldWithName 803 Note: also used for "Literal header field with post-base name 804 reference" 806 class LiteralHeaderFieldWithName { 807 header_field_type:string = "literal_with_name"; 809 preserve_literal:boolean; // the 3rd "N" bit 810 table_type:"static"|"dynamic"; // MUST be "dynamic" if is_post_base is true 811 name_index:uint32; 813 huffman_encoded_value:boolean; 814 value_length?:uint32; 815 value?:string; 817 is_post_base:boolean = false; // to represent the "Literal header field with post-base name reference" header field type 818 } 820 B.2.3. LiteralHeaderFieldWithoutName 822 class LiteralHeaderFieldWithoutName { 823 header_field_type:string = "literal_without_name"; 825 preserve_literal:boolean; // the 3rd "N" bit 827 huffman_encoded_name:boolean; 828 name_length?:uint32; 829 name?:string; 831 huffman_encoded_value:boolean; 832 value_length?:uint32; 833 value?:string; 834 } 836 B.2.4. QPackHeaderBlockPrefix 838 class QPackHeaderBlockPrefix { 839 required_insert_count:uint32; 840 sign_bit:boolean; 841 delta_base:uint32; 842 } 844 Appendix C. Change Log 846 C.1. Since draft-marx-qlog-event-definitions-quic-h3-02: 848 * These changes were done in preparation of the adoption of the 849 drafts by the QUIC working group (#137) 851 * Split QUIC and HTTP/3 events into two separate documents 852 * Moved RawInfo, Importance, Generic events and Simulation events to 853 the main schema document. 855 C.2. Since draft-marx-qlog-event-definitions-quic-h3-01: 857 Major changes: 859 * Moved data_moved from http to transport. Also made the "from" and 860 "to" fields flexible strings instead of an enum (#111,#65) 862 * Moved packet_type fields to PacketHeader. Moved packet_size field 863 out of PacketHeader to RawInfo:length (#40) 865 * Made events that need to log packet_type and packet_number use a 866 header field instead of logging these fields individually 868 * Added support for logging retry, stateless reset and initial 869 tokens (#94,#86,#117) 871 * Moved separate general event categories into a single category 872 "generic" (#47) 874 * Added "transport:connection_closed" event (#43,#85,#78,#49) 876 * Added version_information and alpn_information events 877 (#85,#75,#28) 879 * Added parameters_restored events to help clarify 0-RTT behaviour 880 (#88) 882 Smaller changes: 884 * Merged loss_timer events into one loss_timer_updated event 886 * Field data types are now strongly defined (#10,#39,#36,#115) 888 * Renamed qpack instruction_received and instruction_sent to 889 instruction_created and instruction_parsed (#114) 891 * Updated qpack:dynamic_table_updated.update_type. It now has the 892 value "inserted" instead of "added" (#113) 894 * Updated qpack:dynamic_table_updated. It now has an "owner" field 895 to differentiate encoder vs decoder state (#112) 897 * Removed push_allowed from http:parameters_set (#110) 898 * Removed explicit trigger field indications from events, since this 899 was moved to be a generic property of the "data" field (#80) 901 * Updated transport:connection_id_updated to be more in line with 902 other similar events. Also dropped importance from Core to Base 903 (#45) 905 * Added length property to PaddingFrame (#34) 907 * Added packet_number field to transport:frames_processed (#74) 909 * Added a way to generically log packet header flags (first 8 bits) 910 to PacketHeader 912 * Added additional guidance on which events to log in which 913 situations (#53) 915 * Added "simulation:scenario" event to help indicate simulation 916 details 918 * Added "packets_acked" event (#107) 920 * Added "datagram_ids" to the datagram_X and packet_X events to 921 allow tracking of coalesced QUIC packets (#91) 923 * Extended connection_state_updated with more fine-grained states 924 (#49) 926 C.3. Since draft-marx-qlog-event-definitions-quic-h3-00: 928 * Event and category names are now all lowercase 930 * Added many new events and their definitions 932 * "type" fields have been made more specific (especially important 933 for PacketType fields, which are now called packet_type instead of 934 type) 936 * Events are given an importance indicator (issue #22) 938 * Event names are more consistent and use past tense (issue #21) 940 * Triggers have been redefined as properties of the "data" field and 941 updated for most events (issue #23) 943 Appendix D. Design Variations 945 TBD 947 Appendix E. Acknowledgements 949 Much of the initial work by Robin Marx was done at Hasselt 950 University. 952 Thanks to Marten Seemann, Jana Iyengar, Brian Trammell, Dmitri 953 Tikhonov, Stephen Petrides, Jari Arkko, Marcus Ihlar, Victor 954 Vasiliev, Mirja Kuehlewind, Jeremy Laine, Kazu Yamamoto, Christian 955 Huitema, and Lucas Pardue for their feedback and suggestions. 957 Authors' Addresses 959 Robin Marx 960 KU Leuven 962 Email: robin.marx@kuleuven.be 964 Luca Niccolini (editor) 965 Facebook 967 Email: lniccolini@fb.com 969 Marten Seemann (editor) 970 Protocol Labs 972 Email: marten@protocol.ai