OpenTelemetry Rust distro for Uptrace

Uptrace is an open-source, OpenTelemetry-native APM platform. This document explains how to configure the OpenTelemetry Rust SDK to export spans (traces), logs, and metrics to Uptrace using OTLP.

Choose Your Setup Path

Option A: Quick Start with the uptrace crate

Best for: Getting started quickly, automatic configuration

uptrace is a thin wrapper over opentelemetry-rust that configures the OpenTelemetry SDK to export traces, metrics, and logs to Uptrace. It does not add any new functionality and is provided only for your convenience.

Continue below

Option B: Direct OTLP Configuration

Best for: Existing OpenTelemetry users, custom exporters, fine-grained control

Direct OTLP Setup

Quick Start Guide

Follow these steps to get your first trace running in 5 minutes:

Step 1: Create an Uptrace Project

Create an Uptrace project (or self-host Uptrace) to obtain a DSN (Data Source Name), for example, https://<secret>@api.uptrace.dev?grpc=4317.

Step 2: Install the uptrace crate

cargo add uptrace opentelemetry

Or add the dependencies to your Cargo.toml manually:

[dependencies]
uptrace = "0.33"
opentelemetry = "0.33"

The uptrace crate version follows the OpenTelemetry Rust version it is built with. Keep opentelemetry on the same version, or use the re-exported uptrace::opentelemetry and uptrace::opentelemetry_sdk crates.

Step 3: Basic Configuration

You can configure the Uptrace client using a DSN (Data Source Name) from the project settings page. Replace myservice with a name that identifies your application.

let uptrace = uptrace::Uptrace::builder()
    // copy your project DSN here or use UPTRACE_DSN env var
    //.with_dsn("<FIXME>")
    .with_service_name("myservice")
    .with_service_version("1.0.0")
    .with_deployment_environment("production")
    .build()?;

build() creates and registers the global tracer and meter providers, so you can use opentelemetry::global anywhere in your code. Call uptrace.shutdown() before the program exits to send buffered data.

Step 4: Create Your First Trace

Copy the code to src/main.rs:

use std::thread;
use std::time::Duration;

use opentelemetry::trace::{TraceContextExt, Tracer};
use opentelemetry::{global, KeyValue};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure OpenTelemetry with sensible defaults.
    let uptrace = uptrace::Uptrace::builder()
        // copy your project DSN here or use UPTRACE_DSN env var
        //.with_dsn("<FIXME>")
        .with_service_name("myservice")
        .with_service_version("1.0.0")
        .build()?;

    // Create a tracer. Usually, tracer is a global variable.
    let tracer = global::tracer("app_or_crate_name");

    // Create a root span (a trace) to measure some operation.
    tracer.in_span("main-operation", |cx| {
        // Spans created inside the closure become children of main-operation.
        tracer.in_span("GET /posts/:id", |cx| {
            thread::sleep(Duration::from_millis(10));

            let span = cx.span();
            span.set_attribute(KeyValue::new("http.request.method", "GET"));
            span.set_attribute(KeyValue::new("http.route", "/posts/:id"));
            span.set_attribute(KeyValue::new("http.response.status_code", 200));

            // Record an error on the current span.
            uptrace.report_error(&std::io::Error::other("dummy error"));
        });

        tracer.in_span("SELECT", |cx| {
            thread::sleep(Duration::from_millis(20));

            let span = cx.span();
            span.set_attribute(KeyValue::new("db.system.name", "mysql"));
            span.set_attribute(KeyValue::new("db.query.text", "SELECT * FROM posts LIMIT 100"));
        });

        println!("trace: {}", uptrace.trace_url(cx.span().span_context()));
    });

    // Send buffered data and free resources.
    uptrace.shutdown()?;
    Ok(())
}

Step 5: Run Your Application

Run the code, replacing <FIXME> with your Uptrace DSN:

$ UPTRACE_DSN="<FIXME>" cargo run
trace: https://app.uptrace.dev/traces/<trace_id>?span_id=<span_id>

Step 6: View Your Trace

Follow the link to view the trace:

Configuration Options

You can find the full list of available options at docs.rs.

The Uptrace handle returned by build() provides trace_url, current_trace_url, report_error, force_flush, and shutdown.

Cargo features

For example, to export over gRPC only:

[dependencies]
uptrace = { version = "0.33", default-features = false, features = ["grpc"] }

Environment variables

# Endpoint (choose HTTP or gRPC)
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.uptrace.dev"         # HTTP
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.uptrace.dev:4317"   # gRPC

# Pass DSN for authentication
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=<FIXME>"

# Performance optimizations
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=BASE2_EXPONENTIAL_BUCKET_HISTOGRAM
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA

export OTEL_BSP_EXPORT_TIMEOUT=10000         # Max export timeout (ms)
export OTEL_BSP_MAX_EXPORT_BATCH_SIZE=10000  # Avoid >32MB payloads
export OTEL_BSP_MAX_QUEUE_SIZE=30000         # Adjust for available memory
export OTEL_BSP_MAX_CONCURRENT_EXPORTS=2     # Parallel exports

Troubleshooting

Common Issues

No data in Uptrace:

• Verify the DSN is set correctly, either via .with_dsn("...") or the UPTRACE_DSN environment variable. build() returns an error for an empty or invalid DSN.
• Check that the endpoint is reachable: https://api.uptrace.dev:443 (HTTP) or https://api.uptrace.dev:4317 (gRPC).
• Make sure you call uptrace.shutdown() before the program exits — without it, buffered spans are dropped.
• Check that UPTRACE_DISABLED is not set; uptrace.is_enabled() returns false in that case.

Build errors with mismatched types:

• Errors such as "expected opentelemetry::..., found a different opentelemetry::..." mean two OpenTelemetry versions are in your dependency tree. Use the same 0.33 version for all opentelemetry* crates, or use the re-exported uptrace::opentelemetry. Run cargo tree -d -i opentelemetry to find duplicates.

gRPC exporter panics or doesn't export:

• The grpc feature uses tonic, which requires a Tokio runtime. Build Uptrace inside #[tokio::main] and call shutdown() from tokio::task::spawn_blocking.

Logs exported in an infinite loop:

• When using uptrace.log_layer(), filter out the exporter's own logs with EnvFilter directives such as hyper=off, h2=off, tonic=off, and reqwest=off. See Logs.

What's Next?

Instrument more operations to get a detailed picture of your application. Prioritize network calls, database queries, errors, and logs.

By Use Case

Framework Guides

OpenTelemetry Rust integrates with popular frameworks through the tracing ecosystem:

See the OTLP Configuration page for Axum and Actix-web integration examples.