OpenTelemetry Zipkin Exporter

1.41.0 · active · verified Thu Apr 16

The `opentelemetry-exporter-zipkin` library provides a Span Exporter for OpenTelemetry Python, enabling the export of trace data to Zipkin. It is part of the OpenTelemetry Python project, currently at version 1.41.0, and typically releases updates on a monthly or bi-monthly basis.

Common errors

```
TypeError: Couldn't build proto file into descriptor pool! Invalid proto descriptor for file "py_zipkin/encoding/protobuf/zipkin.proto": zipkin.proto3.Span.local_endpoint: "zipkin.proto3.Span.local_endpoint" is already defined in file "zipkin.proto".
```
cause Conflict between `opentelemetry-exporter-zipkin` and the `py-zipkin` library due to duplicate Protobuf definitions.

fix Uninstall `py-zipkin` if it's not strictly needed, or migrate its functionality to use OpenTelemetry. If both are essential, run them in isolated Python environments.
```
StatusRuntimeException: UNAVAILABLE: io exception
```
cause The Zipkin exporter failed to connect to the Zipkin collector endpoint, often due to the collector not running, an incorrect endpoint URL, or network issues.

fix Ensure your Zipkin collector is running and reachable at the configured endpoint (default `http://localhost:9411/api/v2/spans`). Verify the `OTEL_EXPORTER_ZIPKIN_ENDPOINT` environment variable or the `endpoint` parameter in `ZipkinSpanExporter` is correct. Check network connectivity and firewall rules.
```
ModuleNotFoundError: No module named 'opentelemetry.exporter.zipkin'
```
cause The `opentelemetry-exporter-zipkin` package is not installed in the current Python environment.

fix Install the package using pip: `pip install opentelemetry-exporter-zipkin`.

Warnings

deprecated The OpenTelemetry project is deprecating the Zipkin exporter specification in favor of native OTLP support, as Zipkin now supports OTLP ingestion directly. The specification was deprecated in December 2025.
Fix: Migrate to using the OpenTelemetry Protocol (OTLP) exporter (`opentelemetry-exporter-otlp`) and configure your Zipkin backend to ingest OTLP directly. Existing stable Zipkin exporters will receive security patches and critical bug fixes until at least December 2026.
gotcha When using the `opentelemetry-exporter-zipkin` alongside `py-zipkin` (an older, unrelated Python Zipkin library), you might encounter Protobuf definition conflicts, leading to `TypeError: Couldn't build proto file into descriptor pool!`.
Fix: Avoid installing both `opentelemetry-exporter-zipkin` and `py-zipkin` in the same environment. If you need both, ensure they are isolated (e.g., in separate virtual environments) or migrate away from `py-zipkin` to use OpenTelemetry exclusively for tracing.
gotcha The exporter expects a running Zipkin collector. If the collector is unavailable or the endpoint is incorrect, traces will not be exported. While SDK span processors generally catch and log export exceptions, repeated connection failures can indicate a misconfiguration.
Fix: Verify that the Zipkin collector is running and accessible from your application's host. Check the `OTEL_EXPORTER_ZIPKIN_ENDPOINT` environment variable or the `endpoint` parameter in `ZipkinSpanExporter` for correctness. Ensure network connectivity (e.g., firewall rules, host IP).

Install

pip install opentelemetry-exporter-zipkin Install latest version

Imports

ZipkinSpanExporter
wrong:
```
from opentelemetry.ext import zipkin
```
correct:
```
from opentelemetry.exporter.zipkin import ZipkinSpanExporter
```
The `ext` namespace was used in older versions for extensions. The direct `opentelemetry.exporter.zipkin` path is the current and recommended import for the Zipkin exporter.

Quickstart

This quickstart demonstrates how to configure OpenTelemetry Python to send traces to a Zipkin collector. It sets up a `TracerProvider`, `BatchSpanProcessor`, and `ZipkinSpanExporter`, using environment variables for the Zipkin endpoint, and then creates a simple traced operation. Ensure a Zipkin collector is running and accessible at the specified endpoint.

import os
from opentelemetry import trace
from opentelemetry.exporter.zipkin import ZipkinSpanExporter
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Configure the service name
resource = Resource.create({
    SERVICE_NAME: "my-zipkin-service"
})

# Configure TracerProvider
tracer_provider = TracerProvider(resource=resource)

# Get Zipkin collector endpoint from environment variable or use default
zipkin_endpoint = os.environ.get(
    "OTEL_EXPORTER_ZIPKIN_ENDPOINT", 
    "http://localhost:9411/api/v2/spans"
)

# Configure ZipkinSpanExporter
zipkin_exporter = ZipkinSpanExporter(endpoint=zipkin_endpoint)

# Configure BatchSpanProcessor and add exporter
span_processor = BatchSpanProcessor(zipkin_exporter)
tracer_provider.add_span_processor(span_processor)

# Set the global TracerProvider
trace.set_tracer_provider(tracer_provider)

# Get a tracer and create a span
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-operation"):
    print("Hello from OpenTelemetry with Zipkin!")

print(f"Traces sent to Zipkin endpoint: {zipkin_endpoint}")

view raw JSON →