Home | History | Annotate | Line # | Download | only in quic-design 
      1 qlog Support
      2 ============
      3 
      4 qlog 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 
     10 The API for the JSON encoder is detailed in [a separate document](json-encoder.md).
     11 
     12 qlog support will involve instrumenting various functions with qlog logging
     13 code. 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 
     29 Output Format
     30 -------------
     31 
     32 The output format is always the JSON-SEQ qlog variant. This has the advantage
     33 that each event simply involves concatenating another record to an output log
     34 file and does not require nesting of syntactic constructs between events.
     35 
     36 Output is written to a directory containing multiple qlog files.
     37 
     38 Basic Usage
     39 -----------
     40 
     41 Basic 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 
     52 Usage is synchronised across threads on a per-event basis automatically.
     53 
     54 API Definition
     55 --------------
     56 
     57 API details can be found in `internal/qlog.h`.
     58 
     59 Configuration
     60 -------------
     61 
     62 qlog must currently be enabled at build time using `enable-unstable-qlog`. If
     63 not enabled, `OPENSSL_NO_QLOG` is defined.
     64 
     65 When built with qlog support, qlog can be turned on using the recommended
     66 environment variable `QLOGDIR`. A filter can be defined using `OSSL_QFILTER`. When
     67 enabled, each connection causes a file `{ODCID}_{ROLE}.sqlog` to be created in
     68 the specified directory, where `{ODCID}` is the original initial DCID used for
     69 the connection and `{ROLE}` is `client` or `server`.
     70 
     71 Filters
     72 -------
     73 
     74 Each event type can be turned on and off individually.
     75 
     76 The filtering is configured using a string with the following syntax, expressed
     77 in ABNF:
     78 
     79 ```abnf
     80 filter = *filter-term
     81 
     82 filter-term = add-sub-term
     83 
     84 add-sub-term = ["-" / "+"] specifier
     85 
     86 specifier           = global-specifier / qualified-specifier
     87 
     88 global-specifier    = wildcard
     89 
     90 qualified-specifier = component-specifier ":" component-specifier
     91 
     92 component-specifier = name / wildcard
     93 
     94 wildcard            = "*"
     95 
     96 name                = 1*(ALPHA / DIGIT / "_" / "-")
     97 ```
     98 
     99 Here is a (somewhat nonsensical) example filter:
    100 
    101 ```text
    102 +* -quic:version_information -* quic:packet_sent
    103 ```
    104 
    105 The 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 
    120 Each term is applied in sequence, therefore later items in the filter override
    121 earlier items. In the example above, for example, all event types are enabled,
    122 then the `quic:version_information` event is disabled, then all event types are
    123 disabled, then the `quic:packet_sent` event is re-enabled.
    124 
    125 Some 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 
    133 See also
    134 --------
    135 
    136 See the manpage openssl-qlog(7) for additional usage guidance.
    137