Skip to main content

​
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.

​
Documentation

Full API Documentation

View complete API reference on docs.rs

Zipkin Documentation

Official Zipkin documentation

​
Minimum Rust Version

MSRV: 1.75.0

Build docs developers (and LLMs) love

Get started for freeTalk to us