jiebi/TextFlow huggingface dataset:
Original text:
Definition:  4. TBD

Reviewer comments:
While DPLPMTUD is optional, there's an about it in QUIC transport. Minimal support for this in qlog would define an event for every increase of the MTU: I don't think we need a separate event for the sending of an MTU probe packet, but we should probably standardize a for this. Suggestion: . Open question: Do we want a separate failure event? Failure would be either the loss of an MTU probe packet, or (for implementations that pay attention to ICMP packets) the receipt of an ICMP Packet Too Big (PTB) message.
I agree it would be useful to have this information in qlog. In terms of design, as always there are several options: 1) have separate events for this (, , , etc.) 2) integrate them into existing events( triggers on and , new field in ) 3) a combination of these approaches (which is what you suggest IIUC) This is imo a good example of where we need clear design guidelines on how to add new information/events to qlog.
Revisiting this after a long time: is problematic, as this would essentially be a copy of the normal event (it is allowed, although not recommended, to just send normal application data as a probe packet). The trigger seems to be the best solution here needs to be a separate event, there's just no way we can reasonably collapse this into an acknowledgment event is what I'm still undecided about. This logically belongs to the regular event, we'd just need a way to attach "oh and by the way, this was a MTU probe packet". In fact, it would be really useful to have it on that event, since the congestion control implications are very different for lost MTU packets (i.e., you wouldn't decrease your cwnd).
I have to disagree with myself here. The sending of the packet might have been triggered by something else, it's just that the stack decided to send a probe packet. I suggest: Add a optional on the and events. Add a event.
Supporting DPLPMTUTD events seems important to cover in the base specs.

Revised text:
Definition: <ins> 3.5. Importance: Extra This event indicates that the estimated Path MTU was updated.  This happens as part of the Path MTU discovery process. </ins> 4. TBD
Original text:
inclusion, log aggregation, event grouping and log file size reduction techniques.  Feedback and discussion are welcome at https://github.com/quicwg/qlog [1].  Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document. have a string key that maps to any value.  Used to indicate a generic JSON object.  1.1.2. <del> While the qlog schemas are format-agnostic, and can be serialized in many ways (e.g., JSON, CBOR, protobuf, ...), this document only describes how to employ JSON, its subset I-JSON, and its streamable derivative JSON-Text-Sequences as textual serialization options.  As such, examples are provided in JSON.  Other documents may describe how to utilize other concrete serialization options, though tips and requirements for these are also listed in this document (concrete- formats). </del>  2.

Reviewer comments:
There's too much text here that doesn't aid the reader. Delete it to be clear that we're using JSON as the notational convention for examples. If this text was valuable, it should be somewhere else.
I still feel we should have a "forward reference" here, indicating that we also discuss I-JSON and Streaming JSON considerations in this document, rather than making it seem we only do "pure JSON" due to the examples. Put differently, something like this should still be mentioned in this location imo:
But the fact it can be serialized to I-JSON has nothing to do with notational conventions used in this document, because we don't use any I-JSON.
NAME I just pushed a commit with a proposal to split up the original text to keep only a minimal amount in "Notational Conventions" but keep the core message alive in the introduction (which seemed the most logical location for now). I added the "unless otherwise indicated", as there are some examples of JSON-SEQ near the end of the document that obviously don't use RFC8259 notation directly. Please review and if approved, merge :)

Revised text:
inclusion, log aggregation, event grouping and log file size reduction techniques. <ins> The qlog schema can be serialized in many ways (e.g., JSON, CBOR, protobuf, etc).  This document describes only how to employ JSON, its subset I-JSON, and its streamable derivative JSON-Text-Sequences. </ins> Feedback and discussion are welcome at https://github.com/quicwg/qlog [1].  Readers are advised to refer to the "editor's draft" at that URL for an up-to-date version of this document. have a string key that maps to any value.  Used to indicate a generic JSON object. <ins> All timestamps and time-related values (e.g., offsets) in qlog are logged as "float64" in the millisecond resolution. Other qlog documents can define their own CDDL-compatible (struct) types (e.g., separately for each Packet type that a protocol supports). </ins> 1.1.2.  <ins> Serialization examples in this document use JSON (JSON) unless otherwise indicated. </ins> 2.
Original text:
For now, infer from other connectivity events and path_challenge/ path_response frames  3.2. 3.2.1. Definition: <del> 3.5. Importance: Extra This event indicates that the estimated Path MTU was updated.  This happens as part of the Path MTU discovery process. </del> 4. TBD

