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)

diff --git a/doc/designs/quic-design/qlog.md b/doc/designs/quic-design/qlog.md
new file mode 100644 (file)
index 0000000..b04d56f
--- /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.