| 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(
qlog::VantagePoint {
name: Some("Example client".to_string()),
ty: qlog::VantagePointType::Client,
flow: None,
},
Some("Example qlog trace".to_string()),
Some("Example qlog trace description".to_string()),
Some(qlog::Configuration {
time_offset: Some(0.0),
original_uris: None,
}),
None,
);
```
### 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 (
# qlog::VantagePoint {
# name: Some("Example client".to_string()),
# ty: qlog::VantagePointType::Client,
# flow: None,
# },
# Some("Example qlog trace".to_string()),
# Some("Example qlog trace description".to_string()),
# Some(qlog::Configuration {
# time_offset: Some(0.0),
# original_uris: None,
# }),
# None
# );
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, // flags
None, // token
None, // length
Some(0x00000001), // version
Some(&scid),
Some(&dcid),
);
let frames = vec![qlog::events::quic::QuicFrame::Crypto {
offset: 0,
length: 0,
}];
let raw = qlog::events::RawInfo { |
27719 |
| reader.rs |
|
3722 |
| streamer.rs |
|
19731 |