opentelemetry-zipkin

Zipkin trace exporter for OpenTelemetry

opentelemetry-zipkin

Version: 0.31.0

The opentelemetry-zipkin crate exports trace data to Zipkin using the Zipkin v2 JSON format over HTTP.

Installation

[dependencies]
opentelemetry-zipkin = "0.31"

Feature Flags

• reqwest-blocking-client: Use reqwest blocking HTTP client (enabled by default)
• reqwest-client: Use reqwest async HTTP client
• reqwest-rustls: Use rustls for TLS with reqwest

Quick Start

Start Zipkin

docker run -d -p 9411:9411 openzipkin/zipkin

Basic Usage

use opentelemetry::global;
use opentelemetry::trace::Tracer;
use opentelemetry_sdk::Resource;
use opentelemetry_zipkin::ZipkinExporter;

// Set up Zipkin propagator
global::set_text_map_propagator(opentelemetry_zipkin::Propagator::new());

// Create exporter
let exporter = ZipkinExporter::builder().build()?;

// Create tracer provider
let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
    .with_simple_exporter(exporter)
    .with_resource(Resource::builder_empty()
        .with_service_name("my-service")
        .build()
    )
    .build();

global::set_tracer_provider(provider.clone());

// Use the tracer
let tracer = global::tracer("zipkin-tracer");
tracer.in_span("doing_work", |cx| {
    // Your application logic
});

// Shutdown to flush remaining spans
provider.shutdown()?;

With Batch Exporter

For better performance in production, use a batch span processor:

use opentelemetry_sdk::trace::{BatchSpanProcessor, BatchConfigBuilder};

let exporter = ZipkinExporter::builder().build()?;

let batch = BatchSpanProcessor::builder(exporter)
    .with_batch_config(
        BatchConfigBuilder::default()
            .with_max_queue_size(4096)
            .build()
    )
    .build();

let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
    .with_span_processor(batch)
    .build();

Configuration

Exporter Builder

ZipkinExporter · struct

Exports spans to Zipkin in v2 JSON format

ZipkinExporterBuilder · struct

Builder for configuring the Zipkin exporter

use opentelemetry_zipkin::ZipkinExporter;
use std::net::SocketAddr;

let exporter = ZipkinExporter::builder()
    .with_collector_endpoint("http://localhost:9411/api/v2/spans")
    .with_service_address("127.0.0.1:8080".parse::<SocketAddr>()?)
    .build()?;

Configuration Methods

with_collector_endpoint · fn(String) -> Self

Set the Zipkin collector endpoint URL. Default: http://localhost:9411/api/v2/spans

with_service_address · fn(SocketAddr) -> Self

Set the local service address to report in spans

with_http_client · fn(HttpClient) -> Self

Provide a custom HTTP client implementation

Propagator

Propagator · struct

B3 propagator for Zipkin trace context

B3Encoding · enum

B3 propagation encoding format:

• SingleHeader: Use single b3 header
• MultipleHeader: Use multiple X-B3-* headers (default)

use opentelemetry::global;
use opentelemetry_zipkin::{Propagator, B3Encoding};

// Use single-header B3 format
let propagator = Propagator::with_encoding(B3Encoding::SingleHeader);
global::set_text_map_propagator(propagator);

Custom HTTP Client

You can provide a custom HTTP client by implementing the HttpClient trait:

use opentelemetry_http::{HttpClient, HttpError};
use async_trait::async_trait;
use http::{Request, Response};
use bytes::Bytes;

#[derive(Debug)]
struct MyHttpClient;

#[async_trait]
impl HttpClient for MyHttpClient {
    async fn send_bytes(&self, request: Request<Bytes>) 
        -> Result<Response<Bytes>, HttpError> {
        // Your implementation
        todo!()
    }
}

let exporter = ZipkinExporter::builder()
    .with_http_client(MyHttpClient)
    .build()?;

Error Handling

ExporterBuildError · enum

Errors that can occur during exporter construction

use opentelemetry_zipkin::ZipkinExporter;

match ZipkinExporter::builder().build() {
    Ok(exporter) => { /* use exporter */ },
    Err(e) => eprintln!("Failed to create exporter: {}", e),
}

Environment Variables

The Zipkin exporter does not use environment variables for configuration. All settings must be configured programmatically via the builder.

View Traces

After exporting traces, view them in the Zipkin UI:

http://localhost:9411

HTTP Client Options

Reqwest Blocking (Default)

[dependencies]
opentelemetry-zipkin = "0.31"

Reqwest Async

For async applications using Tokio:

[dependencies]
opentelemetry-zipkin = { version = "0.31", features = ["reqwest-client"], default-features = false }

Custom Client

Implement HttpClient trait for full control over HTTP requests.

Related Crates

• opentelemetry - Core API
• opentelemetry-sdk - SDK implementation
• opentelemetry-http - HTTP utilities

Documentation

Full API Documentation

View complete API reference on docs.rs

Zipkin Documentation

Official Zipkin documentation

Minimum Rust Version

MSRV: 1.75.0