Skip to content

Get started

You don’t need to know OpenTelemetry to use oxtel. Start with logs, and add the rest when you want it.

  1. Logs. Add oxtel and tracing, and call oxtel::init() first thing in main. 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_LOG chooses how much is logged: info by default.

  2. 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 main return, so what’s still pending is sent. A web service has the whole program.

  3. 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 run

    To 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:latest

    Nothing 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.