| <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="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."><title>qlog - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-b21aa549bf6d91ff.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="qlog" data-themes="" data-resource-suffix="" data-rustdoc-version="1.80.0-nightly (79734f1db 2024-05-02)" data-channel="nightly" data-search-js="search-bf21c90c8c1d92b1.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-e32f0c247825364d.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-20a3ad099b048cf2.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-09095024cf37855e.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../qlog/index.html">qlog</a><span class="version">0.13.0</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#constants">Constants</a></li><li><a href="#types">Type Aliases</a></li></ul></section></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../qlog/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Type ‘S’ or ‘/’ to search, ‘?’ for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings">Settings</a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Crate <a class="mod" href="#">qlog</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><a class="src" href="../src/qlog/lib.rs.html#27-987">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>−</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>The qlog crate is an implementation of the qlog <a href="https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-main-schema">main logging schema</a>, |
| <a href="https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-quic-events.html">QUIC event definitions</a>, and <a href="https://datatracker.ietf.org/doc/html/draft-ietf-quic-qlog-h3-events.html">HTTP/3 and QPACK event definitions</a>. |
| 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.</p> |
| <p>Serialization operates in either a <a href="#buffered-traces-with-standard-json">buffered mode</a> or a <a href="#streaming-traces-with-json-seq">streaming mode</a>.</p> |
| <p>The crate uses Serde for conversion between Rust and JSON.</p> |
| <h3 id="overview"><a class="doc-anchor" href="#overview">§</a>Overview</h3> |
| <p>qlog is a hierarchical logging format, with a rough structure of:</p> |
| <ul> |
| <li>Log |
| <ul> |
| <li>Trace(s) |
| <ul> |
| <li>Event(s)</li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <p>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.</p> |
| <h3 id="buffered-traces-with-standard-json"><a class="doc-anchor" href="#buffered-traces-with-standard-json">§</a>Buffered Traces with standard JSON</h3> |
| <p>A <a href="struct.Trace.html"><code>Trace</code></a> is a single JSON object. It contains metadata such as the |
| <a href="struct.VantagePoint.html"><code>VantagePoint</code></a> of capture and the <a href="struct.Configuration.html"><code>Configuration</code></a>, and protocol event |
| data in the <a href="events/struct.Event.html" title="struct qlog::events::Event"><code>Event</code></a> array.</p> |
| <p>JSON Traces allow applications to appends events to them before eventually |
| being serialized as a complete JSON object.</p> |
| <h4 id="creating-a-trace"><a class="doc-anchor" href="#creating-a-trace">§</a>Creating a Trace</h4> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span><span class="kw-2">mut </span>trace = qlog::Trace::new( |
| qlog::VantagePoint { |
| name: <span class="prelude-val">Some</span>(<span class="string">"Example client"</span>.to_string()), |
| ty: qlog::VantagePointType::Client, |
| flow: <span class="prelude-val">None</span>, |
| }, |
| <span class="prelude-val">Some</span>(<span class="string">"Example qlog trace"</span>.to_string()), |
| <span class="prelude-val">Some</span>(<span class="string">"Example qlog trace description"</span>.to_string()), |
| <span class="prelude-val">Some</span>(qlog::Configuration { |
| time_offset: <span class="prelude-val">Some</span>(<span class="number">0.0</span>), |
| original_uris: <span class="prelude-val">None</span>, |
| }), |
| <span class="prelude-val">None</span>, |
| );</code></pre></div> |
| <h4 id="adding-events-to-a-trace"><a class="doc-anchor" href="#adding-events-to-a-trace">§</a>Adding events to a Trace</h4> |
| <p>Qlog <a href="events/struct.Event.html" title="struct qlog::events::Event"><code>Event</code></a> objects are added to <a href="struct.Trace.html#structfield.events"><code>qlog::Trace.events</code></a>.</p> |
| <p>The following example demonstrates how to log a qlog QUIC <code>packet_sent</code> |
| event containing a single Crypto frame. It constructs the necessary elements |
| of the <a href="events/struct.Event.html" title="struct qlog::events::Event"><code>Event</code></a>, then appends it to the trace with <a href="struct.Trace.html#method.push_event"><code>push_event()</code></a>.</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code> |
| <span class="kw">let </span>scid = [<span class="number">0x7e</span>, <span class="number">0x37</span>, <span class="number">0xe4</span>, <span class="number">0xdc</span>, <span class="number">0xc6</span>, <span class="number">0x68</span>, <span class="number">0x2d</span>, <span class="number">0xa8</span>]; |
| <span class="kw">let </span>dcid = [<span class="number">0x36</span>, <span class="number">0xce</span>, <span class="number">0x10</span>, <span class="number">0x4e</span>, <span class="number">0xee</span>, <span class="number">0x50</span>, <span class="number">0x10</span>, <span class="number">0x1c</span>]; |
| |
| <span class="kw">let </span>pkt_hdr = qlog::events::quic::PacketHeader::new( |
| qlog::events::quic::PacketType::Initial, |
| <span class="prelude-val">Some</span>(<span class="number">0</span>), <span class="comment">// packet_number |
| </span><span class="prelude-val">None</span>, <span class="comment">// flags |
| </span><span class="prelude-val">None</span>, <span class="comment">// token |
| </span><span class="prelude-val">None</span>, <span class="comment">// length |
| </span><span class="prelude-val">Some</span>(<span class="number">0x00000001</span>), <span class="comment">// version |
| </span><span class="prelude-val">Some</span>(<span class="kw-2">&</span>scid), |
| <span class="prelude-val">Some</span>(<span class="kw-2">&</span>dcid), |
| ); |
| |
| <span class="kw">let </span>frames = <span class="macro">vec!</span>[qlog::events::quic::QuicFrame::Crypto { |
| offset: <span class="number">0</span>, |
| length: <span class="number">0</span>, |
| }]; |
| |
| <span class="kw">let </span>raw = qlog::events::RawInfo { |
| length: <span class="prelude-val">Some</span>(<span class="number">1251</span>), |
| payload_length: <span class="prelude-val">Some</span>(<span class="number">1224</span>), |
| data: <span class="prelude-val">None</span>, |
| }; |
| |
| <span class="kw">let </span>event_data = |
| qlog::events::EventData::PacketSent(qlog::events::quic::PacketSent { |
| header: pkt_hdr, |
| frames: <span class="prelude-val">Some</span>(frames.into()), |
| is_coalesced: <span class="prelude-val">None</span>, |
| retry_token: <span class="prelude-val">None</span>, |
| stateless_reset_token: <span class="prelude-val">None</span>, |
| supported_versions: <span class="prelude-val">None</span>, |
| raw: <span class="prelude-val">Some</span>(raw), |
| datagram_id: <span class="prelude-val">None</span>, |
| send_at_time: <span class="prelude-val">None</span>, |
| trigger: <span class="prelude-val">None</span>, |
| }); |
| |
| trace.push_event(qlog::events::Event::with_time(<span class="number">0.0</span>, event_data));</code></pre></div> |
| <h4 id="serializing"><a class="doc-anchor" href="#serializing">§</a>Serializing</h4> |
| <p>The qlog crate has only been tested with <code>serde_json</code>, however |
| other serializer targets might work.</p> |
| <p>For example, serializing the trace created above:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>serde_json::to_string_pretty(<span class="kw-2">&</span>trace).unwrap();</code></pre></div> |
| <p>which would generate the following:</p> |
| |
| <div class="example-wrap ignore"><a href="#" class="tooltip" title="This example is not tested">ⓘ</a><pre class="rust rust-example-rendered"><code>{ |
| <span class="string">"vantage_point"</span>: { |
| <span class="string">"name"</span>: <span class="string">"Example client"</span>, |
| <span class="string">"type"</span>: <span class="string">"client" |
| </span>}, |
| <span class="string">"title"</span>: <span class="string">"Example qlog trace"</span>, |
| <span class="string">"description"</span>: <span class="string">"Example qlog trace description"</span>, |
| <span class="string">"configuration"</span>: { |
| <span class="string">"time_offset"</span>: <span class="number">0.0 |
| </span>}, |
| <span class="string">"events"</span>: [ |
| { |
| <span class="string">"time"</span>: <span class="number">0.0</span>, |
| <span class="string">"name"</span>: <span class="string">"transport:packet_sent"</span>, |
| <span class="string">"data"</span>: { |
| <span class="string">"header"</span>: { |
| <span class="string">"packet_type"</span>: <span class="string">"initial"</span>, |
| <span class="string">"packet_number"</span>: <span class="number">0</span>, |
| <span class="string">"version"</span>: <span class="string">"1"</span>, |
| <span class="string">"scil"</span>: <span class="number">8</span>, |
| <span class="string">"dcil"</span>: <span class="number">8</span>, |
| <span class="string">"scid"</span>: <span class="string">"7e37e4dcc6682da8"</span>, |
| <span class="string">"dcid"</span>: <span class="string">"36ce104eee50101c" |
| </span>}, |
| <span class="string">"raw"</span>: { |
| <span class="string">"length"</span>: <span class="number">1251</span>, |
| <span class="string">"payload_length"</span>: <span class="number">1224 |
| </span>}, |
| <span class="string">"frames"</span>: [ |
| { |
| <span class="string">"frame_type"</span>: <span class="string">"crypto"</span>, |
| <span class="string">"offset"</span>: <span class="number">0</span>, |
| <span class="string">"length"</span>: <span class="number">0 |
| </span>} |
| ] |
| } |
| } |
| ] |
| }</code></pre></div> |
| <h3 id="streaming-traces-with-json-seq"><a class="doc-anchor" href="#streaming-traces-with-json-seq">§</a>Streaming Traces with JSON-SEQ</h3> |
| <p>To help support streaming serialization of qlogs, |
| draft-ietf-quic-qlog-main-schema-01 introduced support for RFC 7464 JSON |
| Text Sequences (JSON-SEQ). The qlog crate supports this format and provides |
| utilities that aid streaming.</p> |
| <p>A <a href="struct.TraceSeq.html"><code>TraceSeq</code></a> contains metadata such as the <a href="struct.VantagePoint.html"><code>VantagePoint</code></a> of capture and |
| the <a href="struct.Configuration.html"><code>Configuration</code></a>. However, protocol event data is handled as separate |
| lines containing a record separator character, a serialized <a href="events/struct.Event.html" title="struct qlog::events::Event"><code>Event</code></a>, and a |
| newline.</p> |
| <h4 id="creating-a-traceseq"><a class="doc-anchor" href="#creating-a-traceseq">§</a>Creating a TraceSeq</h4> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span><span class="kw-2">mut </span>trace = qlog::TraceSeq::new( |
| qlog::VantagePoint { |
| name: <span class="prelude-val">Some</span>(<span class="string">"Example client"</span>.to_string()), |
| ty: qlog::VantagePointType::Client, |
| flow: <span class="prelude-val">None</span>, |
| }, |
| <span class="prelude-val">Some</span>(<span class="string">"Example qlog trace"</span>.to_string()), |
| <span class="prelude-val">Some</span>(<span class="string">"Example qlog trace description"</span>.to_string()), |
| <span class="prelude-val">Some</span>(qlog::Configuration { |
| time_offset: <span class="prelude-val">Some</span>(<span class="number">0.0</span>), |
| original_uris: <span class="prelude-val">None</span>, |
| }), |
| <span class="prelude-val">None</span>, |
| );</code></pre></div> |
| <p>Create an object with the <a href="https://doc.rust-lang.org/std/io/trait.Write.html"><code>Write</code></a> trait:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span><span class="kw-2">mut </span>file = std::fs::File::create(<span class="string">"foo.sqlog"</span>).unwrap();</code></pre></div> |
| <p>Create a <a href="struct.QlogStreamer.html"><code>QlogStreamer</code></a> and start serialization to foo.sqlog |
| using <a href="streamer/struct.QlogStreamer.html#method.start_log"><code>start_log()</code></a>:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span><span class="kw-2">mut </span>streamer = qlog::streamer::QlogStreamer::new( |
| qlog::QLOG_VERSION.to_string(), |
| <span class="prelude-val">Some</span>(<span class="string">"Example qlog"</span>.to_string()), |
| <span class="prelude-val">Some</span>(<span class="string">"Example qlog description"</span>.to_string()), |
| <span class="prelude-val">None</span>, |
| std::time::Instant::now(), |
| trace, |
| qlog::events::EventImportance::Base, |
| Box::new(file), |
| ); |
| |
| streamer.start_log().ok();</code></pre></div> |
| <h4 id="adding-events"><a class="doc-anchor" href="#adding-events">§</a>Adding events</h4> |
| <p>Once logging has started you can stream events. Events |
| are written in one step using one of <a href="streamer/struct.QlogStreamer.html#method.add_event"><code>add_event()</code></a>, |
| <a href="streamer/struct.QlogStreamer.html#method.add_event_with_instant"><code>add_event_with_instant()</code></a>, <a href="streamer/struct.QlogStreamer.html#method.add_event_now"><code>add_event_now()</code></a>, |
| <a href="streamer/struct.QlogStreamer.html#method.add_event_data_with_instant"><code>add_event_data_with_instant()</code></a>, or <a href="streamer/struct.QlogStreamer.html#method.add_event_data_now"><code>add_event_data_now()</code></a> :</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code> |
| <span class="kw">let </span>scid = [<span class="number">0x7e</span>, <span class="number">0x37</span>, <span class="number">0xe4</span>, <span class="number">0xdc</span>, <span class="number">0xc6</span>, <span class="number">0x68</span>, <span class="number">0x2d</span>, <span class="number">0xa8</span>]; |
| <span class="kw">let </span>dcid = [<span class="number">0x36</span>, <span class="number">0xce</span>, <span class="number">0x10</span>, <span class="number">0x4e</span>, <span class="number">0xee</span>, <span class="number">0x50</span>, <span class="number">0x10</span>, <span class="number">0x1c</span>]; |
| |
| <span class="kw">let </span>pkt_hdr = qlog::events::quic::PacketHeader::with_type( |
| qlog::events::quic::PacketType::OneRtt, |
| <span class="prelude-val">Some</span>(<span class="number">0</span>), |
| <span class="prelude-val">Some</span>(<span class="number">0x00000001</span>), |
| <span class="prelude-val">Some</span>(<span class="kw-2">&</span>scid), |
| <span class="prelude-val">Some</span>(<span class="kw-2">&</span>dcid), |
| ); |
| |
| <span class="kw">let </span>ping = qlog::events::quic::QuicFrame::Ping { |
| length: <span class="prelude-val">None</span>, |
| payload_length: <span class="prelude-val">None</span>, |
| }; |
| <span class="kw">let </span>padding = qlog::events::quic::QuicFrame::Padding { |
| length: <span class="prelude-val">None</span>, |
| payload_length: <span class="number">1234</span>, |
| }; |
| |
| <span class="kw">let </span>event_data = |
| qlog::events::EventData::PacketSent(qlog::events::quic::PacketSent { |
| header: pkt_hdr, |
| frames: <span class="prelude-val">Some</span>(<span class="macro">vec!</span>[ping, padding].into()), |
| is_coalesced: <span class="prelude-val">None</span>, |
| retry_token: <span class="prelude-val">None</span>, |
| stateless_reset_token: <span class="prelude-val">None</span>, |
| supported_versions: <span class="prelude-val">None</span>, |
| raw: <span class="prelude-val">None</span>, |
| datagram_id: <span class="prelude-val">None</span>, |
| send_at_time: <span class="prelude-val">None</span>, |
| trigger: <span class="prelude-val">None</span>, |
| }); |
| |
| <span class="kw">let </span>event = qlog::events::Event::with_time(<span class="number">0.0</span>, event_data); |
| |
| streamer.add_event(event).ok();</code></pre></div> |
| <p>Once all events have been written, the log |
| can be finalized with <a href="streamer/struct.QlogStreamer.html#method.finish_log"><code>finish_log()</code></a>:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code>streamer.finish_log().ok();</code></pre></div> |
| <h4 id="serializing-1"><a class="doc-anchor" href="#serializing-1">§</a>Serializing</h4> |
| <p>Serialization to JSON occurs as methods on the <a href="struct.QlogStreamer.html"><code>QlogStreamer</code></a> |
| are called. No additional steps are required.</p> |
| </div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="events/index.html" title="mod qlog::events">events</a></div></li><li><div class="item-name"><a class="mod" href="reader/index.html" title="mod qlog::reader">reader</a></div></li><li><div class="item-name"><a class="mod" href="streamer/index.html" title="mod qlog::streamer">streamer</a></div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.CommonFields.html" title="struct qlog::CommonFields">CommonFields</a></div></li><li><div class="item-name"><a class="struct" href="struct.Configuration.html" title="struct qlog::Configuration">Configuration</a></div></li><li><div class="item-name"><a class="struct" href="struct.HexSlice.html" title="struct qlog::HexSlice">HexSlice</a></div></li><li><div class="item-name"><a class="struct" href="struct.Qlog.html" title="struct qlog::Qlog">Qlog</a></div></li><li><div class="item-name"><a class="struct" href="struct.QlogSeq.html" title="struct qlog::QlogSeq">QlogSeq</a></div></li><li><div class="item-name"><a class="struct" href="struct.Token.html" title="struct qlog::Token">Token</a></div></li><li><div class="item-name"><a class="struct" href="struct.Trace.html" title="struct qlog::Trace">Trace</a></div></li><li><div class="item-name"><a class="struct" href="struct.TraceSeq.html" title="struct qlog::TraceSeq">TraceSeq</a></div></li><li><div class="item-name"><a class="struct" href="struct.VantagePoint.html" title="struct qlog::VantagePoint">VantagePoint</a></div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.Error.html" title="enum qlog::Error">Error</a></div><div class="desc docblock-short">A quiche qlog error.</div></li><li><div class="item-name"><a class="enum" href="enum.ImportanceLogLevel.html" title="enum qlog::ImportanceLogLevel">ImportanceLogLevel</a></div></li><li><div class="item-name"><a class="enum" href="enum.TokenType.html" title="enum qlog::TokenType">TokenType</a></div></li><li><div class="item-name"><a class="enum" href="enum.VantagePointType.html" title="enum qlog::VantagePointType">VantagePointType</a></div></li></ul><h2 id="constants" class="section-header">Constants<a href="#constants" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="constant" href="constant.QLOG_VERSION.html" title="constant qlog::QLOG_VERSION">QLOG_VERSION</a></div></li></ul><h2 id="types" class="section-header">Type Aliases<a href="#types" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="type" href="type.Bytes.html" title="type qlog::Bytes">Bytes</a></div></li><li><div class="item-name"><a class="type" href="type.Result.html" title="type qlog::Result">Result</a></div><div class="desc docblock-short">A specialized <a href="https://doc.rust-lang.org/std/result/enum.Result.html"><code>Result</code></a> type for quiche qlog operations.</div></li><li><div class="item-name"><a class="type" href="type.StatelessResetToken.html" title="type qlog::StatelessResetToken">StatelessResetToken</a></div></li></ul></section></div></main></body></html> |