Reviewer comments:
Updates as that had some problems: used instead of for CDDL type in some of the definitions (not in others)... Made a separate category for the event. It's debatable imo whether it belongs in or , but it shouldn't be its own thing. In general, I feel was approved/merged too soon and this type of things should be checked for future PRs of a similar type.
Changes look good to me. First of all, sorry for messing up the type name. I'm not sure I agree that it was merge too soon though, was open for 3 months, and was approved by one of the editors. Sometimes it's better to make progress instead of not moving at all, even if some cleanup is necessary later.
NAME no problem, I mess up way worse than that :) Let me rephrase that to just "approved" too soon then, instead of "merged" too soon (which is again perfectly understandable with Lucas not used to watching for that type of issue, just wanted to indicate future approvals should).
From the discussion in , it seems better to keep this consistent with other events. Also noticed I forgot to prefix the event with Connectivity and add it to the CDDL list on the bottom...
Sorry if that's a stupid question, but why do we have an and a field here? I thought you can only set it once. Originally posted by NAME in URL
This is a fair question. This is most likely a copy-paste from one of the events (can't find evidence that this was once called StreamTypeUpdated though...) For updates this makes sense, but if the StreamType is only ever set once after becoming known, it would be better to change the definition to e.g., (note, is from ) :

Revised text:
For now, infer from other connectivity events and path_challenge/ path_response frames <ins> 3.1.9. Importance: Extra This event indicates that the estimated Path MTU was updated.  This happens as part of the Path MTU discovery process. </ins> 3.2. 3.2.1. Definition:  4. TBD
Original text:
Additionally, this document defines the following custom types for clarity:  The main general CDDL syntax conventions in this document a reader should be aware of for easy reading comprehension are: have a string key that maps to any value.  Used to indicate a generic JSON object. <del> All timestamps and time-related values (e.g., offsets) in qlog are logged as "float64" in the millisecond resolution. Other qlog documents can define their own CDDL-compatible (struct) types (e.g., separately for each Packet type that a protocol supports). </del> 1.1.2. While the qlog schemas are format-agnostic, and can be serialized in

Reviewer comments:
In the main schema document, there's a a chunk of text that says: The danger with restating things like this is that there is some subtle problem or incompatibility with the canonical CDDL source citation. I appreciate the QUIC WG might not be familiar with this syntax, so it's handy. But the long-term problems a more insidious. Consider replacing it with deep links to CDDL syntax, or sticking it behind a note that it will be removed prior to publication.
Yes, the intent is to remove this prior to publication. It's just there to make early adoption easier for now. Will look up how to properly add such a note (not sure if there's something default in the kramdown for that) and add it.

Revised text:
Additionally, this document defines the following custom types for clarity: <ins> All timestamps and time-related values (e.g., offsets) in qlog are logged as "float64" in the millisecond resolution. Other qlog documents can define their own CDDL-compatible (struct) types (e.g., separately for each Packet type that a protocol supports). </ins> The main general CDDL syntax conventions in this document a reader should be aware of for easy reading comprehension are: have a string key that maps to any value.  Used to indicate a generic JSON object.  1.1.2. While the qlog schemas are format-agnostic, and can be serialized in
Original text:
4.6. <del> TODO 4.7. </del> Importance: Base This event is used to track progress through QUIC's complex handshake state = handshake_confirmed <del> 4.8. </del>  e.g., path_updated For now, infer from other connectivity events and path_challenge/ path_response frames <del> 4.9. </del>  Importance: Extra

Reviewer comments:
Connection retried was never properly specced. The main reason is that a retried connection is completely separate from the original connection attempt, except for the value, and as such is usually logged in a separate file / separate context from the original connection qlog data. Current qlog deployments either have other ways of correlating retried connections with the original attempts, or don't need to do this. Either way, there is no tangible need for at this time.
I don't think that's correct. You also take your Connection IDs with you to the new connection. quic-go logs it to the same file, as it is the same connection attempt. I don't see value in though.

