Provide clearer usage advice

[rmarx]

At the moment, it's not entirely clear how qlog is "supposed to be used".

For example, it's not clear to implementers why some fields (e.g., quic version) are duplicated across connection_started and also the PacketHeader.

We should provide some examples of what things look like if you implement "all of qlog" and what should happen if you only implement the Core events (i.e., some fields in the Core events can be skipped if you're using the Base or Extra events instead). This is also important info for tool implementers.

This also depends on the use case: tracing while debugging vs production-level logging.

[rmarx]

Thinking about this more, this seems to have become an untenable situation going forward to -03. qlog straddles the weird line between being a replacement for pcaps, as well as having to provide events for logging conceptual events not reflected in pcaps.

This was fine in the beginning, as everyone can/did log packet contents (e.g., ACK frames) and we could skip many events related to things clear from the wire (e.g., packet_acked or flow_control_updated etc.). However, for implementations that would not want to log the wire image itself, we would have to add these latter types of events for everything... (ref #107). Tools would then also have to be flexible enough to get this info both from frames and these other events.

Long story short: we're tying to be a one-stop-shop, defining everything. That might be fine, but then we probably need to explicitly and quite clearly split up the wire-image events from the conceptual events (and provide alternatives for all and clear guidance).

This really could use wider discussion.

[rmarx]

We had a clear example today of how a separate flow_control_updated event is useful. A misbehaving client was lowering flow control limits (probably because it retransmits FC frames as they were in the past, rather than create a new FC update with new limits). qvis showed this as lowering the limits, even though the server probably didn't actually apply the lower limits at its end. It was good that qvis showed the limits (leading to the discovery of this problem), but it again highlights that there is a difference between receipt of a given frame and how that's actually applied in the implementation.

[LPardue]

Sounds like we want to focus on transport-related events in qlog and tell people that logging what your implementation_does_ with those can aid analysis or debug. This is an implementation choice. And general-purpose tooling is unlikely to support implementation-specific needs or data. I'd think most people could live with that because it is logical.

What else might we want to say?

In future, if people are always logging some application-specific field and want to ask their tool vendor to support it. That's probaby a good time for them to engage in the community.

[LPardue]

Marking this as editorial since I don't think there's anything we can do apart from reiterate that qlog doesn't cover everything and that it extensible enough to support individual needs.

Requests for adding design changes to these drafts can be raised as new issues (albeit at this stage likely to be declined unless there is sufficient evidence that it is needed).