Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Observability

Every request that reaches the server produces one wide event. Under into_axum a path that the description does not declare gets one only through the fallback in Adapters. The event holds these fields:

  • the operation and route
  • the status and duration
  • the body sizes
  • the security schemes and scopes
  • the failure kind if there is one

Layers add fields with req.event().set(key, value). Handlers add fields with ctx.event.set(key, value). A key is an EventKey. Declare it as a const such as const TENANT: EventKey = EventKey::new("tenant"). Then a key that has the name of a built-in field fails to compile.

Send the event anywhere with on_event:

/// The wide event of each request as one JSON line to wherever your logs go. Here it is a list that a test reads.
fn logged(lines: Arc<Mutex<Vec<String>>>) -> api::Client<impl api::Transport> {
    let service = api::Server::new(Catalog::default())
        .on_event(move |event: &api::RequestEvent| {
            if let Ok(mut lines) = lines.lock() {
                lines.push(event.to_json());
            }
        })
        .into_service();
    api::Client::new(service).with_api_key("secret")
}

Tracing

With the tracing adapter each request runs in a span that wraps your layers and handler. The span follows the HTTP server conventions of OpenTelemetry (otel.name, http.route and http.response.status_code). The default on_event logs the wide event inside the span as one structured line. Export the spans with tracing-opentelemetry.

Trace context

The tracing-opentelemetry adapter adds W3C Trace Context. The span of a request then continues the trace that its traceparent header names. The requests of the client carry the traceparent and tracestate of the current span. A request that already has a traceparent keeps it. Spans join only once a tracing-opentelemetry layer exports them:

/// Spans exported through OpenTelemetry. The span of a request continues the trace that its `traceparent` names. The
/// requests of the client carry the ones of the current span.
fn exported() -> impl tracing::Subscriber {
    use opentelemetry::trace::TracerProvider as _;
    use tracing_subscriber::layer::SubscriberExt as _;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder().build();
    tracing_subscriber::registry().with(tracing_opentelemetry::layer().with_tracer(provider.tracer("shop")))
}

The runtime is built against opentelemetry 0.33 and tracing-opentelemetry 0.34. Depend on the same versions. A span from another version holds no context that the runtime can read.