Revised text:
4.6.  Importance: Base This event is used to track progress through QUIC's complex handshake state = handshake_confirmed  <ins> 4.7. </ins> e.g., path_updated For now, infer from other connectivity events and path_challenge/ path_response frames  <ins> 4.8. </ins> Importance: Extra
Original text:
5.2.  5.2.1. 5.2.2. 8.11.  8.11.1. In QUIC, PADDING frames are simply identified as a single byte of

Reviewer comments:
In doing the exercise to try and define a new DATAGRAM extension for qlog (at URL), it became clear that we only had a CDDL extension point for the events themselves () but NOT for the individual QUIC and HTTP/3 frames. This is needed so we can add the CDDL definitions for new frames in other documents and have them properly matched to the CDDL expectations of "main document" events like and .
LGTM modulo some editorial nits

Revised text:
5.2. <ins> The generic "$HTTPFrame" is defined here as a CDDL extension point (a "socket" or "plug").  It can be extended to support additional HTTP/3 frame types. The HTTP/3 frame types defined in this document are as follows: </ins> 5.2.1. 5.2.2. 8.11. <ins> The generic "$QuicFrame" is defined here as a CDDL extension point (a "socket" or "plug").  It can be extended to support additional QUIC frame types. The QUIC frame types defined in this document are as follows: </ins> 8.11.1. In QUIC, PADDING frames are simply identified as a single byte of
Original text:
2.1.  2.2. A single qlog event trace is typically associated with a single QUIC

Reviewer comments:
This field is not particularly useful, because it will always be 16, see URL it's a property of the TLS cipher suite in use, so it can be trivially looked up, if necessary
So this is a bit of a tough one for me, since I've gone through the pain of trying to determine the length of the TLS trailer for TLS-over-TCP from wireshark output that does NOT explicitly include the size and also makes it difficult to get the proper cipher name to heuristically determine it. That said, for QUIC V1 it's indeed all 16, so you -could- make an argument we can drop it here and add it back in with a V2.1/V3 if new ciphers start being used. I don't have a particularly big preference either way. If we do this change though, the prose could use tightening, because in the current version we have 2 sentences after another that indicate the aead_length depends on the cipher suite.
I'm leaning on the side of removing this field. The information is made redundant by the cipher suite. Things that care about the tag length can do a lookup or make their own assumptions based on other information
Discussed on call. NAME will make the requested prose change and should be good to go.
Rebased and tightened the text around the tag length.
Minus the comment above, this LGTM.

Revised text:
2.1. <ins> QUIC packets always include an AEAD authentication tag at the end. In general, the length of the AEAD tag depends on the TLS cipher suite, although all cipher suites used in QUIC v1 use a 16 byte tag. </ins> 2.2. A single qlog event trace is typically associated with a single QUIC
Original text:
"application" // e.g., HTTP/3's GOAWAY frame  5.1.7. e.g., path_updated

Reviewer comments:
Partially Main change is adding as a PacketType. The is added as a field to packetsent and packetreceived. Any of the "unpredictable bits" can be logged as Added a trigger to to indicate if a connection goes into draining/closing because a valid statelessreset was received. Backwards compatibility break: renamed to on the NewConnectionID frame definition (for consistency). Been thinking about a way to signal an "invalid" stateless reset, but figured there is no way to distinguish it from an otherwise garbage datagram, so decided it was impossible. Not 100% sure about the "looping case" where you continually lower the packet size. Maybe that's solved by adding a generic "packetsize" trigger value to though?
LGTM!
These concepts were in flux when -01 was made and are now much more settled. Any thoughts on how to best approach this are more than welcome.
For stateless reset, I can see two options: make it a new PacketType and then simply use / make it a new event type with custom semantics At least one implementer has indicated a preference for (1), since their stack only intends to support the core events.
For stateless reset, both works for me. Most important thing is to get a way to log it at all, since this would be an interesting signal in production.

