#tracing #instrumentation #axiom

tracing-axiom

The tracing layer for shipping traces to Axiom

3 releases (breaking)

Uses new Rust 2021

0.3.0 Aug 29, 2022
0.2.0 Aug 26, 2022
0.1.0 Aug 26, 2022

#17 in #telemetry

MIT/Apache

17KB
215 lines

tracing-axiom

CI crates.io docs.rs License

The tracing layer for shipping traces to Axiom.

Install

Add the following to your Cargo.toml:

[dependencies]
tracing-axiom = "0.3"

Quickstart

Expose an API token with ingest permission under AXIOM_TOKEN and initialize the exporter like this:

#[tokio::main]
async fn main() {
    let _guard = tracing_axiom::init(); // or try_init() to handle errors
    say_hello();
}

#[tracing::instrument]
pub fn say_hello() {
    tracing::info!("Hello, world!");
}

Note: Due to a limitation of an underlying library, events outside of a span are not recorded.

Kitchen Sink Full Configuration

Here's a full configuration:

use opentelemetry::sdk::trace;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let trace_config = trace::Config::default()
    .with_max_events_per_span(42);

  let _guard = tracing_axiom::builder()
    .with_token("xaat-123456789")
    .with_url("https://my-axiom.example.org")
    .with_service_name("my-service")
    .with_trace_config(trace_config)
    .try_init()?;
  Ok(())
}

If you want to use other layers next to Axiom in your tracing configuration, check out the fmt example.

Under The Hood

This library uses OpenTelemetry to send data to Axiom. You can set this up yourself if you want to, but make sure to use the OTLP format with the http transport and set the endpoint to https://cloud.axiom.co/api/v1/traces. A good entrypoint is the opentelemetry-otlp crate.

Features

The following are a list of Cargo features that can be enabled or disabled:

  • default-tls (enabled by default): Provides TLS support to connect over HTTPS.
  • native-tls: Enables TLS functionality provided by native-tls.
  • rustls-tls: Enables TLS functionality provided by rustls.

FAQ & Troubleshooting

How do I log traces to the console in addition to Axiom?

You can use this library to get a tracing-subscriber::layer and combine it with other layers, for example one that prints traces to the console. You can see how this works in the fmt example.

Logs are not appearing in Axiom

init, try_init and layer all return a Guard, which will shutdown the tracer provider on drop. Logs won't be sent to Axiom if the Guard is dropped prematurely. If you have a function that sets up observability, return the Guard up to the main func to prevent it from being dropped.

My test function hangs indefinitely

This can happen when you use #[tokio::test] as that defaults to a single-threaded executor, but the opentelemetry crate requires a multi-thread executor.

License

Licensed under either of

at your option.

Dependencies

~10–20MB
~377K SLoC