From f49944b737ff33d0e0e985482b86871469918ff8 Mon Sep 17 00:00:00 2001 From: Marten Seemann Date: Fri, 13 Oct 2023 14:05:47 +0700 Subject: [PATCH] README: add qlog to list of supported RFCs, add an example (#4102) --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 976a07cc..e6beb8aa 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ In addition to these base RFCs, it also implements the following RFCs: * Unreliable Datagram Extension ([RFC 9221](https://datatracker.ietf.org/doc/html/rfc9221)) * Datagram Packetization Layer Path MTU Discovery (DPLPMTUD, [RFC 8899](https://datatracker.ietf.org/doc/html/rfc8899)) * QUIC Version 2 ([RFC 9369](https://datatracker.ietf.org/doc/html/rfc9369)) +* QUIC Event Logging using qlog ([draft-ietf-quic-qlog-main-schema](https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/) and [draft-ietf-quic-qlog-quic-events](https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-quic-events/)) ## Using QUIC @@ -174,6 +175,30 @@ msg, err := conn.ReceiveMessage() Note that this code path is currently not optimized. It works for datagrams that are sent occasionally, but it doesn't achieve the same throughput as writing data on a stream. Please get in touch on issue #3766 if your use case relies on high datagram throughput, or if you'd like to help fix this issue. There are also some restrictions regarding the maximum message size (see #3599). +### QUIC Event Logging using qlog + +quic-go logs a wide range of events defined in [draft-ietf-quic-qlog-quic-events](https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-quic-events/), providing comprehensive insights in the internals of a QUIC connection. + +qlog files can be processed by a number of 3rd-party tools. [qviz](https://qvis.quictools.info/) has proven very useful for debugging all kinds of QUIC connection failures. + +qlog is activated by setting a `Tracer` callback on the `Config`. It is called as soon as quic-go decides to starts the QUIC handshake on a new connection. +A useful implementation of this callback could look like this: +```go +quic.Config{ + Tracer: func(ctx context.Context, p logging.Perspective, connID quic.ConnectionID) *logging.ConnectionTracer { + role := "server" + if p == logging.PerspectiveClient { + role = "client" + } + filename := fmt.Sprintf("./log_%x_%s.qlog", connID, role) + f, err := os.Create(filename) + // handle the error + return qlog.NewConnectionTracer(f, p, connID) + } +} +``` + +This implementation of the callback creates a new qlog file in the current directory named `log__.qlog`. ## Using HTTP/3