{"id":8378,"library":"opentelemetry-exporter-zipkin-proto-http","title":"Zipkin Proto HTTP Span Exporter for OpenTelemetry","description":"The `opentelemetry-exporter-zipkin-proto-http` library provides a Span Exporter for OpenTelemetry Python, enabling applications to send tracing data to a Zipkin collector using Protobuf over HTTP. It is an integral part of the OpenTelemetry Python project, which maintains an active release cadence, with the current version being 1.41.0.","status":"active","version":"1.41.0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python","tags":["opentelemetry","tracing","zipkin","exporter","observability","protobuf"],"install":[{"cmd":"pip install opentelemetry-exporter-zipkin-proto-http opentelemetry-sdk","lang":"bash","label":"Install package and SDK"}],"dependencies":[{"reason":"Core OpenTelemetry API for tracing concepts.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK for trace processing and management.","package":"opentelemetry-sdk","optional":false},{"reason":"Used for making HTTP requests to the Zipkin collector.","package":"requests","optional":false},{"reason":"Required for Protobuf serialization of span data.","package":"protobuf","optional":false}],"imports":[{"symbol":"ZipkinExporter","correct":"from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter"},{"symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"},{"symbol":"BatchSpanProcessor","correct":"from opentelemetry.sdk.trace.export import BatchSpanProcessor"},{"note":"The `trace` module is a top-level package.","wrong":"from opentelemetry.trace import trace","symbol":"trace","correct":"from opentelemetry import trace"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.zipkin.proto.http import ZipkinExporter\n\n# Configure the TracerProvider\nprovider = TracerProvider()\ntrace.set_tracer_provider(provider)\n\n# Configure Zipkin Exporter\n# The endpoint can also be configured via OTEL_EXPORTER_ZIPKIN_ENDPOINT environment variable\nzipkin_endpoint = os.environ.get('OTEL_EXPORTER_ZIPKIN_ENDPOINT', 'http://localhost:9411/api/v2/spans')\nzipkin_exporter = ZipkinExporter(endpoint=zipkin_endpoint)\n\n# Add the exporter to a BatchSpanProcessor\nspan_processor = BatchSpanProcessor(zipkin_exporter)\nprovider.add_span_processor(span_processor)\n\n# Get a tracer and create a span\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span(\"my-zipkin-span\") as span:\n    span.set_attribute(\"event.name\", \"Quickstart event\")\n    span.add_event(\"Processing data\")\n    print(\"Hello from OpenTelemetry with Zipkin!\")\n\n# Ensure all spans are exported before application exit\nprovider.shutdown()","lang":"python","description":"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."},"warnings":[{"fix":"Review any code that relies on `NoOpTracer` explicitly or implicitly when the SDK is not present, as span context will now propagate.","message":"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.","severity":"breaking","affected_versions":">=1.40.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions (deprecation announced Dec 2025)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update your import statement to `from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter`.","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.","error":"ModuleNotFoundError: No module named 'opentelemetry.ext.zipkin'"},{"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.","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.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))"},{"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.","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.","error":"AttributeError: 'NoneType' object has no attribute 'add_span_processor'"}]}