idnits 2.17.1 draft-marx-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 (May 17, 2021) is 1075 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 587 -- Looks like a reference, but probably isn't: '2' on line 589 -- Unexpected draft version: The latest known version of draft-marx-qlog-main-schema is -03, but you're referring to -04. -- 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 (~~), 1 warning (==), 8 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: November 18, 2021 Facebook 6 M. Seemann, Ed. 7 Protocol Labs 8 May 17, 2021 10 HTTP/3 and QPACK event definitions for qlog 11 draft-marx-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 November 18, 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 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 55 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.1. Usage with QUIC . . . . . . . . . . . . . . . . . . . . . 4 57 2.2. Links to the main schema . . . . . . . . . . . . . . . . 4 58 2.2.1. Raw packet and frame information . . . . . . . . . . 4 59 3. HTTP/3 and QPACK event definitions . . . . . . . . . . . . . 5 60 3.1. http . . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.1.1. parameters_set . . . . . . . . . . . . . . . . . . . 5 62 3.1.2. parameters_restored . . . . . . . . . . . . . . . . . 6 63 3.1.3. stream_type_set . . . . . . . . . . . . . . . . . . . 6 64 3.1.4. frame_created . . . . . . . . . . . . . . . . . . . . 7 65 3.1.5. frame_parsed . . . . . . . . . . . . . . . . . . . . 8 66 3.1.6. push_resolved . . . . . . . . . . . . . . . . . . . . 8 67 3.2. qpack . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 3.2.1. state_updated . . . . . . . . . . . . . . . . . . . . 9 69 3.2.2. stream_state_updated . . . . . . . . . . . . . . . . 9 70 3.2.3. dynamic_table_updated . . . . . . . . . . . . . . . . 10 71 3.2.4. headers_encoded . . . . . . . . . . . . . . . . . . . 10 72 3.2.5. headers_decoded . . . . . . . . . . . . . . . . . . . 11 73 3.2.6. instruction_created . . . . . . . . . . . . . . . . . 11 74 3.2.7. instruction_parsed . . . . . . . . . . . . . . . . . 12 75 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 76 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 77 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 78 6.1. Normative References . . . . . . . . . . . . . . . . . . 12 79 6.2. Informative References . . . . . . . . . . . . . . . . . 13 80 6.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 Appendix A. HTTP/3 data field definitions . . . . . . . . . . . 13 82 A.1. HTTP/3 Frames . . . . . . . . . . . . . . . . . . . . . . 13 83 A.1.1. DataFrame . . . . . . . . . . . . . . . . . . . . . . 13 84 A.1.2. HeadersFrame . . . . . . . . . . . . . . . . . . . . 13 85 A.1.3. CancelPushFrame . . . . . . . . . . . . . . . . . . . 14 86 A.1.4. SettingsFrame . . . . . . . . . . . . . . . . . . . . 14 87 A.1.5. PushPromiseFrame . . . . . . . . . . . . . . . . . . 14 88 A.1.6. GoAwayFrame . . . . . . . . . . . . . . . . . . . . . 14 89 A.1.7. MaxPushIDFrame . . . . . . . . . . . . . . . . . . . 15 90 A.1.8. DuplicatePushFrame . . . . . . . . . . . . . . . . . 15 91 A.1.9. ReservedFrame . . . . . . . . . . . . . . . . . . . . 15 92 A.1.10. UnknownFrame . . . . . . . . . . . . . . . . . . . . 15 93 A.2. ApplicationError . . . . . . . . . . . . . . . . . . . . 15 94 Appendix B. QPACK DATA type definitions . . . . . . . . . . . . 16 95 B.1. QPACK Instructions . . . . . . . . . . . . . . . . . . . 16 96 B.1.1. SetDynamicTableCapacityInstruction . . . . . . . . . 16 97 B.1.2. InsertWithNameReferenceInstruction . . . . . . . . . 16 98 B.1.3. InsertWithoutNameReferenceInstruction . . . . . . . . 16 99 B.1.4. DuplicateInstruction . . . . . . . . . . . . . . . . 17 100 B.1.5. HeaderAcknowledgementInstruction . . . . . . . . . . 17 101 B.1.6. StreamCancellationInstruction . . . . . . . . . . . . 17 102 B.1.7. InsertCountIncrementInstruction . . . . . . . . . . . 17 103 B.2. QPACK Header compression . . . . . . . . . . . . . . . . 17 104 B.2.1. IndexedHeaderField . . . . . . . . . . . . . . . . . 17 105 B.2.2. LiteralHeaderFieldWithName . . . . . . . . . . . . . 18 106 B.2.3. LiteralHeaderFieldWithoutName . . . . . . . . . . . . 18 107 B.2.4. QPackHeaderBlockPrefix . . . . . . . . . . . . . . . 18 108 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 18 109 C.1. Since draft-marx-qlog-event-definitions-quic-h3-02: . . . 19 110 C.2. Since draft-marx-qlog-event-definitions-quic-h3-01: . . . 19 111 C.3. Since draft-marx-qlog-event-definitions-quic-h3-00: . . . 20 112 Appendix D. Design Variations . . . . . . . . . . . . . . . . . 21 113 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 21 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 116 1. Introduction 118 This document describes the values of the qlog name ("category" + 119 "event") and "data" fields and their semantics for the HTTP/3 and 120 QPACK protocols. This document is based on draft-34 of the HTTP/3 121 I-D [QUIC-HTTP] and draft-21 of the QPACK I-D [QUIC-QPACK]. QUIC 122 events are defined in a separate document [QLOG-QUIC]. 124 Feedback and discussion are welcome at https://github.com/quiclog/ 125 internet-drafts [1]. Readers are advised to refer to the "editor's 126 draft" at that URL for an up-to-date version of this document. 128 Concrete examples of integrations of this schema in various 129 programming languages can be found at https://github.com/quiclog/ 130 qlog/ [2]. 132 1.1. Notational Conventions 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. 138 The examples and data definitions in ths document are expressed in a 139 custom data definition language, inspired by JSON and TypeScript, and 140 described in [QLOG-MAIN]. 142 2. Overview 144 This document describes the values of the qlog "name" ("category" + 145 "event") and "data" fields and their semantics for the HTTP/3 and 146 QPACK protocols. 148 This document assumes the usage of the encompassing main qlog schema 149 defined in [QLOG-MAIN]. Each subsection below defines a separate 150 category (for example http, qpack) and each subsubsection is an event 151 type (for example "frame_created"). 153 For each event type, its importance and data definition is laid out, 154 often accompanied by possible values for the optional "trigger" 155 field. For the definition and semantics of "importance" and 156 "trigger", see the main schema document. 158 Most of the complex datastructures, enums and re-usable definitions 159 are grouped together on the bottom of this document for clarity. 161 2.1. Usage with QUIC 163 The events described in this document can be used with or without 164 logging the related QUIC events defined in [QLOG-QUIC]. If used with 165 QUIC events, the QUIC document takes precedence in terms of 166 recommended filenames and trace separation setups. 168 If used without QUIC events, it is recommended that the 169 implementation assign a globally unique identifier to each HTTP/3 170 connection. This ID can then be used as the value of the qlog 171 "group_id" field, as well as the qlog filename or file identifier, 172 potentially suffixed by the vantagepoint type (For example, 173 abcd1234_server.qlog would contain the server-side trace of the 174 connection with GUID abcd1234). 176 2.2. Links to the main schema 178 This document re-uses all the fields defined in the main qlog schema 179 (e.g., name, category, type, data, group_id, protocol_type, the time- 180 related fields, importance, RawInfo, etc.). 182 One entry in the "protocol_type" qlog array field MUST be "HTTP3" if 183 events from this document are included in a qlog trace. 185 2.2.1. Raw packet and frame information 187 This document re-uses the definition of the RawInfo data class from 188 [QLOG-MAIN]. 190 Note: As HTTP/3 does not use trailers in frames, each HTTP/3 frame 191 header_length can be calculated as header_length = RawInfo:length 192 - RawInfo:payload_length 194 Note: In some cases, the length fields are also explicitly reflected 195 inside of frame headers. For example, all HTTP/3 frames include 196 their explicit payload lengths in the frame header. In these 197 cases, those fields are intentionally preserved in the event 198 definitions. Even though this can lead to duplicate data when the 199 full RawInfo is logged, it allows a more direct mapping of the 200 HTTP/3 specifications to qlog, making it easier for users to 201 interpret. In this case, both fields MUST have the same value. 203 3. HTTP/3 and QPACK event definitions 205 Each subheading in this section is a qlog event category, while each 206 sub-subheading is a qlog event type. 208 For example, for the following two items, we have the category "http" 209 and event type "parameters_set", resulting in a concatenated qlog 210 "name" field value of "http:parameters_set". 212 3.1. http 214 Note: like all category values, the "http" category is written in 215 lowercase. 217 3.1.1. parameters_set 219 Importance: Base 221 This event contains HTTP/3 and QPACK-level settings, mostly those 222 received from the HTTP/3 SETTINGS frame. All these parameters are 223 typically set once and never change. However, they are typically set 224 at different times during the connection, so there can be several 225 instances of this event with different fields set. 227 Note that some settings have two variations (one set locally, one 228 requested by the remote peer). This is reflected in the "owner" 229 field. As such, this field MUST be correct for all settings included 230 a single event instance. If you need to log settings from two sides, 231 you MUST emit two separate event instances. 233 Data: 235 { 236 owner?:"local" | "remote", 238 max_header_list_size?:uint64, // from SETTINGS_MAX_HEADER_LIST_SIZE 239 max_table_capacity?:uint64, // from SETTINGS_QPACK_MAX_TABLE_CAPACITY 240 blocked_streams_count?:uint64, // from SETTINGS_QPACK_BLOCKED_STREAMS 242 // qlog-defined 243 waits_for_settings?:boolean // indicates whether this implementation waits for a SETTINGS frame before processing requests 244 } 246 Note: enabling server push is not explicitly done in HTTP/3 by use of 247 a setting or parameter. Instead, it is communicated by use of the 248 MAX_PUSH_ID frame, which should be logged using the frame_created and 249 frame_parsed events below. 251 Additionally, this event can contain any number of unspecified 252 fields. This is to reflect setting of for example unknown (greased) 253 settings or parameters of (proprietary) extensions. 255 3.1.2. parameters_restored 257 Importance: Base 259 When using QUIC 0-RTT, HTTP/3 clients are expected to remember and 260 reuse the server's SETTINGs from the previous connection. This event 261 is used to indicate which HTTP/3 settings were restored and to which 262 values when utilizing 0-RTT. 264 Data: 266 { 267 max_header_list_size?:uint64, 268 max_table_capacity?:uint64, 269 blocked_streams_count?:uint64 270 } 272 Note that, like for parameters_set above, this event can contain any 273 number of unspecified fields to allow for additional and custom 274 settings. 276 3.1.3. stream_type_set 278 Importance: Base 280 Emitted when a stream's type becomes known. This is typically when a 281 stream is opened and the stream's type indicator is sent or received. 283 Note: most of this information can also be inferred by looking at a 284 stream's id, since id's are strictly partitioned at the QUIC level. 285 Even so, this event has a "Base" importance because it helps a lot in 286 debugging to have this information clearly spelled out. 288 Data: 290 { 291 stream_id:uint64, 293 owner?:"local"|"remote" 295 old?:StreamType, 296 new:StreamType, 298 associated_push_id?:uint64 // only when new == "push" 299 } 301 enum StreamType { 302 data, // bidirectional request-response streams 303 control, 304 push, 305 reserved, 306 qpack_encode, 307 qpack_decode 308 } 310 3.1.4. frame_created 312 Importance: Core 314 HTTP equivalent to the packet_sent event. This event is emitted when 315 the HTTP/3 framing actually happens. Note: this is not necessarily 316 the same as when the HTTP/3 data is passed on to the QUIC layer. For 317 that, see the "data_moved" event in [QLOG-QUIC]. 319 Data: 321 { 322 stream_id:uint64, 323 length?:uint64, // payload byte length of the frame 324 frame:HTTP3Frame, // see appendix for the definitions, 326 raw?:RawInfo 327 } 329 Note: in HTTP/3, DATA frames can have arbitrarily large lengths to 330 reduce frame header overhead. As such, DATA frames can span many 331 QUIC packets and can be created in a streaming fashion. In this 332 case, the frame_created event is emitted once for the frame header, 333 and further streamed data is indicated using the data_moved event. 335 3.1.5. frame_parsed 337 Importance: Core 339 HTTP equivalent to the packet_received event. This event is emitted 340 when we actually parse the HTTP/3 frame. Note: this is not 341 necessarily the same as when the HTTP/3 data is actually received on 342 the QUIC layer. For that, see the "data_moved" event in [QLOG-QUIC]. 344 Data: 346 { 347 stream_id:uint64, 348 length?:uint64, // payload byte length of the frame 349 frame:HTTP3Frame, // see appendix for the definitions, 351 raw?:RawInfo 352 } 354 Note: in HTTP/3, DATA frames can have arbitrarily large lengths to 355 reduce frame header overhead. As such, DATA frames can span many 356 QUIC packets and can be processed in a streaming fashion. In this 357 case, the frame_parsed event is emitted once for the frame header, 358 and further streamed data is indicated using the data_moved event. 360 3.1.6. push_resolved 362 Importance: Extra 364 This event is emitted when a pushed resource is successfully claimed 365 (used) or, conversely, abandoned (rejected) by the application on top 366 of HTTP/3 (e.g., the web browser). This event is added to help debug 367 problems with unexpected PUSH behaviour, which is commonplace with 368 HTTP/2. 370 { 371 push_id?:uint64, 372 stream_id?:uint64, // in case this is logged from a place that does not have access to the push_id 374 decision:"claimed"|"abandoned" 375 } 376 3.2. qpack 378 Note: like all category values, the "qpack" category is written in 379 lowercase. 381 The QPACK events mainly serve as an aid to debug low-level QPACK 382 issues. The higher-level, plaintext header values SHOULD (also) be 383 logged in the http.frame_created and http.frame_parsed event data 384 (instead). 386 Note: qpack does not have its own parameters_set event. This was 387 merged with http.parameters_set for brevity, since qpack is a 388 required extension for HTTP/3 anyway. Other HTTP/3 extensions MAY 389 also log their SETTINGS fields in http.parameters_set or MAY define 390 their own events. 392 3.2.1. state_updated 394 Importance: Base 396 This event is emitted when one or more of the internal QPACK 397 variables changes value. Note that some variables have two 398 variations (one set locally, one requested by the remote peer). This 399 is reflected in the "owner" field. As such, this field MUST be 400 correct for all variables included a single event instance. If you 401 need to log settings from two sides, you MUST emit two separate event 402 instances. 404 Data: 406 { 407 owner:"local" | "remote", 409 dynamic_table_capacity?:uint64, 410 dynamic_table_size?:uint64, // effective current size, sum of all the entries 412 known_received_count?:uint64, 413 current_insert_count?:uint64 414 } 416 3.2.2. stream_state_updated 418 Importance: Core 420 This event is emitted when a stream becomes blocked or unblocked by 421 header decoding requests or QPACK instructions. 423 Note: This event is of "Core" importance, as it might have a large 424 impact on HTTP/3's observed performance. 426 Data: 428 { 429 stream_id:uint64, 431 state:"blocked"|"unblocked" // streams are assumed to start "unblocked" until they become "blocked" 432 } 434 3.2.3. dynamic_table_updated 436 Importance: Extra 438 This event is emitted when one or more entries are inserted or 439 evicted from QPACK's dynamic table. 441 Data: 443 { 444 owner:"local" | "remote", // local = the encoder's dynamic table. remote = the decoder's dynamic table 446 update_type:"inserted"|"evicted", 448 entries:Array 449 } 451 class DynamicTableEntry { 452 index:uint64; 453 name?:string | bytes; 454 value?:string | bytes; 455 } 457 3.2.4. headers_encoded 459 Importance: Base 461 This event is emitted when an uncompressed header block is encoded 462 successfully. 464 Note: this event has overlap with http.frame_created for the 465 HeadersFrame type. When outputting both events, implementers MAY 466 omit the "headers" field in this event. 468 Data: 470 { 471 stream_id?:uint64, 473 headers?:Array, 475 block_prefix:QPackHeaderBlockPrefix, 476 header_block:Array, 478 length?:uint32, 479 raw?:bytes 480 } 482 3.2.5. headers_decoded 484 Importance: Base 486 This event is emitted when a compressed header block is decoded 487 successfully. 489 Note: this event has overlap with http.frame_parsed for the 490 HeadersFrame type. When outputting both events, implementers MAY 491 omit the "headers" field in this event. 493 Data: 495 { 496 stream_id?:uint64, 498 headers?:Array, 500 block_prefix:QPackHeaderBlockPrefix, 501 header_block:Array, 503 length?:uint32, 504 raw?:bytes 505 } 507 3.2.6. instruction_created 509 Importance: Base 511 This event is emitted when a QPACK instruction (both decoder and 512 encoder) is created and added to the encoder/decoder stream. 514 Data: 516 { 517 instruction:QPackInstruction // see appendix for the definitions, 519 length?:uint32, 520 raw?:bytes 521 } 523 Note: encoder/decoder semantics and stream_id's are implicit in 524 either the instruction types or can be logged via other events (e.g., 525 http.stream_type_set) 527 3.2.7. instruction_parsed 529 Importance: Base 531 This event is emitted when a QPACK instruction (both decoder and 532 encoder) is read from the encoder/decoder stream. 534 Data: 536 { 537 instruction:QPackInstruction // see appendix for the definitions, 539 length?:uint32, 540 raw?:bytes 541 } 543 Note: encoder/decoder semantics and stream_id's are implicit in 544 either the instruction types or can be logged via other events (e.g., 545 http.stream_type_set) 547 4. Security Considerations 549 TBD 551 5. IANA Considerations 553 TBD 555 6. References 557 6.1. Normative References 559 [QLOG-MAIN] 560 Marx, R., Ed., Niccolini, L., Ed., and M. Seemann, Ed., 561 "Main logging schema for qlog", draft-marx-qlog-main- 562 schema-04 (work in progress). 564 [QLOG-QUIC] 565 Marx, R., Ed., Niccolini, L., Ed., and M. Seemann, Ed., 566 "QUIC event definitions for qlog", draft-marx-quic-qlog- 567 quic-events-00 (work in progress). 569 [QUIC-HTTP] 570 Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 571 (HTTP/3)", draft-ietf-quic-http-latest (work in progress). 573 [QUIC-QPACK] 574 Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 575 Header Compression for HTTP over QUIC", draft-ietf-quic- 576 qpack-latest (work in progress). 578 6.2. Informative References 580 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 581 Requirement Levels", BCP 14, RFC 2119, 582 DOI 10.17487/RFC2119, March 1997, 583 . 585 6.3. URIs 587 [1] https://github.com/quiclog/internet-drafts 589 [2] https://github.com/quiclog/qlog/ 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 686 enum ApplicationError{ 687 http_no_error, 688 http_general_protocol_error, 689 http_internal_error, 690 http_stream_creation_error, 691 http_closed_critical_stream, 692 http_frame_unexpected, 693 http_frame_error, 694 http_excessive_load, 695 http_id_error, 696 http_settings_error, 697 http_missing_settings, 698 http_request_rejected, 699 http_request_cancelled, 700 http_request_incomplete, 701 http_early_response, 702 http_connect_error, 703 http_version_fallback 704 } 706 Appendix B. QPACK DATA type definitions 708 B.1. QPACK Instructions 710 Note: the instructions do not have explicit encoder/decoder types, 711 since there is no overlap between the insturctions of both types in 712 neither name nor function. 714 type QPackInstruction = SetDynamicTableCapacityInstruction | InsertWithNameReferenceInstruction | InsertWithoutNameReferenceInstruction | DuplicateInstruction | HeaderAcknowledgementInstruction | StreamCancellationInstruction | InsertCountIncrementInstruction; 716 B.1.1. SetDynamicTableCapacityInstruction 718 class SetDynamicTableCapacityInstruction { 719 instruction_type:string = "set_dynamic_table_capacity"; 721 capacity:uint32; 722 } 724 B.1.2. InsertWithNameReferenceInstruction 726 class InsertWithNameReferenceInstruction { 727 instruction_type:string = "insert_with_name_reference"; 729 table_type:"static"|"dynamic"; 731 name_index:uint32; 733 huffman_encoded_value:boolean; 735 value_length?:uint32; 736 value?:string; 737 } 739 B.1.3. InsertWithoutNameReferenceInstruction 741 class InsertWithoutNameReferenceInstruction { 742 instruction_type:string = "insert_without_name_reference"; 744 huffman_encoded_name:boolean; 746 name_length?:uint32; 747 name?:string; 749 huffman_encoded_value:boolean; 751 value_length?:uint32; 752 value?:string; 753 } 755 B.1.4. DuplicateInstruction 757 class DuplicateInstruction { 758 instruction_type:string = "duplicate"; 760 index:uint32; 761 } 763 B.1.5. HeaderAcknowledgementInstruction 765 class HeaderAcknowledgementInstruction { 766 instruction_type:string = "header_acknowledgement"; 768 stream_id:uint64; 769 } 771 B.1.6. StreamCancellationInstruction 773 class StreamCancellationInstruction { 774 instruction_type:string = "stream_cancellation"; 776 stream_id:uint64; 777 } 779 B.1.7. InsertCountIncrementInstruction 781 class InsertCountIncrementInstruction { 782 instruction_type:string = "insert_count_increment"; 784 increment:uint32; 785 } 787 B.2. QPACK Header compression 789 type QPackHeaderBlockRepresentation = IndexedHeaderField | LiteralHeaderFieldWithName | LiteralHeaderFieldWithoutName; 791 B.2.1. IndexedHeaderField 793 Note: also used for "indexed header field with post-base index" 795 class IndexedHeaderField { 796 header_field_type:string = "indexed_header"; 798 table_type:"static"|"dynamic"; // MUST be "dynamic" if is_post_base is true 799 index:uint32; 801 is_post_base:boolean = false; // to represent the "indexed header field with post-base index" header field type 802 } 803 B.2.2. LiteralHeaderFieldWithName 805 Note: also used for "Literal header field with post-base name 806 reference" 808 class LiteralHeaderFieldWithName { 809 header_field_type:string = "literal_with_name"; 811 preserve_literal:boolean; // the 3rd "N" bit 812 table_type:"static"|"dynamic"; // MUST be "dynamic" if is_post_base is true 813 name_index:uint32; 815 huffman_encoded_value:boolean; 816 value_length?:uint32; 817 value?:string; 819 is_post_base:boolean = false; // to represent the "Literal header field with post-base name reference" header field type 820 } 822 B.2.3. LiteralHeaderFieldWithoutName 824 class LiteralHeaderFieldWithoutName { 825 header_field_type:string = "literal_without_name"; 827 preserve_literal:boolean; // the 3rd "N" bit 829 huffman_encoded_name:boolean; 830 name_length?:uint32; 831 name?:string; 833 huffman_encoded_value:boolean; 834 value_length?:uint32; 835 value?:string; 836 } 838 B.2.4. QPackHeaderBlockPrefix 840 class QPackHeaderBlockPrefix { 841 required_insert_count:uint32; 842 sign_bit:boolean; 843 delta_base:uint32; 844 } 846 Appendix C. Change Log 847 C.1. Since draft-marx-qlog-event-definitions-quic-h3-02: 849 o These changes were done in preparation of the adoption of the 850 drafts by the QUIC working group (#137) 852 o Split QUIC and HTTP/3 events into two separate documents 854 o Moved RawInfo, Importance, Generic events and Simulation events to 855 the main schema document. 857 C.2. Since draft-marx-qlog-event-definitions-quic-h3-01: 859 Major changes: 861 o Moved data_moved from http to transport. Also made the "from" and 862 "to" fields flexible strings instead of an enum (#111,#65) 864 o Moved packet_type fields to PacketHeader. Moved packet_size field 865 out of PacketHeader to RawInfo:length (#40) 867 o Made events that need to log packet_type and packet_number use a 868 header field instead of logging these fields individually 870 o Added support for logging retry, stateless reset and initial 871 tokens (#94,#86,#117) 873 o Moved separate general event categories into a single category 874 "generic" (#47) 876 o Added "transport:connection_closed" event (#43,#85,#78,#49) 878 o Added version_information and alpn_information events 879 (#85,#75,#28) 881 o Added parameters_restored events to help clarify 0-RTT behaviour 882 (#88) 884 Smaller changes: 886 o Merged loss_timer events into one loss_timer_updated event 888 o Field data types are now strongly defined (#10,#39,#36,#115) 890 o Renamed qpack instruction_received and instruction_sent to 891 instruction_created and instruction_parsed (#114) 893 o Updated qpack:dynamic_table_updated.update_type. It now has the 894 value "inserted" instead of "added" (#113) 896 o Updated qpack:dynamic_table_updated. It now has an "owner" field 897 to differentiate encoder vs decoder state (#112) 899 o Removed push_allowed from http:parameters_set (#110) 901 o Removed explicit trigger field indications from events, since this 902 was moved to be a generic property of the "data" field (#80) 904 o Updated transport:connection_id_updated to be more in line with 905 other similar events. Also dropped importance from Core to Base 906 (#45) 908 o Added length property to PaddingFrame (#34) 910 o Added packet_number field to transport:frames_processed (#74) 912 o Added a way to generically log packet header flags (first 8 bits) 913 to PacketHeader 915 o Added additional guidance on which events to log in which 916 situations (#53) 918 o Added "simulation:scenario" event to help indicate simulation 919 details 921 o Added "packets_acked" event (#107) 923 o Added "datagram_ids" to the datagram_X and packet_X events to 924 allow tracking of coalesced QUIC packets (#91) 926 o Extended connection_state_updated with more fine-grained states 927 (#49) 929 C.3. Since draft-marx-qlog-event-definitions-quic-h3-00: 931 o Event and category names are now all lowercase 933 o Added many new events and their definitions 935 o "type" fields have been made more specific (especially important 936 for PacketType fields, which are now called packet_type instead of 937 type) 939 o Events are given an importance indicator (issue #22) 941 o Event names are more consistent and use past tense (issue #21) 942 o Triggers have been redefined as properties of the "data" field and 943 updated for most events (issue #23) 945 Appendix D. Design Variations 947 TBD 949 Appendix E. Acknowledgements 951 Much of the initial work by Robin Marx was done at Hasselt 952 University. 954 Thanks to Marten Seemann, Jana Iyengar, Brian Trammell, Dmitri 955 Tikhonov, Stephen Petrides, Jari Arkko, Marcus Ihlar, Victor 956 Vasiliev, Mirja Kuehlewind, Jeremy Laine, Kazu Yamamoto, Christian 957 Huitema, and Lucas Pardue for their feedback and suggestions. 959 Authors' Addresses 961 Robin Marx 962 KU Leuven 964 Email: robin.marx@kuleuven.be 966 Luca Niccolini (editor) 967 Facebook 969 Email: lniccolini@fb.com 971 Marten Seemann (editor) 972 Protocol Labs 974 Email: marten@protocol.ai