Zipkin JSON Exporter for OpenTelemetry

Warnings

• gotcha 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.
  Fix: Always set the 'service.name' attribute when initializing the TracerProvider's Resource, e.g., `Resource.create({"service.name": "my-app-name"})`.
• gotcha 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.
  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`).
• gotcha 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.
  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.
• gotcha 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.
  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`.

Install

• pip install opentelemetry-exporter-zipkin-json opentelemetry-sdk requests Install core exporter and SDK

Imports

• ZipkinExporter

  from opentelemetry.exporter.zipkin.json import ZipkinExporter

Quickstart

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.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.zipkin.json import ZipkinExporter

# Configure a TracerProvider with a service name
resource = Resource.create({"service.name": "my-zipkin-service"})
tracer_provider = TracerProvider(resource=resource)
trace.set_tracer_provider(tracer_provider)

# Create a ZipkinExporter
# The default endpoint is http://localhost:9411/api/v2/spans
# You can override it with environment variable OTEL_EXPORTER_ZIPKIN_ENDPOINT
# or by passing the 'endpoint' argument to ZipkinExporter
zipkin_exporter = ZipkinExporter(
    endpoint=os.environ.get("OTEL_EXPORTER_ZIPKIN_ENDPOINT", "http://localhost:9411/api/v2/spans")
)

# Add the exporter to a BatchSpanProcessor
span_processor = BatchSpanProcessor(zipkin_exporter)
tracer_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-span") as span:
    span.set_attribute("event.name", "hello")
    print("Hello, OpenTelemetry with Zipkin!")

# Ensure all spans are exported before exiting
tracer_provider.shutdown()