eaze_tracing_honeycomb/
lib.rs

1#![deny(
2    warnings,
3    missing_debug_implementations,
4    missing_copy_implementations,
5    missing_docs
6)]
7
8//! This crate provides:
9//! - A tracing layer, `TelemetryLayer`, that can be used to publish trace data to honeycomb.io
10//! - Utilities for implementing distributed tracing against the honeycomb.io backend
11//!
12//! As a tracing layer, `TelemetryLayer` can be composed with other layers to provide stdout logging, filtering, etc.
13
14use eaze_tracing_distributed as tracing_distributed;
15
16mod honeycomb;
17mod span_id;
18mod trace_id;
19mod visitor;
20
21pub use honeycomb::HoneycombTelemetry;
22pub use span_id::SpanId;
23pub use trace_id::TraceId;
24#[doc(no_inline)]
25pub use tracing_distributed::{TelemetryLayer, TraceCtxError};
26pub use visitor::HoneycombVisitor;
27
28pub(crate) mod deterministic_sampler;
29
30/// Register the current span as the local root of a distributed trace.
31///
32/// Specialized to the honeycomb.io-specific SpanId and TraceId provided by this crate.
33pub fn register_dist_tracing_root(
34    trace_id: TraceId,
35    remote_parent_span: Option<SpanId>,
36) -> Result<(), TraceCtxError> {
37    tracing_distributed::register_dist_tracing_root(trace_id, remote_parent_span)
38}
39
40/// Retrieve the distributed trace context associated with the current span.
41///
42/// Returns the `TraceId`, if any, that the current span is associated with along with
43/// the `SpanId` belonging to the current span.
44///
45/// Specialized to the honeycomb.io-specific SpanId and TraceId provided by this crate.
46pub fn current_dist_trace_ctx() -> Result<(TraceId, SpanId), TraceCtxError> {
47    tracing_distributed::current_dist_trace_ctx()
48}
49
50/// Construct a TelemetryLayer that does not publish telemetry to any backend.
51///
52/// Specialized to the honeycomb.io-specific SpanId and TraceId provided by this crate.
53pub fn new_blackhole_telemetry_layer(
54) -> TelemetryLayer<tracing_distributed::BlackholeTelemetry<SpanId, TraceId>, SpanId, TraceId> {
55    TelemetryLayer::new(
56        "honeycomb_blackhole_tracing_layer",
57        tracing_distributed::BlackholeTelemetry::default(),
58        move |tracing_id| SpanId { tracing_id },
59    )
60}
61
62/// Construct a TelemetryLayer that publishes telemetry to honeycomb.io using the provided honeycomb config.
63///
64/// Specialized to the honeycomb.io-specific SpanId and TraceId provided by this crate.
65pub fn new_honeycomb_telemetry_layer(
66    service_name: &'static str,
67    honeycomb_config: libhoney::Config,
68) -> TelemetryLayer<HoneycombTelemetry, SpanId, TraceId> {
69    TelemetryLayer::new(
70        service_name,
71        HoneycombTelemetry::new(honeycomb_config, None),
72        move |tracing_id| SpanId { tracing_id },
73    )
74}
75
76/// Construct a TelemetryLayer that publishes telemetry to honeycomb.io using the
77/// provided honeycomb config, and sample rate. This function differs from
78/// `new_honeycomb_telemetry_layer` and the `sample_rate` on the
79/// `libhoney::Config` there in an important way. `libhoney` samples `Event`
80/// data, which is individual spans on each trace. This means that using the
81/// sampling logic in libhoney may result in missing event data or incomplete
82/// traces. Calling this function provides trace-level sampling, meaning sampling
83/// decisions are based on a modulo of the traceID, and events in a single trace
84/// will not be sampled differently. If the trace is sampled, then all spans
85/// under it will be sent to honeycomb. If a trace is not sampled, no spans or
86/// events under it will be sent. When using this trace-level sampling, the
87/// `sample_rate` parameter on the `libhoney::Config` should be set to 1, which
88/// is the default.
89///
90/// Specialized to the honeycomb.io-specific SpanId and TraceId provided by this crate.
91pub fn new_honeycomb_telemetry_layer_with_trace_sampling(
92    service_name: &'static str,
93    honeycomb_config: libhoney::Config,
94    sample_rate: u32,
95) -> TelemetryLayer<HoneycombTelemetry, SpanId, TraceId> {
96    TelemetryLayer::new(
97        service_name,
98        HoneycombTelemetry::new(honeycomb_config, Some(sample_rate)),
99        move |tracing_id| SpanId { tracing_id },
100    )
101}
eaze_tracing_honeycomb/lib.rs

eaze_tracing_honeycomb/
lib.rs
