Send traces from Rust tracing to Axiom
This page explains how to send spans generated by the tokio-rs/tracing library to Axiom with the tracing-axiom layer.
Use the tracing-axiom crate to send spans generated by the tokio-rs/tracing library to Axiom. tracing-axiom provides a tracing-subscriber layer that exports your spans to Axiom over the OpenTelemetry protocol (OTLP). You combine it with any other layers your app already uses.
To send events from Rust without the tracing library, use the Axiom Rust SDK. For more information, see Send data from Rust app to Axiom.
Prerequisites
- Create an Axiom account.
- Create a dataset in Axiom where you send your data.
- Create an API token in Axiom with permissions to ingest data to the dataset you have created.
- Use the Tokio runtime in your app.
tracing-axiomexports spans in the background on a Tokio runtime, so create the layer inside an async context such as#[tokio::main].
Install crate
Add the following to your Cargo.toml:
The opentelemetry dependency is needed to flush spans when your app exits. Use the same opentelemetry version as tracing-axiom. Version 0.7 of tracing-axiom depends on opentelemetry 0.22. If your app depends on a different opentelemetry version, the shutdown call in the examples below doesn’t reach the tracer provider that tracing-axiom installs, and the last batch of spans is lost.
Configure environment
tracing-axiom reads its configuration from the following environment variables:
AXIOM_URL is the base URL of the endpoint. tracing-axiom appends the /v1/traces path. If you don’t set AXIOM_URL, tracing-axiom sends traces to https://api.axiom.co. Recommended: Set AXIOM_URL to the edge deployment where your dataset lives.
The following edge domains are available:
| Edge deployment | Base domain for ingest and query |
|---|---|
US East 1 (AWS) | us-east-1.aws.edge.axiom.co |
EU Central 1 (AWS) | eu-central-1.aws.edge.axiom.co |
Send traces
Create the layer with tracing_axiom::default, add it to a tracing-subscriber registry, and instrument your functions:
The argument of tracing_axiom::default is the service name. Axiom stores it in the service.name resource attribute of every span. Each function annotated with #[tracing::instrument] becomes a span, and the function arguments become span attributes. Events such as tracing::info! inside a span are recorded as span events.
tracing-axiom batches spans and sends them in the background. Call opentelemetry::global::shutdown_tracer_provider before your app exits to send the remaining spans.
Configure layer in code
To set the configuration in code instead of environment variables, use tracing_axiom::builder:
tracing_axiom::builder ignores the environment. To read the environment first and override individual values in code, use tracing_axiom::builder_with_env. Values that you set in code take precedence over environment variables.
The builder provides the following methods:
| Method | Description |
|---|---|
with_token | Axiom API token. Overrides AXIOM_TOKEN. |
with_dataset | Name of the dataset where you send traces. Overrides AXIOM_DATASET. |
with_url | Base URL of the endpoint. Overrides AXIOM_URL. |
with_service_name | Value of the service.name resource attribute. |
with_tags | Resource attributes added to all spans. |
with_timeout | Timeout of the OTLP exporter. The default is 3 seconds. |
with_trace_config | OpenTelemetry SDK trace configuration, for example, a custom sampler. |
Combine with other layers
tracing_axiom::default and build return a standard tracing-subscriber layer. To print spans and events to the console in addition to sending them to Axiom, add a fmt layer to the same registry:
Optional features
tracing-axiom provides the following Cargo features to choose the TLS implementation:
rustls-tls: Enables TLS functionality provided byrustls. Enabled by default.native-tls: Enables TLS functionality provided bynative-tls.default-tls: Enables the default TLS implementation ofreqwest.
Limitations
tracing-axiomexports spans. Events emitted outside of a span aren’t sent to Axiom. To send these events, wrap them in a span or use the Axiom Rust SDK.- The OpenTelemetry exporter requires a multi-threaded Tokio runtime. In tests, use
#[tokio::test(flavor = "multi_thread")]. With the default single-threaded test runtime, tests that export spans can hang. - The standard OpenTelemetry environment variables
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTandOTEL_EXPORTER_OTLP_ENDPOINTtake precedence overAXIOM_URLandwith_url. If you set them for another exporter, unset them for apps that usetracing-axiom.
View traces
After your app sends spans, query them in the dataset you specified. For more information, see Explore traces.
Reference
- For a full reference of the crate’s API, see docs.rs.
- For more examples, see the examples in GitHub.
- To use the OpenTelemetry SDK directly instead of
tracing-axiom, see Send OpenTelemetry data to Axiom.