Docs
DocumentationQuery ReferenceAPI Reference
Open Console→→
DocumentationQuery ReferenceAPI Reference

Platform overview

What is Axiom?QuickstartArchitectureFeatures
Fundamentals
Datasets
Edge deployments
Limits
Performance
Optimize usage
Requirements
Semantic conventions
Glossary
Tour
SecurityRoadmap

Send data

Reference architecturesMethods

Understand data

Console
Query
Builder
Editor
Query results
Visualize
Traces
Metrics
Correlations
Save queries
Stream
Dashboard
Create
Elements
Create
Configure
Element types
Gauge
Heatmap
Log stream
Monitor list
Note
Pie chart
Scatter plot
Statistic
Table
Time series
Sections
Configure
Filter
Monitor
Overview
View status
Configure
Examples
Monitor types
Anomaly
Match
New values
Threshold
Alerting
Overview
Configure
Notifier types
Amp
ChatGPT Workspace Agent
Claude Code
Cursor
Custom Webhook
Discord
Email
incident.io
Jira Service Management
Microsoft Teams
Opsgenie
PagerDuty
Slack
Annotations
Command Menu
Manage
Datasets
Overview
Views
Virtual fields
Access
RBAC
Tokens
CLI
Organization
Labels
Audit log
Settings
Usage and billing
Profile
Extend
Overview
AWS Lambda
AWS PrivateLink
Cloudflare Workers
Cloudflare Logpush
Convex
Grafana
Hex
Netlify
Supabase
Tailscale
Terraform
Unkey
Vercel
Intelligence
Overview
Spotlight
AI agents
Overview
MCP Server
Overview
Tools
Query cost limits
Agent-created orgs
Skills
Overview
Axiom alerting
Build dashboards
Control costs
SRE
Translate SPL to APL
Splunk
Overview
Splunk app
Install and configure
Commands
Examples
Portal
How it works
Set up standard mode
Set up transparent mode
Observability Cloud
OCSF data
OCSF as CIM
SPL command support
Examples
Monitor and troubleshoot

Use cases

ObservabilityProduct analytics
OCSF security data
Overview
Send data
Query data
LLM observability
Overview
Use Vercel AI SDK
Manual instrumentation
GenAI attributes
Redaction policies

Miscellaneous

LLMs
Overview
List of docs pages
Full docs
Query reference
FAQs
Legal
Acceptable use policy
Axiom for Startups terms
Committed use terms
Cookies
Data processing
HIPAA
Partner agreement
Partner program guide
Privacy policy
SLA
Terms of service
Terms of use

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.

Info

tracing-axiom is an open-source project and welcomes your contributions. For more information, see the GitHub repository.

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-axiom exports 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:

TOML
[dependencies]
tracing-axiom = "0.7"
tracing = "0.1"
tracing-subscriber = "0.3"
tokio = { version = "1", features = ["full"] }
opentelemetry = "0.22"

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:

shell
export AXIOM_TOKEN="API_TOKEN"
export AXIOM_DATASET="DATASET_NAME"
export AXIOM_URL="https://AXIOM_DOMAIN"
Info

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you send your data.

Replace AXIOM_DOMAIN with the base domain of your edge deployment. For more information, see Edge deployments.

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 deploymentBase 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
Info

tracing-axiom only accepts API tokens (xaat-). Personal access tokens (xapt-) return an InvalidToken error when you create the layer.

Send traces

Create the layer with tracing_axiom::default, add it to a tracing-subscriber registry, and instrument your functions:

rust
use tracing_subscriber::{layer::SubscriberExt as _, util::SubscriberInitExt as _, Registry};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Read AXIOM_TOKEN, AXIOM_DATASET, and AXIOM_URL from the environment
    let axiom_layer = tracing_axiom::default("my-service")?;
    Registry::default().with(axiom_layer).init();

    handle_request(42);

    // Flush buffered spans before the process exits
    opentelemetry::global::shutdown_tracer_provider();
    Ok(())
}

#[tracing::instrument]
fn handle_request(user_id: u64) {
    tracing::info!("Handling request");
}

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:

rust
use std::time::Duration;
use tracing_subscriber::{layer::SubscriberExt as _, util::SubscriberInitExt as _, Registry};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let axiom_layer = tracing_axiom::builder("my-service")
        .with_token("API_TOKEN")?
        .with_dataset("DATASET_NAME")?
        .with_url("https://AXIOM_DOMAIN")?
        // Add resource attributes to all spans
        .with_tags([("deployment.environment", "production")].into_iter())
        // Set the export timeout. The default is 3 seconds.
        .with_timeout(Duration::from_secs(10))
        .build()?;
    Registry::default().with(axiom_layer).init();

    // ...

    opentelemetry::global::shutdown_tracer_provider();
    Ok(())
}
Info

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you send your data.

Replace AXIOM_DOMAIN with the base domain of your edge deployment. For more information, see Edge deployments.

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:

MethodDescription
with_tokenAxiom API token. Overrides AXIOM_TOKEN.
with_datasetName of the dataset where you send traces. Overrides AXIOM_DATASET.
with_urlBase URL of the endpoint. Overrides AXIOM_URL.
with_service_nameValue of the service.name resource attribute.
with_tagsResource attributes added to all spans.
with_timeoutTimeout of the OTLP exporter. The default is 3 seconds.
with_trace_configOpenTelemetry 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:

rust
use tracing_subscriber::{filter::LevelFilter, prelude::*};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let axiom_layer = tracing_axiom::builder_with_env("my-service")?.build()?;
    // Filter console output so that the exporter’s own debug logs stay hidden
    let fmt_layer = tracing_subscriber::fmt::layer().with_filter(LevelFilter::INFO);

    tracing_subscriber::registry()
        .with(fmt_layer)
        .with(axiom_layer)
        .try_init()?;

    handle_request(42);

    opentelemetry::global::shutdown_tracer_provider();
    Ok(())
}

#[tracing::instrument]
fn handle_request(user_id: u64) {
    tracing::info!("Handling request");
}

Optional features

tracing-axiom provides the following Cargo features to choose the TLS implementation:

  • rustls-tls: Enables TLS functionality provided by rustls. Enabled by default.
  • native-tls: Enables TLS functionality provided by native-tls.
  • default-tls: Enables the default TLS implementation of reqwest.

Limitations

  • tracing-axiom exports 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_ENDPOINT and OTEL_EXPORTER_OTLP_ENDPOINT take precedence over AXIOM_URL and with_url. If you set them for another exporter, unset them for apps that use tracing-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.
Was this page helpful?
Suggest edits on GitHub
On this page
Install crateConfigure environmentSend tracesConfigure layer in codeCombine with other layersOptional featuresLimitationsView tracesReference