Zipkin Proto HTTP Span Exporter for OpenTelemetry

Common errors

• ModuleNotFoundError: No module named 'opentelemetry.ext.zipkin'

  cause This import path (`opentelemetry.ext.zipkin`) is for an older or different OpenTelemetry Zipkin exporter package (e.g., `opentelemetry-ext-zipkin`). The current `opentelemetry-exporter-zipkin-proto-http` uses a different import structure.
  fix Update your import statement to `from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter`.

• requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))

  cause The Python application failed to connect to the configured Zipkin collector endpoint. This usually means the collector is not running, is on a different host/port, or a firewall is blocking the connection.
  fix Verify that the Zipkin collector is running and accessible at the specified endpoint (e.g., `http://localhost:9411/api/v2/spans`). Check `OTEL_EXPORTER_ZIPKIN_ENDPOINT` environment variable or the `endpoint` parameter in `ZipkinExporter`. Ensure no firewall rules are blocking the connection.

• AttributeError: 'NoneType' object has no attribute 'add_span_processor'

  cause The `trace.get_tracer_provider()` call is returning `None` because a `TracerProvider` has not been set, or was set too late in the application's lifecycle.
  fix Ensure `trace.set_tracer_provider(TracerProvider())` is called early in your application, typically during startup, before any attempts to get a tracer or add span processors.

Warnings

• breaking In v1.40.0, the behavior of `start_span` and `start_as_current_span` within `NoOpTracer` (used when the SDK is not initialized) was fixed to correctly propagate span context. Previously, it would strictly return `INVALID_SPAN`, potentially causing unexpected tracing behavior in certain scenarios.
  Fix: Review any code that relies on `NoOpTracer` explicitly or implicitly when the SDK is not present, as span context will now propagate.
• deprecated The OpenTelemetry project is deprecating the Zipkin exporter specification in favor of Zipkin's OTLP ingestion support. Existing Zipkin exporters will continue to receive security patches and critical bug fixes until at least December 2026. Users are strongly encouraged to migrate to OTLP for long-term support and broader compatibility.
  Fix: Consider switching to the OpenTelemetry Protocol (OTLP) exporter (`opentelemetry-exporter-otlp-proto-http`) and routing data via the OpenTelemetry Collector, which can then export to Zipkin if needed.
• gotcha Incorrectly configuring the Zipkin collector endpoint can lead to spans not being exported, often silently. Common issues include wrong host, port, or protocol, or the Zipkin collector not being accessible/running.
  Fix: Ensure the `endpoint` parameter in `ZipkinExporter` or the `OTEL_EXPORTER_ZIPKIN_ENDPOINT` environment variable points to a reachable and correctly configured Zipkin collector (e.g., `http://localhost:9411/api/v2/spans`). Check network connectivity and firewall rules. Run `docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin` to quickly test a local Zipkin instance.

Install

• pip install opentelemetry-exporter-zipkin-proto-http opentelemetry-sdk Install package and SDK

Imports

• ZipkinExporter

  from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter

• TracerProvider

  from opentelemetry.sdk.trace import TracerProvider

• BatchSpanProcessor

  from opentelemetry.sdk.trace.export import BatchSpanProcessor

• trace
  wrong:

  from opentelemetry.trace import trace

  correct:

  from opentelemetry import trace

  The `trace` module is a top-level package.

Quickstart

This quickstart demonstrates how to set up the Zipkin Proto HTTP Exporter to send traces. It initializes a `TracerProvider`, configures `ZipkinExporter` with an endpoint (defaulting to `http://localhost:9411/api/v2/spans` or an environment variable), attaches it to a `BatchSpanProcessor`, and creates a simple span. Remember to run a Zipkin collector (e.g., via `docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin`) for traces to be received.

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter

# Configure the TracerProvider
provider = TracerProvider()
trace.set_tracer_provider(provider)

# Configure Zipkin Exporter
# The endpoint can also be configured via OTEL_EXPORTER_ZIPKIN_ENDPOINT environment variable
zipkin_endpoint = os.environ.get('OTEL_EXPORTER_ZIPKIN_ENDPOINT', 'http://localhost:9411/api/v2/spans')
zipkin_exporter = ZipkinExporter(endpoint=zipkin_endpoint)

# Add the exporter to a BatchSpanProcessor
span_processor = BatchSpanProcessor(zipkin_exporter)
provider.add_span_processor(span_processor)

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

with tracer.start_as_current_span("my-zipkin-span") as span:
    span.set_attribute("event.name", "Quickstart event")
    span.add_event("Processing data")
    print("Hello from OpenTelemetry with Zipkin!")

# Ensure all spans are exported before application exit
provider.shutdown()