Expand description
OpenTelemetry-compatible telemetry for Rust, native to tracing and
metrics: structured logs with one line of setup, and traces, metrics
and logs sent to a collector when you want them, with no code changes.
fn main() -> Result<(), oxtel::Error> {
// Keep the guard alive for as long as the program runs.
let _telemetry = oxtel::init()?;
// Instrument as usual: events and spans with `tracing`, metrics
// with `metrics`.
tracing::info!(user.id = 42, "signed in");
let span = tracing::info_span!("request", order.id = 7);
let _entered = span.enter();
tracing::warn!(attempt = 2, "payment provider slow; retrying");
metrics::counter!("orders.placed").increment(1);
Ok(())
}With nothing configured, that writes log lines to standard error, as
text on a terminal and one JSON object per line anywhere else, and sends
nothing anywhere. Set OTEL_EXPORTER_OTLP_ENDPOINT (for example
http://localhost:4318) and traces, metrics and logs go there over OTLP.
On startup, oxtel logs one line saying what it set up. The
guide covers the rest in
plain words.
What gets set up:
| Signal | From | To (OTEL_*_EXPORTER) |
|---|---|---|
| Traces | tracing spans | otlp, console, none |
| Logs | tracing events, and log records with the log feature | otlp, console, none |
| Metrics | the metrics facade | otlp, prometheus, console, none |
- Nothing is exported until it’s configured. Setting
OTEL_EXPORTER_OTLP_ENDPOINT, or a signal’s own endpoint, makesotlpthe default for those signals. The specification’s default isotlptolocalhost:4318even then; namingotlpstill gets that. OTEL_CONFIG_FILE, with theconfigfeature (on by default), names a declarative configuration file to build everything from instead: seeoxtel_config.OTEL_SDK_DISABLED=trueturns all of it off. Local logs and layers added withBuilder::with_layerstill run.- The resource comes from
OTEL_SERVICE_NAMEandOTEL_RESOURCE_ATTRIBUTES, the sampler fromOTEL_TRACES_SAMPLER, OTLP’s endpoint and headers fromOTEL_EXPORTER_OTLP_*, the Prometheus endpoint fromOTEL_EXPORTER_PROMETHEUS_HOSTand_PORT, and batching and limits from their standard variables. - Spans and log records follow
RUST_LOG-style directives,infoby default; seeBuilder::with_traces_filter. - With a log pipeline, events become log records carrying their span’s ids. Without one, they become span events instead.
- Events are also written locally, to standard error: readable text
when that’s a terminal, flat JSON with OpenTelemetry field names
otherwise, for log shippers.
OXTEL_LOG_FORMAT(auto,text,json,ecsornone) andOXTEL_LOG_OUTPUT(stderrorstdout) change that; so doBuilder::with_local_logsand its neighbours. - Libraries that already log what they do get spans and metrics under
the conventions’ names from it, with the
mappingsfeature (on by default): a database span for each of sqlx’s queries, for one. Seemappingsfor what they can and can’t record;OXTEL_MAPPINGS=noneleaves them out. - Settings oxtel can’t honour, such as
OTEL_TRACES_EXPORTER=zipkin, are logged as warnings with the targetoxtel, rather than failing.
Builder adds to this: resource attributes, filters, your own layers,
and hooks into each pipeline for extra exporters and processors.
Re-exports§
pub use oxtel_otlp as otlp;pub use oxtel_prometheus as prometheus;pub use oxtel_sdk as sdk;
Modules§
- mappings
- Spans and metrics, under the semantic conventions’ names, from what
libraries already report through
tracing, with no code change.oxtel::initinstalls these;Builder::without_mappingsorOXTEL_MAPPINGS=noneleaves them out. - propagation
- Carrying trace context across process boundaries, as
OTEL_PROPAGATORSconfigures: W3C Trace Context unless it’s left out.
Structs§
- Builder
- Configures oxtel. Start with
oxtel::builder. - Guard
- Keeps oxtel’s pipelines running. Dropping it, or calling
shutdown, exports what’s pending and stops them. - KeyValue
- A key and its value.
- Resource
- Attributes that describe the entity producing telemetry.
- Telemetry
- Pipelines built but not yet installed. See
Builder::build.
Enums§
- Error
- Why oxtel couldn’t be set up.
- Exporter
- An exporter the environment can choose for a signal.
- LogOutput
- Where local log lines go.
- Value
- An attribute value: OpenTelemetry’s
AnyValue.