Get started
You don’t need to know OpenTelemetry to use oxtel. Start with logs, and add the rest when you want it.
-
Logs. Add oxtel and
tracing, and calloxtel::init()first thing inmain. Keep what it returns for as long as the program runs.Cargo.toml [dependencies]oxtel = "0.3"tracing = "0.1"examples/logs.rs fn main() -> Result<(), oxtel::Error> {// Text on a terminal, JSON anywhere else. Keep the guard alive.let _logs = oxtel::init()?;// Fields are structured: in JSON, each is a key of its own.tracing::info!(user.id = 42, plan = "team", "signed in");// Lines inside a span carry its fields and its trace id, so every line// about one request can be found together.let request = tracing::info_span!("request", http.route = "/orders", order.id = 7);let _entered = request.enter();tracing::warn!(attempt = 2, "payment provider slow; retrying");Ok(())}On a terminal you get text, and anywhere else one JSON object per line. Wrap work in a span, as this does with the request, and every line inside it carries the span’s fields and a trace id.
RUST_LOGchooses how much is logged:infoby default. -
Requests. For a web service, add
oxtel-tower, and one line on an axum router gives every request a span, a log line and duration metrics:Cargo.toml [dependencies]oxtel = "0.3"oxtel-tower = { version = "0.3", features = ["axum"] }axum = "0.8"tokio = { version = "1", features = ["macros", "rt-multi-thread", "signal"] }tracing = "0.1"examples/web.rs let app = Router::new().route("/orders/{id}", get(order)).layer(oxtel_tower::HttpServerLayer::new());let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;tracing::info!("listening on http://127.0.0.1:3000");axum::serve(listener, app)// On Ctrl-C, finish the requests in flight and let main return, so// the guard is dropped and sends what's pending. Without this,// Ctrl-C ends the process at once and the last few seconds of// telemetry are lost..with_graceful_shutdown(async {let _ = tokio::signal::ctrl_c().await;}).await?;The graceful shutdown matters: when the program is stopped, it lets
mainreturn, so what’s still pending is sent. A web service has the whole program. -
Send it somewhere. Point oxtel at an OpenTelemetry Collector, or at any backend that accepts OTLP, and traces, metrics and logs go there. There’s nothing to change in your code:
Terminal window OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=shop cargo runTo see traces on your own machine, run Jaeger, then open http://localhost:16686:
Terminal window docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latestNothing is sent anywhere until you set an endpoint. When oxtel starts, it logs one line saying what it set up, and if sending fails, it says so and what to check. When something’s wrong goes through the usual causes.