Revised text:
"application" // e.g., HTTP/3's GOAWAY frame <ins> "stateless_reset" // because a stateless reset was received </ins> 5.1.7. e.g., path_updated
Original text:
Importance: Extra <del> This event is emitted when the single recovery loss timer is set. </del>  Data: these events need to be?  Just support QUIC-style recovery from the spec or broader? <del> Triggers: TODO </del>  5.4.5. <del> Importance: Extra This event is emitted when the single recovery loss timer fires. Data: 5.4.6. </del> Importance: Core This event is emitted when a packet is deemed lost by loss detection. "pto_expired" // draft-23 section 5.3.1, MAY <del> 5.4.7. </del>  Importance: Extra

Reviewer comments:
Not 100% sure this is enough for all the latest draft-27(+) changes though, added a TODO in the draft for that purpose. Also added a packetnumberspace field to metrics_updated to be flexible for implementations that don't want to implement all types of events. It's not a great fit at that location, but it seemed the most synergistic without having a completely new event type. PTAL NAME
Currently, we log in . However, we can have multiple PTO's running across multiple PN spaces and there is no proper way to correlate them with a PN space in metricsupdated. This also impacts the event types. Possible resolutions: Add pnspace attribute to Split PTO count into a separate event (potentially merge with loss_timer?) TODO: reason more about how these metrics are tied to PN spaces in general (are there others than PTO that are duplicated) cc NAME
Most other metrics in the event are independent of the PN space, so that would be weird. I'd prefer to do that. Not sure if it makes sense to merge is with the loss timer events, since we also need to be able to log a reset of the PTO count to 0 (which doesn't require setting of a timer).

Revised text:
Importance: Extra  <ins> This event is emitted when a recovery loss timer changes state.  The three main event types are: set: the timer is set with a delta timeout for when it will trigger next expired: when the timer effectively expires after the delta timeout cancelled: when a timer is cancelled (e.g., all outstanding packets are acknowledged, start idle period) Note: to indicate an active timer's timeout update, a new "set" event is used. </ins> Data: these events need to be?  Just support QUIC-style recovery from the spec or broader?  <ins> TODO: read up on the loss detection logic in draft-27+ and see if this suffices </ins> 5.4.5.  Importance: Core This event is emitted when a packet is deemed lost by loss detection. "pto_expired" // draft-23 section 5.3.1, MAY  <ins> 5.4.6. </ins> Importance: Extra
Original text:
"unsupported_version"  Note: sometimes packets are dropped before they can be associated with a particular connection (e.g., in case of "unsupported_version").  This situation is discussed in handling-

Reviewer comments:
Per discussion on slack, and can be merged into , given that we have a field for the disambiguation.
NAME Done. Updated the PR.

Revised text:
"unsupported_version" <ins> "unexpected_packet" "unexpected_source_connection_id" "unexpected_version" </ins> Note: sometimes packets are dropped before they can be associated with a particular connection (e.g., in case of "unsupported_version").  This situation is discussed in handling-
Original text:
packets. A client MAY also clear the QUIC Bit in Initial packets that are sent <del> to establish a new connection.  A client can only clear the QUIC Bit if the packet includes a token provided by the server in a NEW_TOKEN frame on a connection where the server also included the grease_quic_bit transport parameter.  To allow for changes in server configuration, clients SHOULD set the QUIC Bit if the token was provided more than 7 days prior. </del>  3.2.

Reviewer comments:
At the moment, the paragraph says "Initial packets that are sent to establish a new connection." That is unclear. It is possible to interpret this text as "all Initial packets that the client sends," because all the Initial packets are used to establish a new connection. As the paragraph right above discusses what endpoints should do once they receive transport parameters, we can be clear that this paragraph discusses what should be done until then.
Thanks Kazuho, this is definitely clearer. WDYT of the tweak?

