Module qlog 

Available on crate features quic and std only.

Typed QUIC diagnostics with optional async recording.

Configure QlogConfig with a writer, call QlogConfig::start inside a Tokio runtime, and attach the recorder through TransportConfig::with_qlog_recorder. Output uses qlog JSON text sequences; EncodedWriter supports custom encoders. For direct observation, attach a QlogSink: events borrow connection data and callbacks must finish promptly.

Use QlogConfig::with_executor for graceful draining and flushing, or await QlogRecorder::shutdown explicitly. Dropping handles does not wait for output. Recording failures go to the configured QlogConfig::with_error_sink; explicit completion checks are optional. Keep the runtime alive until recording finishes.

HistoryConfig retains a bounded recent window for QlogRecorder::dump_recent. ConnectionQlogControl provides per-connection toggles and triggers. Disabled observations are not retained; enabling later produces a partial trace.

Format and tooling

The built-in encoder targets main schema draft 14 and QUIC events draft 13, using RFC 7464 JSON text sequences (application/qlog+json-seq) and event schema urn:ietf:params:qlog:events:quic-13. event::EventView lists the implemented event subset; HTTP/3 events are not included. The linked specifications are fixed published revisions; neither the drafts nor their CDDL schemas are vendored.

Some tools still expect older qlog formats, such as draft-02 / qlog 0.3, and may not accept this output. Compatibility depends on both the file schema and event definitions; changing the header alone does not convert a trace. Rama does not emit a legacy compatibility format.

Modules

event

QUIC qlog observations shared by inline sinks and owned recording adapters.

Structs

ConnectionQlogControl

Recording controls obtained from crate::Connection::qlog_control. Clones share this connection’s gate and retain its sink, never the QUIC connection. Implements Rama’s extension trait for propagation through request context.

EncodedWriter

Combine an asynchronous writer with a streaming encoder. The writer is used directly; supply an AsyncWrite buffer when small writes are costly. Finishing writes encoder trailers, flushes, then shuts down the writer, even on errors. Cancellation while the encoder writes trailers cannot be retried; drop the output. Cancellation during writer flush or shutdown resumes that phase. Successful finishes are idempotent.

Filtered

A sink that delivers only matching observations and propagates selection generations. Construct with QlogSink::filtered or QlogSink::filtered_by.

HistoryConfig

A rolling history shared by all connections on this recorder. Age is measured from admission using a monotonic clock; original event timestamps are preserved. Queue wait counts toward the window. Node storage and retained field capacities fit max_bytes (allocator bookkeeping excluded). No events are written until explicitly dumped.

JsonSeqEncoder

Direct async qlog JSON text-sequence output without whole-event byte buffers. Cancellation or an I/O error may leave a partial record; do not retry it on the same stream. At most eight consecutive Interrupted writes are retried before returning an error retaining the original source. Writers must report backpressure with Pending and arrange a wakeup; WouldBlock is an error.

QlogConfig

Configure a worker and destination. The default has no destination and records nothing. Built-in output uses qlog main draft 14 / QUIC events draft 13 JSON text sequences. See qlog for specification links and reader compatibility. Supply an output for custom storage, or an EncodedWriter for a custom serializer.

QlogEventView

A typed observation whose variable-length fields may borrow from the connection.

QlogRecorder

A cloneable handle to one worker. Clones share the destination and recording gate. Keep a handle to await completion; dropping it never waits for output.

QueueLimits

Admission limits for owned events, including the event currently being processed. Byte accounting covers event storage and owned field capacities, not allocator overhead.

RecorderStats

Cumulative admission counters and current retained storage. Counters are observational; concurrent updates can occur between reading individual fields.

TraceInfo

Metadata shared by the events in a recorder’s output.

Enums

RecorderState

Lifecycle of the output worker, independent of whether event admission is enabled.

Traits

QlogEncoder

Streaming asynchronous serialization of borrowed events to caller-provided output. Encoders can suspend at I/O backpressure without blocking an executor thread.

QlogFilter

A cheap borrowed-event selection rule. Stateful filters advance generation whenever selection changes, so the connection can provide a fresh recovery snapshot.

QlogOutput

Asynchronous storage, invoked by the recording task after event admission. Methods may wait for I/O. Synchronous computation and destruction must finish promptly. An error ends the recorder; partially written records are never retried automatically. One task owns the output exclusively; Send permits executor migration. Implementations remain concrete inside the task, without boxing a future per event.

QlogSink

Borrowed observations delivered synchronously inside the QUIC state machine.

Type Aliases

QlogEvent

An event that owns all variable-length data and can cross a worker boundary.