diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-09-06 12:04:54 +0100 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2024-02-02 11:49:34 +0000 |
commit | 76989370bc3b48575c556ce37c3cb0381443ed6a (patch) | |
tree | a303bad8562f3860fad8b6a2af324bcbfd608c2e /doc/designs | |
parent | 1b39eab7aaa955c3a6cd24c864e714c32725861c (diff) |
QLOG: Frontend: Design
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22037)
Diffstat (limited to 'doc/designs')
-rw-r--r-- | doc/designs/quic-design/qlog.md | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/doc/designs/quic-design/qlog.md b/doc/designs/quic-design/qlog.md new file mode 100644 index 0000000000..b04d56f402 --- /dev/null +++ b/doc/designs/quic-design/qlog.md @@ -0,0 +1,120 @@ +QLOG Support +============ + +QLOG support is formed of two components: + +- A QLOG API and implementation. +- A JSON encoder API and implementation, which is used by the QLOG + implementation. + +The API for the JSON encoder is detailed in [a separate document](json-encoder.md). + +QLOG support will involve instrumenting various functions with QLOG logging +code. An example call site will look something like this: + +```c +{ + QLOG_EVENT_BEGIN(qlog_instance, quic, parameters_set) + QLOG_STR("owner", "local") + QLOG_BOOL("resumption_allowed", 1) + QLOG_STR("tls_cipher", "AES_128_GCM") + QLOG_BEGIN("subgroup") + QLOG_U64("u64_value", 123) + QLOG_BIN("binary_value", buf, buf_len) + QLOG_END() + QLOG_EVENT_END() +} +``` + +Output Format +------------- + +The output format will always be the JSON-SEQ QLOG variant. This has the +advantage that each event simply involves concatenating another record to an +output log file and does not require nesting of syntactic constructs between +events. + +Writing to files or to multi-file directories, or to arbitrary BIO sinks, will +be supported. + +Basic Usage +----------- + +Basic usage is in the form of + +- a `QLOG_EVENT_BEGIN` macro which takes a QLOG instance, category name and + event name. + + This (category name, event name) tuple is known as the event type. + +- zero or more macros which log fields inside a QLOG event. + +- a `QLOG_EVENT_END` macro. + +Usage is synchronised across threads on a per-event basis automatically. + +API Definition +-------------- + +API details can be found in `internal/qlog.h`. + +Configuration +------------- + +QLOG must currently be enabled at build time using `enable-unstable-qlog`. If +not enabled, `OPENSSL_NO_QLOG` is defined. + +When built with QLOG support, QLOG can be turned on using the recommended +environment variable `QLOGDIR`. A filter can be defined using `QLOGFILTER`. When +enabled, each connection causes a file `{ODCID}_{ROLE}.sqlog` to be created in +the specified directory, where `{ODCID}` is the original initial DCID used for +the connection and `{ROLE}` is `client` or `server`. + +Filters +------- + +Each event type can be turned on and off individually. + +The filtering is configured using a string with the following syntax, expressed +in ABNF: + +```abnf +filter = *filter-term + +filter-term = add-sub-term + +add-sub-term = ["-" / "+"] specifier + +specifier = global-specifier / qualified-specifier + +global-specifier = wildcard + +qualified-specifier = component-specifier ":" component-specifier + +component-specifier = name / wildcard + +wildcard = "*" + +name = 1*(ALPHA / DIGIT / "_" / "-") +``` + +Here is an example filter: + +```text +-quic:version_information quic:packet_sent -* +* +``` + +The syntax works as follows: + +- A filter term is preceded by `-` (disable an event type) or `+` (enable an + event type). If this symbol is omitted, `+` is assumed. + +- `+*` (or `*`) enables all event types. + +- `-*` disables all event types. + +- `+quic:*` (or `quic:*`) enables all event types in the `quic` category. + +- `-quic:version_information` disables a specific event type. + +- Partial wildcard matches are not supported at this time. |