Revised text:
packets. A client MAY also clear the QUIC Bit in Initial packets that are sent  <ins> prior to receiving transport parameters from the server.  A client can only clear the QUIC Bit if such packets include a token provided by the server in a NEW_TOKEN frame on a connection where the server also included the grease_quic_bit transport parameter.  To allow for changes in server configuration, clients SHOULD set the QUIC Bit if the token was provided more than 7 days prior. </ins> 3.2.
Original text:
sent in addition to the grease_quic_bit transport parameter.  Though the value of the QUIC Bit in packets received by a peer might be set according to rules defined by the extension, they might also be <del> randomized according to the definition of the grease_quic_bit extension.  Receiving the transport parameter for the extension could be used to confirm that a peer supports the semantic defined in the extension.  To avoid acting on a randomized signal, the extension can require that endpoints set the QUIC Bit according to the rules of the extension, but defer acting on the information conveyed until the transport parameter for the extension is received. </del>  Extensions that define semantics for the QUIC Bit can be negotiated without using the grease_quic_bit transport parameter.

Reviewer comments:
This was unclear as it wasn't clear which extension was operative in the sentence.
changes lgtm

Revised text:
sent in addition to the grease_quic_bit transport parameter.  Though the value of the QUIC Bit in packets received by a peer might be set according to rules defined by the extension, they might also be  <ins> randomized as specified in this document.  Receiving the transport parameter for the extension could be used to confirm that a peer supports the semantic defined in the extension.  To avoid acting on a randomized signal, the extension can require that endpoints set the QUIC Bit according to the rules of the extension, but defer acting on the information conveyed until the transport parameter for the extension is received. </ins> Extensions that define semantics for the QUIC Bit can be negotiated without using the grease_quic_bit transport parameter.
Original text:
The second-to-most significant bit of the first byte in every QUIC packet is defined as having a fixed value in QUIC version 1 QUIC. <del> The purpose of having a fixed value is to allow intermediaries and endpoints to efficiently distinguish between QUIC and other protocols; see DEMUX for a description of a scheme that QUIC can integrate with as a result.  As this bit effectively identifies a packet as QUIC, it is sometimes referred to as the "QUIC Bit". </del>  Where endpoints and the intermediaries that support them do not depend on the QUIC Bit having a fixed value, sending the same value

Reviewer comments:
This is also fewer words :)
URL there is no definition of what an intermediary stands for here to understand the statement. I think rather defining the "intermediary" we can rephrase to inform the original intention of the fixed bit in QUIC packet i.e. coexistence with protocols in RFC7983. The statement here also gives an impression that any node in the network should be able to efficiently distinguish QUIC packets where in our OPS draft we are saying this is not reliable with a notion of "don't use it". so rephrasing should also help from this point of view. I would propose something like this - The purpose of having a fixed value is to allow coexistance with other protocols in ] . As this bit can be used to identify a packet as QUIC, it is sometimes referred to as the "QUIC Bit".

Revised text:
The second-to-most significant bit of the first byte in every QUIC packet is defined as having a fixed value in QUIC version 1 QUIC.  <ins> The purpose of having a fixed value is to allow QUIC to be efficiently distinguished from other protocols; see DEMUX for a description of a system that might use this property.  As this bit can identify a packet as QUIC, it is sometimes referred to as the "QUIC Bit". </ins> Where endpoints and the intermediaries that support them do not depend on the QUIC Bit having a fixed value, sending the same value
Original text:
The grease_quic_bit transport parameter (0x2ab2) can be sent by both client and server.  The transport parameter is sent with an empty value; an endpoint that understands this transport parameter MUST <del> treat receipt of a non-empty value as a connection error of type TRANSPORT_PARAMETER_ERROR. </del>  An endpoint that advertises the grease_quic_bit transport parameter MUST accept packets with the QUIC Bit set to a value of 0.  The QUIC

Reviewer comments:
Broken into separate changes; see the commentary on each. This won't rebase nicely with , but I can manage that later.

Revised text:
The grease_quic_bit transport parameter (0x2ab2) can be sent by both client and server.  The transport parameter is sent with an empty value; an endpoint that understands this transport parameter MUST  <ins> treat receipt of a non-empty value of the transport parameter as a connection error of type TRANSPORT_PARAMETER_ERROR. </ins> An endpoint that advertises the grease_quic_bit transport parameter MUST accept packets with the QUIC Bit set to a value of 0.  The QUIC