1qlog Support 2============ 3 4qlog support is formed of two components: 5 6- A qlog API and implementation. 7- A JSON encoder API and implementation, which is used by the qlog 8 implementation. 9 10The API for the JSON encoder is detailed in [a separate document](json-encoder.md). 11 12qlog support will involve instrumenting various functions with qlog logging 13code. An example call site will look something like this: 14 15```c 16{ 17 QLOG_EVENT_BEGIN(qlog_instance, quic, parameters_set) 18 QLOG_STR("owner", "local") 19 QLOG_BOOL("resumption_allowed", 1) 20 QLOG_STR("tls_cipher", "AES_128_GCM") 21 QLOG_BEGIN("subgroup") 22 QLOG_U64("u64_value", 123) 23 QLOG_BIN("binary_value", buf, buf_len) 24 QLOG_END() 25 QLOG_EVENT_END() 26} 27``` 28 29Output Format 30------------- 31 32The output format is always the JSON-SEQ qlog variant. This has the advantage 33that each event simply involves concatenating another record to an output log 34file and does not require nesting of syntactic constructs between events. 35 36Output is written to a directory containing multiple qlog files. 37 38Basic Usage 39----------- 40 41Basic usage is in the form of 42 43- a `QLOG_EVENT_BEGIN` macro which takes a QLOG instance, category name and 44 event name. 45 46 This (category name, event name) tuple is known as the event type. 47 48- zero or more macros which log fields inside a qlog event. 49 50- a `QLOG_EVENT_END` macro. 51 52Usage is synchronised across threads on a per-event basis automatically. 53 54API Definition 55-------------- 56 57API details can be found in `internal/qlog.h`. 58 59Configuration 60------------- 61 62qlog must currently be enabled at build time using `enable-unstable-qlog`. If 63not enabled, `OPENSSL_NO_QLOG` is defined. 64 65When built with qlog support, qlog can be turned on using the recommended 66environment variable `QLOGDIR`. A filter can be defined using `OSSL_QFILTER`. When 67enabled, each connection causes a file `{ODCID}_{ROLE}.sqlog` to be created in 68the specified directory, where `{ODCID}` is the original initial DCID used for 69the connection and `{ROLE}` is `client` or `server`. 70 71Filters 72------- 73 74Each event type can be turned on and off individually. 75 76The filtering is configured using a string with the following syntax, expressed 77in ABNF: 78 79```abnf 80filter = *filter-term 81 82filter-term = add-sub-term 83 84add-sub-term = ["-" / "+"] specifier 85 86specifier = global-specifier / qualified-specifier 87 88global-specifier = wildcard 89 90qualified-specifier = component-specifier ":" component-specifier 91 92component-specifier = name / wildcard 93 94wildcard = "*" 95 96name = 1*(ALPHA / DIGIT / "_" / "-") 97``` 98 99Here is a (somewhat nonsensical) example filter: 100 101```text 102+* -quic:version_information -* quic:packet_sent 103``` 104 105The syntax works as follows: 106 107- A filter term is preceded by `-` (disable an event type) or `+` (enable an 108 event type). If this symbol is omitted, `+` is assumed. 109 110- `+*` (or `*`) enables all event types. 111 112- `-*` disables all event types. 113 114- `+quic:*` (or `quic:*`) enables all event types in the `quic` category. 115 116- `-quic:version_information` disables a specific event type. 117 118- Partial wildcard matches are not supported at this time. 119 120Each term is applied in sequence, therefore later items in the filter override 121earlier items. In the example above, for example, all event types are enabled, 122then the `quic:version_information` event is disabled, then all event types are 123disabled, then the `quic:packet_sent` event is re-enabled. 124 125Some examples of more normal filters include: 126 127- `*` (or `+*`): enable all event types 128 129- `quic:version_information quic:packet_sent`: enable some event types explicitly 130 131- `* -quic:version_information`: enable all event types except certain ones 132 133See also 134-------- 135 136See the manpage openssl-qlog(7) for additional usage guidance. 137
