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