{"id":2626,"library":"opentelemetry-exporter-zipkin-json","title":"Zipkin JSON Exporter for OpenTelemetry","description":"This library allows to export tracing data to Zipkin using JSON for serialization. It is part of the OpenTelemetry Python project, which releases frequently (typically monthly or bi-monthly). The current version is 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","exporter","zipkin","observability","json"],"install":[{"cmd":"pip install opentelemetry-exporter-zipkin-json opentelemetry-sdk requests","lang":"bash","label":"Install core exporter and SDK"}],"dependencies":[{"reason":"Required for OpenTelemetry SDK functionalities like TracerProvider and SpanProcessor.","package":"opentelemetry-sdk"},{"reason":"Used internally by the ZipkinExporter for sending traces via HTTP.","package":"requests","optional":true}],"imports":[{"symbol":"ZipkinExporter","correct":"from opentelemetry.exporter.zipkin.json import ZipkinExporter"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.zipkin.json import ZipkinExporter\n\n# Configure a TracerProvider with a service name\nresource = Resource.create({\"service.name\": \"my-zipkin-service\"})\ntracer_provider = TracerProvider(resource=resource)\ntrace.set_tracer_provider(tracer_provider)\n\n# Create a ZipkinExporter\n# The default endpoint is http://localhost:9411/api/v2/spans\n# You can override it with environment variable OTEL_EXPORTER_ZIPKIN_ENDPOINT\n# or by passing the 'endpoint' argument to ZipkinExporter\nzipkin_exporter = ZipkinExporter(\n    endpoint=os.environ.get(\"OTEL_EXPORTER_ZIPKIN_ENDPOINT\", \"http://localhost:9411/api/v2/spans\")\n)\n\n# Add the exporter to a BatchSpanProcessor\nspan_processor = BatchSpanProcessor(zipkin_exporter)\ntracer_provider.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-span\") as span:\n    span.set_attribute(\"event.name\", \"hello\")\n    print(\"Hello, OpenTelemetry with Zipkin!\")\n\n# Ensure all spans are exported before exiting\ntracer_provider.shutdown()\n","lang":"python","description":"This quickstart demonstrates how to set up the OpenTelemetry Python SDK with the Zipkin JSON Exporter. It initializes a TracerProvider, configures the ZipkinExporter to send traces to a default or environment-variable-defined endpoint, and uses a BatchSpanProcessor for efficient trace export. Finally, it creates a simple span and ensures proper shutdown."},"warnings":[{"fix":"Always set the 'service.name' attribute when initializing the TracerProvider's Resource, e.g., `Resource.create({\"service.name\": \"my-app-name\"})`.","message":"Missing 'service.name' Resource Attribute: If the 'service.name' resource attribute is not explicitly set, traces may appear as 'unknown_service' in the Zipkin UI, making it difficult to identify the originating service.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Enable OpenTelemetry debug logging (`OTEL_PYTHON_LOG_LEVEL=DEBUG`) and monitor exporter logs for errors. Verify the Zipkin collector is running and accessible at the configured endpoint (e.g., `http://localhost:9411/api/v2/spans`).","message":"Silent Export Failures: OpenTelemetry exporters, including Zipkin, often fail silently if there are configuration errors (e.g., incorrect endpoint URL, network issues, or timeouts). Traces might not reach Zipkin without any obvious error message.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all spans are properly ended. Use `with tracer.start_as_current_span(...)` or explicitly call `span.end()`. Always configure the SDK with a `BatchSpanProcessor` for production environments.","message":"Unended Spans Not Exported: Spans created but not explicitly ended (e.g., `span.end()` or exiting a `with` block) will remain in memory and will not be exported. Additionally, avoid using `SimpleSpanProcessor` in production as it blocks the application thread; `BatchSpanProcessor` is recommended for performance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the `endpoint` URL matches your Zipkin collector's configuration, including the full path. Use the `OTEL_EXPORTER_ZIPKIN_ENDPOINT` environment variable or pass the `endpoint` argument directly to `ZipkinExporter`.","message":"Incorrect Zipkin Endpoint Configuration: The Zipkin exporter defaults to `http://localhost:9411/api/v2/spans`. A common mistake is using an incorrect host, port, or omitting the `/api/v2/spans` path, which can lead to connection refused or 404 errors at the Zipkin collector.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}