Draft: draft-ietf-quic-qlog-quic-events

Commentary: This is a subjective editorial change . The intent is to improve the readability of the document and expose better how we expect people to use the " name " field . By splitting out the overview of events from the definitions themselves , we achieve those intents . 
 Easier to review as 
 In general looks good , but I wonder if we should be pedantic about the link names / align them with the CDDL definition names . Concretely : The CDDL definition ID for the event is currently while the link to the section in this PR is . Furthermore , few of the other events in the transport category have the prefix in this PR , while they are consistently prefixed with in the CDDL block names . I of course have a preference for consistency and alignment , otherwise I would n't post this , but it 's not necessarily a hill I 'm willing to die on . Finally , this should have accompanying and similar PRs for the main and H3 documents down the line ( maybe make an issue so we do n't forget those ? ) 
 I have no issue with switching to consistent names . Initially I wanted to make the table multi - column and to keep its identifiers short . That 's not how it turned out , so I 'll push a fixup . 
 Yes . I did n't want to invest any more effort if the editor team did n't like this approach . I 'd suggest we refine this PR , get it merged , and then update the other documents using this as a template .
Paragraph (version A):
This document describes the values of the qlog "name" ("category" +
"event") and "data" fields and their semantics for the QUIC protocol.
Paragraph (version A):
This document assumes the usage of the encompassing main qlog schema
defined in QLOG-MAIN.  Each subsection below defines a separate
category (for example connectivity, transport, recovery) and each
subsubsection is an event type (for example "packet_received").
Paragraph (version A):
For each event type, its importance and data definition is laid out,
often accompanied by possible values for the optional "trigger"
field.  For the definition and semantics of "importance" and
"trigger", see the main schema document.
Paragraph (version A):
Most of the complex datastructures, enums and re-usable definitions
are grouped together on the bottom of this document for clarity.
Paragraph (version A):
This document re-uses all the fields defined in the main qlog schema
(e.g., name, category, type, data, group_id, protocol_type, the time-
related fields, importance, RawInfo, etc.).
Paragraph (version A):
One entry in the "protocol_type" qlog array field MUST be "QUIC" if
events from this document are included in a qlog trace.
Paragraph (version B):
The following fields from QLOG-MAIN are imported and used: name,
category, type, data, group_id, protocol_type, importance, RawInfo,
and time-related fields.
Paragraph (version B):
This document describes how the QUIC protocol is can be expressed in
qlog using the schema defined in QLOG-MAIN.  QUIC protocol events are
defined with a category, a name (the concatenation of "category" and
"event"), an "importance", an optional "trigger", and "data" fields.
Paragraph (version B):
Some data fields use complex datastructures.  These are represented
as enums or re-usable definitions, which are grouped together on the
bottom of this document for clarity.
Paragraph (version B):
When any event from this document is included in a qlog trace, the
"protocol_type" qlog array field MUST contain an entry with the value
"QUIC".
Paragraph (version A):
This document re-uses the definition of the RawInfo data class from
QLOG-MAIN.
Paragraph (version A):
Each subheading in this section is a qlog event category, while each
sub-subheading is a qlog event type.  Concretely, for the following
two items, we have the category "connectivity" and event type
"server_listening", resulting in a concatenated qlog "name" field
value of "connectivity:server_listening".
Paragraph (version B):
QUIC connections consist of different phases and interaction events.
In order to model this, QUIC event types are divided into general
categories: connectivity (conn-ev), security (sec-ev), transport
trans-ev, and recovery rec-ev.
Paragraph (version B):
As described in QLOG-MAIN, the qlog "name" field is the concatenation
of category and type.
Paragraph (version B):
quic-events summarizes the name value of each event type that is
defined in this specification.
Paragraph (version A):
Note: for more details on "datagram_ids", see datagram-id.
Paragraph (version B):
Note: for more details on "datagram_ids", see transport-
datagramssent.