1QUIC: Debugging and Tracing
2===========================
3
4When debugging the QUIC stack it is extremely useful to have protocol traces
5available. There are two approaches you can use to obtain this data:
6
7- qlog
8- Packet capture
9
10Neither of these approaches is strictly superior to the other and both have pros
11and cons:
12
13- In general, qlog is aimed at storing only information relevant to the
14  QUIC protocol itself without storing bulk data. This includes both transmitted
15  and received packets but also information about the internal state of a QUIC
16  implementation which is not directly observable from the network.
17
18- By comparison, packet capture stores all packets in their entirety.
19  Packet captures are thus larger, but they also provide more complete
20  information in general and do not have information removed. On the other hand,
21  because they work from a network viewpoint, they cannot provide direct
22  information on the internal state of a QUIC implementation. For example,
23  packet capture cannot directly tell you when an implementation deems a packet
24  lost.
25
26Both of these approaches have good GUI visualisation tools available for viewing
27the logged data.
28
29To summarise:
30
31- qlog:
32  - Pro: Smaller files
33  - Con: May leave out data assumed to be irrelevant
34  - Pro: Information on internal states and decisions made by a QUIC
35    implementation
36  - Pro: No need to obtain a keylog
37- PCAP:
38  - Pro: Complete capture
39  - Con: No direct information on internal states of a QUIC implementation
40  - Con: Need to obtain a keylog
41
42Using qlog
43----------
44
45To enable qlog you must:
46
47- build using the `enable-unstable-qlog` build-time configuration option;
48
49- set the environment variable `QLOGDIR` to a directory where qlog log files
50  are to be written;
51
52- set the environment variable `OSSL_QFILTER` to a filter specifying the events
53  you want to be written (set `OSSL_QFILTER='*'` for all events).
54
55Any process using the libssl QUIC implementation will then automatically write
56qlog files in the JSON-SEQ format to the specified directory. The files have the
57naming convention recommended by the specification: `{ODCID}_{ROLE}.sqlog`,
58where `{ODCID}` is the initial (original) DCID of a connection and `{ROLE}` is
59`client` or `server`.
60
61The log files can be loaded into [qvis](https://qvis.quictools.info/). The [qvis
62website](https://qvis.quictools.info/) also has some sample qlog files which you
63can load at the click of a button, which enables you to see what kind of
64information qvis can offer you.
65
66Note that since the qlog specification is not finalised and still evolving,
67the format of the output may change, as may the method of configuring this
68logging support.
69
70Currently this implementation tracks qvis's qlog support, as that is the
71main target use case at this time.
72
73Note that since qlog emphasises logging only data which is relevant to a QUIC
74protocol implementation, for the purposes of reducing the volume of logging
75data, application data is generally not logged. (However, this is not a
76guarantee and must not be relied upon from a privacy perspective.)
77
78[See here for more details on the design of the qlog facility.](qlog.md)
79
80Using PCAP
81----------
82
83To use PCAP you can use any standard packet capture tool, such as Wireshark or
84tcpdump (e.g. `tcpdump -U -i "$IFACE" -w "$FILE" 'udp port 1234'`).
85
86**Using Wireshark.** Once you have obtained a packet capture as a standard
87`pcap` or `pcapng` file, you can load it into Wireshark, which has excellent
88QUIC protocol decoding support.
89
90**Activating the decoder.** If you are using QUIC on a port not known to be
91commonly used for QUIC, you may need to tell Wireshark to try and decode a flow
92as QUIC. To do this, right click on the Protocol column and select “Decode
93As...”. Click on “(none)” under the Current column and select QUIC.
94
95**Keylogs.** Since QUIC is an encrypted protocol, Wireshark cannot provide much
96information without access to the encryption keys used for the connection
97(though it is able to decrypt Initial packets).
98
99In order to provide this information you need to provide Wireshark with a keylog
100file. This is a log file containing encryption keys for the connection which is
101written directly by a QUIC implementation for debugging purposes. The purpose of
102such a file is to enable a TLS or QUIC session to be decrypted for development
103purposes in a lab environment. It should go without saying that the export of a
104keylog file should never be used in a production environment.
105
106For the OpenSSL QUIC implementation, OpenSSL must be instructed to save a keylog
107file using the SSL_CTX_set_keylog_callback(3) API call. If the application you
108are using does not provide a way to enable this functionality, this requires
109recompiling the application you are using as OpenSSL does not provide a way
110to enable this functionality directly.
111
112If you are using OpenSSL QUIC to talk to another QUIC implementation, you also
113may be able to obtain a keylog from that other implementation. (It does not
114matter from which side of the connection you obtain the keylog.)
115
116Once you have a keylog file you can configure Wireshark to use it.
117There are two ways to do this:
118
119- **Manual configuration.** Select Edit →
120  Preferences and navigate to Protocols → TLS. Enter the path to the keylog file
121  under “(Pre)-Master-Secret log filename". You can have key information being
122  appended to this log continuously if desired. Press OK and Wireshark should
123  now be able to decrypt any TLS or QUIC session described by the log file.
124
125- **Embedding.** Alternatively, you can embed a keylog file into a `.pcapng`
126  file directly, so that Wireshark can decrypt the packets automatically when
127  the packet capture file is opened. This avoids the need to have a centralised
128  key log file and ensures that the key log for a specific packet capture is
129  kept together with the captured packets. It is also highly useful if you want
130  to distribute a packet capture file publicly, for example for educational
131  purposes.
132
133  To embed a keylog, you can use the `editcap` command provided by Wireshark
134  after taking a packet capture (note that `tls` should be specified below
135  regardless of whether TLS or QUIC is being used):
136
137  ```bash
138  $ editcap --inject-secrets tls,$PATH_TO_KEYLOG_FILE \
139    "$INPUT_FILENAME" "$OUTPUT_FILENAME"
140  ```
141
142  This tool accepts `.pcap` or `.pcapng` input and will generate a `.pcapng`
143  output file.
144