py-zipkin

What it is and what it does

py_zipkin is a Python library that integrates Zipkin distributed tracing into your applications. It provides the zipkin_span context manager and decorator to wrap code blocks or functions, automatically creating and sending trace spans to a Zipkin collector. The library handles span creation, sampling, and context propagation across service boundaries.

You supply a transport handler (HTTP, Kafka, or custom) that encodes spans in thrift format and sends them to your Zipkin backend. py_zipkin manages the trace context using thread-local storage by default, with support for explicit Stack and SpanStorage instances in multithreaded or async environments. It also offers utilities to add binary annotations, mark remote service calls, and generate HTTP headers for propagating trace context to downstream services.

Use it for

• Instrument a microservice to trace requests end-to-end across multiple services by propagating trace headers.
• Add sampling-based tracing to high-throughput services to monitor latency and service dependencies without capturing every request.
• Record custom span metadata (binary annotations) during request processing to track business logic or debug information.
• Mark calls to non-instrumented external services with remote endpoint annotations so the trace graph shows the full call chain.
• Implement firehose mode to capture 100% of spans for a subset of traffic and route them to a separate retention backend.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

py-zipkin on PyPI

Before you install

Low install friction with a single runtime dependency (typing-extensions). Maintenance status is active with recent commits as of 2026-04-02, though the latest release was 2023-03-24.

Requires a transport handler implementation to send spans; without one, spans are created but not exported. Zipkin collector endpoint must be accessible from your application.

License in practice

Licensed under Apache v2 (permissive). No restrictions on commercial or private use; modifications and redistribution are allowed under Apache terms.

Quickstart

pip install py_zipkin

from py_zipkin.zipkin import zipkin_span
from py_zipkin.transport import BaseTransportHandler

class MyTransport(BaseTransportHandler):
    def get_max_payload_bytes(self):
        return None
    def send(self, encoded_span):
        pass  # Send to Zipkin collector

with zipkin_span(
    service_name='my_service',
    span_name='my_operation',
    transport_handler=MyTransport(),
    port=9411,
    sample_rate=0.05,
):
    # Your code here
    pass

Package facts

Evidence: py_zipkin-1.2.8-py3-none-any.whl

Tags

More Python Modules packages

See also opentelemetry-exporter-zipkin-proto-http · opentelemetry-exporter-zipkin · opentelemetry-exporter-zipkin-json · opentelemetry-instrumentation-aiokafka · opentelemetry-instrumentation-kafka-python · opentelemetry-instrumentation-confluent-kafka · opentelemetry-instrumentation-httpx · jaeger-client · opentelemetry-instrumentation-ollama · opentracing