| events |
|
|
- |
| lib.rs |
The qlog crate is an implementation of the qlog [main logging schema],
[QUIC event definitions], and [HTTP/3 and QPACK event definitions].
The crate provides a qlog data model that can be used for traces with
events. It supports serialization and deserialization but defers logging IO
choices to applications.
Serialization operates in either a [buffered mode] or a [streaming mode].
The crate uses Serde for conversion between Rust and JSON.
[main logging schema]: https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-main-schema
[QUIC event definitions]:
https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-quic-events.html
[HTTP/3 and QPACK event definitions]:
https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-h3-events.html
[buffered mode]: #buffered-traces-with-standard-json
[streaming mode]: #streaming-traces-with-json-seq
Overview
---------------
qlog is a hierarchical logging format, with a rough structure of:
* Log
* Trace(s)
* Event(s)
In practice, a single QUIC connection maps to a single Trace file with one
or more Events. Applications can decide whether to combine Traces from
different connections into the same Log.
## Buffered Traces with standard JSON
A [`Trace`] is a single JSON object. It contains metadata such as the
[`VantagePoint`] of capture and the [`Configuration`], and protocol event
data in the [`Event`] array.
JSON Traces allow applications to appends events to them before eventually
being serialized as a complete JSON object.
### Creating a Trace
```
let mut trace = qlog::Trace::new(
# Some("Example qlog trace".to_string()),
# Some("Example qlog trace description".to_string()),
# None,
# Some(qlog::VantagePoint {
# name: Some("Example client".to_string()),
# ty: qlog::VantagePointType::Client,
# flow: None,
# }),
# vec![qlog::events::QUIC_URI.to_string(), qlog::events::HTTP3_URI.to_string()],
# );
```
### Adding events to a Trace
Qlog [`Event`] objects are added to [`qlog::Trace.events`].
The following example demonstrates how to log a qlog QUIC `packet_sent`
event containing a single Crypto frame. It constructs the necessary elements
of the [`Event`], then appends it to the trace with [`push_event()`].
```
# let mut trace = qlog::Trace::new(
# Some("Example qlog trace".to_string()),
# Some("Example qlog trace description".to_string()),
# None,
# Some(qlog::VantagePoint {
# name: Some("Example client".to_string()),
# ty: qlog::VantagePointType::Client,
# flow: None,
# }),
# vec![qlog::events::QUIC_URI.to_string(), qlog::events::HTTP3_URI.to_string()],
# );
let scid = [0x7e, 0x37, 0xe4, 0xdc, 0xc6, 0x68, 0x2d, 0xa8];
let dcid = [0x36, 0xce, 0x10, 0x4e, 0xee, 0x50, 0x10, 0x1c];
let pkt_hdr = qlog::events::quic::PacketHeader::new(
qlog::events::quic::PacketType::Initial,
Some(0), // packet_number
None, // token
None, // length
Some(0x00000001), // version
Some(&scid),
Some(&dcid),
);
let frames = vec![qlog::events::quic::QuicFrame::Crypto {
offset: 0,
raw: None,
}];
let raw = qlog::events::RawInfo {
length: Some(1251),
payload_length: Some(1224),
data: None, |
22406 |
- |
| reader.rs |
|
7443 |
- |
| streamer.rs |
|
25134 |
- |
| testing |
|
|
- |
| writer.rs |
QLOG file writer plumbing -- compression-aware companion to
[`crate::reader`].
This module owns the writer-side surface for emitting JSON-SEQ
qlog streams, optionally wrapped in a streaming compressor. It is
a deliberate exception to the qlog crate's otherwise pure-data
posture: the writer helpers, the compression enum, and the
filename / extension conventions live here so any consumer
(tokio-quiche, [`crate::reader::QlogSeqReader::with_file`],
external tooling) shares a single canonical writer story.
Compression is opt-in via Cargo features:
* `gzip` pulls in [`flate2`].
* `zstd` pulls in the [`zstd`] crate (C dependency via `zstd-sys`).
The [`QlogCompression`] enum's `Gzip` and `Zstd` variants are
compile-time gated on their respective features, so a build that
disables one of them cannot construct the unsupported variant.
Bytes flow `producer -> [compressor] -> W` where `W` is any
`Write + Send + Sync + 'static`. No buffering is added here: both
`flate2` and `zstd` emit output in large chunks (DEFLATE blocks /
zstd frames), so an extra `BufWriter` is redundant; callers are
free to add one if they need to. |
8875 |
- |