krabka_telemetry/lib.rs
1//! Generic OTLP distributed-tracing pipeline for Krabka services.
2//!
3//! The consuming service always installs a structured-JSON `tracing_subscriber`
4//! `fmt` layer. That layer writes to stdout and uses the usual `RUST_LOG`
5//! `EnvFilter`. Container log collectors such as GKE / Cloud Logging and Loki
6//! thus ingest each line as fields, not as ANSI-coloured human text.
7//!
8//! The environment can also configure OTLP export. This crate then attaches a
9//! second `tracing-opentelemetry` layer, which converts `tracing` spans into
10//! OpenTelemetry spans. That layer batch-exports the spans over OTLP to a
11//! collector: gRPC `:4317` or HTTP/protobuf `:4318`.
12//!
13//! ## Enabling
14//!
15//! OTLP is **off by default**. A service with no OTLP environment keeps its
16//! behavior byte-for-byte. OTLP turns on when one of these variables sets an
17//! endpoint: `KRABKA_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, or
18//! `OTEL_EXPORTER_OTLP_ENDPOINT`. `KRABKA_OTLP_ENABLED=true` also turns OTLP
19//! on. `OTEL_SDK_DISABLED=true` turns OTLP off and overrides the other
20//! variables.
21//!
22//! ## WebAssembly
23//!
24//! On `wasm32-wasip1` the crate has no OTLP exporter and no profiling admin
25//! server, because both need a network client stack or a socket `bind`. There,
26//! [`init`] returns `TelemetryError::Unsupported` for an OTLP configuration
27//! and installs nothing, and [`profiling`] exports only its configuration
28//! types.
29//!
30//! ## Resolve OTLP settings without touching the environment
31//!
32//! ```rust
33//! use krabka_telemetry::{OtlpConfig, OtlpProtocol};
34//!
35//! let cfg = OtlpConfig::from_env(
36//! |key| (key == "KRABKA_OTLP_ENABLED").then(|| "true".to_string()),
37//! "broker-1",
38//! "0.1.0",
39//! "krabka-broker",
40//! )
41//! .expect("valid OTLP configuration")
42//! .expect("OTLP enabled");
43//!
44//! assert2::assert!((cfg.protocol) == (OtlpProtocol::Grpc));
45//! assert2::assert!((cfg.endpoint) == ("http://localhost:4317"));
46//! ```
47
48#![forbid(unsafe_code)]
49
50pub mod profiling;
51
52mod config;
53mod error;
54#[cfg(not(target_family = "wasm"))]
55mod exporter;
56#[cfg(not(target_family = "wasm"))]
57mod heartbeat;
58mod log_levels;
59mod subscriber;
60
61#[cfg(test)]
62mod test_support;
63
64pub use self::{
65 config::{OtlpConfig, OtlpProtocol},
66 error::TelemetryError,
67 log_levels::{LogLevel, LogLevelController, LogLevelFilter, ROOT_LOGGER, VALID_LOG_LEVELS},
68 subscriber::{TelemetryGuard, init},
69};
70/// W3C Trace Context propagation helpers.
71///
72/// These helpers live in the standalone, publishable `krabka-trace-context`
73/// crate. The wire-protocol crates can thus propagate a trace and do not link
74/// the OTLP exporter, the admin HTTP server, or the profiler that this crate
75/// depends on.
76pub use krabka_trace_context as propagation;