Draft: draft-ietf-quic-qlog-main-schema

Commentary: found one thing to fix . approving to unblock you though . Feel free to merge after fixing the typolgtm , modulo comments
Paragraph (version A):
A qlog file should be able to contain several indivdual traces and
logs from multiple vantage points that are in some way related.  To
that end, the top-level element in the qlog schema defines only a
small set of "header" fields and an array of component traces.  For
this document, the required "qlog_version" field MUST have a value of
"0.3".
Paragraph (version B):
A qlog file should be able to contain several individual traces and
logs from multiple vantage points that are in some way related.  To
that end, the top-level element in the qlog schema defines only a
small set of "header" fields and an array of component traces.  For
this document, the required "qlog_version" field MUST have a value of
"0.3".
Paragraph (version A):
The "time" field indicates the timestamp at which the event occured.
Its value is typically the Unix timestamp since the 1970 epoch
(number of milliseconds since midnight UTC, January 1, 1970, ignoring
leap seconds).  However, qlog supports two more succint timestamps
formats to allow reducing file size.  The employed format is
indicated in the "time_format" field, which allows one of three
values: "absolute", "delta" or "relative".
Paragraph (version B):
The "time" field indicates the timestamp at which the event occurred.
Its value is typically the Unix timestamp since the 1970 epoch
(number of milliseconds since midnight UTC, January 1, 1970, ignoring
leap seconds).  However, qlog supports two more succinct timestamps
formats to allow reducing file size.  The employed format is
indicated in the "time_format" field, which allows one of three
values: "absolute", "delta" or "relative".
Paragraph (version A):
Events in each individual trace SHOULD be logged in strictly
ascending timestamp order (though not necessarily absolute value, for
the "delta" format).  Tools CAN sort all events on the timestamp
before processing them, though are not required to (as this could
impose a significant processing overhead).  This can be a problem
especially for multi-threaded and/or streaming loggers, who could
consider using a separate postprocesser to order qlog events in time
if a tool do not provide this feature.
Paragraph (version B):
Events in each individual trace SHOULD be logged in strictly
ascending timestamp order (though not necessarily absolute value, for
the "delta" format).  Tools CAN sort all events on the timestamp
before processing them, though are not required to (as this could
impose a significant processing overhead).  This can be a problem
especially for multi-threaded and/or streaming loggers, who could
consider using a separate post-processor to order qlog events in time
if a tool do not provide this feature.
Paragraph (version A):
The data field is a generic object.  It contains the per-event
metadata and its form and semantics are defined per specific sort of
event.  For example, data field value definitons for QUIC and HTTP/3
can be found in QLOG-QUIC and QLOG-H3.
Paragraph (version B):
The data field is a generic object.  It contains the per-event
metadata and its form and semantics are defined per specific sort of
event.  For example, data field value definitions for QUIC and HTTP/3
can be found in QLOG-QUIC and QLOG-H3.
Paragraph (version A):
In qlog, the optional "trigger" field contains a string value
describing the reason (if any) for this event instance occuring, see
data-field.  While this "trigger" field could be a property of the
qlog Event itself, it is instead a property of the "data" field
instead.  This choice was made because many event types do not
include a trigger value, and having the field at the Event-level
would cause overhead in some serializations.  Additional information
on the trigger can be added in the form of additional member fields
of the "data" field value, yet this is highly implementation-
specific, as are the trigger field's string values.
Paragraph (version B):
In qlog, the optional "trigger" field contains a string value
describing the reason (if any) for this event instance occurring, see
data-field.  While this "trigger" field could be a property of the
qlog Event itself, it is instead a property of the "data" field
instead.  This choice was made because many event types do not
include a trigger value, and having the field at the Event-level
would cause overhead in some serializations.  Additional information
on the trigger can be added in the form of additional member fields
of the "data" field value, yet this is highly implementation-
specific, as are the trigger field's string values.
Paragraph (version A):
The "common_fields" field is a generic dictionary of key-value pairs,
where the key is always a string and the value can be of any type,
but is typically also a string or number.  As such, unknown entries
in this dictionary MUST be disregarded by the user and tools (i.e.,
the presence of an uknown field is explicitly NOT an error).
Paragraph (version B):
The "common_fields" field is a generic dictionary of key-value pairs,
where the key is always a string and the value can be of any type,
but is typically also a string or number.  As such, unknown entries
in this dictionary MUST be disregarded by the user and tools (i.e.,
the presence of an unknown field is explicitly NOT an error).
Paragraph (version A):
There are several ways of defining qlog events.  In practice, we have
seen two main types used so far: a) those that map directly to
concepts seen in the protocols (e.g., "packet_sent") and b) those
that act as aggregating events that combine data from several
possible protocol behaviours or code paths into one (e.g.,
"parameters_set").  The latter are typically used as a means to
reduce the amount of unique event definitions, as reflecting each
possible protocol event as a separate qlog entity would cause an
explosion of event types.
Paragraph (version B):
There are several ways of defining qlog events.  In practice, we have
seen two main types used so far: a) those that map directly to
concepts seen in the protocols (e.g., "packet_sent") and b) those
that act as aggregating events that combine data from several
possible protocol behaviors or code paths into one (e.g.,
"parameters_set").  The latter are typically used as a means to
reduce the amount of unique event definitions, as reflecting each
possible protocol event as a separate qlog entity would cause an
explosion of event types.
Paragraph (version A):
The "Extra" events are considered mostly useful for low-level
debugging of the implementation, rather than the protocol.  They
allow more fine-grained tracking of internal behaviour.  As such,
they CAN be present in qlog files and tool implementers CAN add
support for these, but they are not required to.
Paragraph (version B):
The "Extra" events are considered mostly useful for low-level
debugging of the implementation, rather than the protocol.  They
allow more fine-grained tracking of internal behavior.  As such, they
CAN be present in qlog files and tool implementers CAN add support
for these, but they are not required to.
Paragraph (version A):
While qlog is a more high-level logging format, it also allows the
inclusion of most raw wire image information, such as byte lengths
and even raw byte values.  This can be useful when for example
investigating or tuning packetization behaviour or determining
encoding/framing overheads.  However, these fields are not always
necessary and can take up considerable space if logged for each
packet or frame.  They can also have a considerable privacy and
security impact.  As such, they are grouped in a separate optional
field called "raw" of type RawInfo (where applicable).
Paragraph (version B):
While qlog is a more high-level logging format, it also allows the
inclusion of most raw wire image information, such as byte lengths
and even raw byte values.  This can be useful when for example
investigating or tuning packetization behavior or determining
encoding/framing overheads.  However, these fields are not always
necessary and can take up considerable space if logged for each
packet or frame.  They can also have a considerable privacy and
security impact.  As such, they are grouped in a separate optional
field called "raw" of type RawInfo (where applicable).
Paragraph (version A):
We do not specify explicit header_length or trailer_length fields.
In most protocols, header_length can be calculated by subtracing
the payload_length from the length (e.g., if trailer_length is
always 0).  In protocols with trailers (e.g., QUIC's AEAD tag),
event definitions documents SHOULD define other ways of logging
the trailer_length to make the header_length calculation possible.
Paragraph (version B):
We do not specify explicit header_length or trailer_length fields.
In most protocols, header_length can be calculated by subtracting
the payload_length from the length (e.g., if trailer_length is
always 0).  In protocols with trailers (e.g., QUIC's AEAD tag),
event definitions documents SHOULD define other ways of logging
the trailer_length to make the header_length calculation possible.
Paragraph (version A):
Relatedly, many modern protocols use Variable-Length Integer
Encoded (VLIE) values in their headers, which are of a dynamic
length.  Because of this, we cannot deterministally reconstruct
the header encoding/length from non-RawInfo qlog data, as
implementations might not necessarily employ the most efficient
VLIE scheme for all values.  As such, to make exact size-analysis
possible, implementers should use explicit lengths in RawInfo
rather than reconstructing them from other qlog data.  Similarly,
tool developers should only utilize RawInfo (and related
information) in such tools to prevent errors.
Paragraph (version B):
Relatedly, many modern protocols use Variable-Length Integer
Encoded (VLIE) values in their headers, which are of a dynamic
length.  Because of this, we cannot deterministically reconstruct
the header encoding/length from non-RawInfo qlog data, as
implementations might not necessarily employ the most efficient
VLIE scheme for all values.  As such, to make exact size-analysis
possible, implementers should use explicit lengths in RawInfo
rather than reconstructing them from other qlog data.  Similarly,
tool developers should only utilize RawInfo (and related
information) in such tools to prevent errors.
Paragraph (version A):
Tools MUST NOT produce breaking errors for any field names and/or
values in the qlog format that they do not recognize.  Tools SHOULD
indicate even unknown event occurences within their context (e.g.,
marking unknown events on a timeline for manual interpretation by the
user).
Paragraph (version B):
Tools MUST NOT produce breaking errors for any field names and/or
values in the qlog format that they do not recognize.  Tools SHOULD
indicate even unknown event occurrences within their context (e.g.,
marking unknown events on a timeline for manual interpretation by the
user).
Paragraph (version A):
Note: QUIC implementations SHOULD mainly log the simplified
bidirectional (HTTP/2-alike) stream states (e.g., idle, open, closed)
instead of the more finegrained stream states (e.g., data_sent,
reset_received).  These latter ones are mainly for more in-depth
debugging.  Tools SHOULD be able to deal with both types equally.
Paragraph (version B):
Note: QUIC implementations SHOULD mainly log the simplified
bidirectional (HTTP/2-alike) stream states (e.g., idle, open, closed)
instead of the more fine-grained stream states (e.g., data_sent,
reset_received).  These latter ones are mainly for more in-depth
debugging.  Tools SHOULD be able to deal with both types equally.
Paragraph (version A):
The "trigger" field SHOULD be logged if there are multiple ways in
which a state change can occur but MAY be omitted if a given state
can only be due to a single event occuring (e.g., slow start is
exited only when ssthresh is exceeded).
Paragraph (version B):
The "trigger" field SHOULD be logged if there are multiple ways in
which a state change can occur but MAY be omitted if a given state
can only be due to a single event occurring (e.g., slow start is
exited only when ssthresh is exceeded).
Paragraph (version A):
This event indicates which data was marked for retransmit upon
detecing a packet loss (see packet_lost).  Similar to our reasoning
for the "frames_processed" event, in order to keep the amount of
different events low, we group this signal for all types of
retransmittable data in a single event based on existing QUIC frame
definitions.
Paragraph (version A):
Implementations retransmitting full packets or frames directly can
just log the consituent frames of the lost packet here (or do away
with this event and use the contents of the packet_lost event
instead).  Conversely, implementations that have more complex logic
(e.g., marking ranges in a stream's data buffer as in-flight), or
that do not track sent frames in full (e.g., only stream offset +
length), can translate their internal behaviour into the appropriate
frame instance here even if that frame was never or will never be put
on the wire.
Paragraph (version B):
This event indicates which data was marked for retransmit upon
detecting a packet loss (see packet_lost).  Similar to our reasoning
for the "frames_processed" event, in order to keep the amount of
different events low, we group this signal for all types of
retransmittable data in a single event based on existing QUIC frame
definitions.
Paragraph (version B):
Implementations retransmitting full packets or frames directly can
just log the constituent frames of the lost packet here (or do away
with this event and use the contents of the packet_lost event
instead).  Conversely, implementations that have more complex logic
(e.g., marking ranges in a stream's data buffer as in-flight), or
that do not track sent frames in full (e.g., only stream offset +
length), can translate their internal behaviour into the appropriate
frame instance here even if that frame was never or will never be put
on the wire.