{"id":8379,"library":"opentelemetry-exporter-zipkin","title":"OpenTelemetry Zipkin Exporter","description":"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.","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","distributed tracing","observability"],"install":[{"cmd":"pip install opentelemetry-exporter-zipkin","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the core OpenTelemetry SDK components, including `TracerProvider` and `BatchSpanProcessor`, necessary for managing and processing spans before export.","package":"opentelemetry-sdk"},{"reason":"Provides the OpenTelemetry API interfaces for creating traces and spans.","package":"opentelemetry-api"}],"imports":[{"note":"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.","wrong":"from opentelemetry.ext import zipkin","symbol":"ZipkinSpanExporter","correct":"from opentelemetry.exporter.zipkin import ZipkinSpanExporter"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.exporter.zipkin import ZipkinSpanExporter\nfrom opentelemetry.sdk.resources import Resource, SERVICE_NAME\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\n\n# Configure the service name\nresource = Resource.create({\n    SERVICE_NAME: \"my-zipkin-service\"\n})\n\n# Configure TracerProvider\ntracer_provider = TracerProvider(resource=resource)\n\n# Get Zipkin collector endpoint from environment variable or use default\nzipkin_endpoint = os.environ.get(\n    \"OTEL_EXPORTER_ZIPKIN_ENDPOINT\", \n    \"http://localhost:9411/api/v2/spans\"\n)\n\n# Configure ZipkinSpanExporter\nzipkin_exporter = ZipkinSpanExporter(endpoint=zipkin_endpoint)\n\n# Configure BatchSpanProcessor and add exporter\nspan_processor = BatchSpanProcessor(zipkin_exporter)\ntracer_provider.add_span_processor(span_processor)\n\n# Set the global TracerProvider\ntrace.set_tracer_provider(tracer_provider)\n\n# Get a tracer and create a span\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span(\"my-operation\"):\n    print(\"Hello from OpenTelemetry with Zipkin!\")\n\nprint(f\"Traces sent to Zipkin endpoint: {zipkin_endpoint}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions (spec deprecated December 2025)"},{"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.","message":"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!`.","severity":"gotcha","affected_versions":"All versions when `py-zipkin` is also installed."},{"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).","message":"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.","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":"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.","cause":"Conflict between `opentelemetry-exporter-zipkin` and the `py-zipkin` library due to duplicate Protobuf definitions.","error":"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\"."},{"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.","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.","error":"StatusRuntimeException: UNAVAILABLE: io exception"},{"fix":"Install the package using pip: `pip install opentelemetry-exporter-zipkin`.","cause":"The `opentelemetry-exporter-zipkin` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'opentelemetry.exporter.zipkin'"}]}