9 releases
new 0.11.5 | Jan 12, 2025 |
---|---|
0.11.4 | Jan 10, 2025 |
0.11.0-alpha.21 | Oct 21, 2024 |
#433 in Debugging
605 downloads per month
3MB
7.5K
SLoC
emit_traceparent
Support trace propagation and sampling via W3C traceparents.
lib.rs
:
Distributed trace context for emit
.
This library implements the W3C trace context standard over emit
's tracing functionality. Trace context is propagated as a traceparent and tracestate in a simple text format. Here's an example of a traceparent:
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
It includes:
- A version:
00
. - A trace id:
4bf92f3577b34da6a3ce929d0e0e4736
. - A span id:
00f067aa0ba902b7
. - A set of trace flags:
01
(sampled).
Here's an example of tracestate:
vendorname1=opaqueValue1,vendorname2=opaqueValue2
It contains a collection of key-value pairs with vendor-specific information.
Getting started
Add emit
and emit_traceparent
to your Cargo.toml
:
[dependencies.emit]
version = "0.11.5"
[dependencies.emit_traceparent]
version = "0.11.5"
Initialize emit
using the setup
or setup_with_sampler
functions from this library:
fn main() {
let rt = emit_traceparent::setup()
.emit_to(emit_term::stdout())
.init();
// Your app code goes here
rt.blocking_flush(std::time::Duration::from_secs(30));
}
Incoming traceparent
When a request arrives, parse a Traceparent
from it and push it onto the current context. Handle the request in the returned emit::Frame
to make trace context correlate with the upstream service:
let traceparent = emit_traceparent::Traceparent::try_from_str("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
.unwrap_or_else(|_| emit_traceparent::Traceparent::current());
// 2. Push the traceparent onto the context and execute your handler within it
traceparent.push().call(handle_request);
#[emit::span("incoming request")]
fn handle_request() {
// Your code goes here
}
Outgoing traceparent
When making an outgoing request, get the current Traceparent
and format it into a header for the downstream service:
let mut headers = HashMap::<String, String>::new();
// 1. Get the current traceparent
let traceparent = emit_traceparent::Traceparent::current();
if traceparent.is_valid() {
// 2. Add the traceparent to the outgoing request
headers.insert("traceparent".into(), traceparent.to_string());
}
Traceparent
and SpanCtxt
emit
stores the active span context as an emit::SpanCtxt
in its emit::Ctxt
, which it generates in [macro@emit::span
] for you. SpanCtxt
doesn't have the concept of sampling, so if it exists then it's sampled.
When in use, the Traceparent
type defined by this library becomes the source of truth for the SpanCtxt
. If the current Traceparent
is not sampled, then no SpanCtxt
will be returned.
Only the span id on incoming SpanCtxt
s created by [macro@emit::span
] are respected. The current Traceparent
overrides any incoming trace ids or span parents.
Sampling
The setup_with_sampler
function lets you configure a sampling function that's run on the first span of each trace.
See the function docs for more details.