py-zipkin

Common errors

• requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))

  cause The Zipkin collector is not running or is not accessible at the specified endpoint (e.g., `http://localhost:9411/api/v2/spans`).
  fix Ensure the Zipkin collector is running and its HTTP API endpoint is correctly configured and reachable from your application. Check firewall rules or container network settings if applicable. Example: `docker run -p 9411:9411 openzipkin/zipkin`

• TypeError: send() takes 2 positional arguments but 3 were given

  cause Your custom transport handler is implemented as a function with one argument (`encoded_span`) but `py-zipkin` is calling it expecting a method of a class (which implicitly includes `self` as the first argument). This typically happens if you haven't correctly subclassed `BaseTransportHandler` for your transport.
  fix Refactor your transport handler to subclass `py_zipkin.transport.BaseTransportHandler` and implement `send(self, encoded_span)` and `get_max_payload_bytes(self)`.

• Error in thread_local context or unexpected trace breakage in asynchronous/multithreaded environments.

  cause By default, `py_zipkin` uses thread-local storage for trace attributes, which is not suitable for cooperative multitasking (e.g., `asyncio`) or complex multithreading without explicit context management.
  fix For cooperative multitasking, explicitly pass instances of `py_zipkin.storage.Stack` as `context_stack` and `py_zipkin.storage.SpanStorage` as `span_storage` to `zipkin_span` and `create_http_headers_for_new_span`.

Warnings

• deprecated The `py_zipkin.thread_local` module and its functionalities are deprecated. Direct usage should be replaced.
  Fix: Migrate to `py_zipkin.storage.ThreadLocalStack` for thread-local storage or explicitly pass `Stack` and `SpanStorage` instances in cooperative multitasking environments like `asyncio`.
• deprecated Older transport handler implementations that were simple functions taking a single `encoded_span` argument are deprecated.
  Fix: Implement your transport handler by subclassing `py_zipkin.transport.BaseTransportHandler` and implementing the `send` and `get_max_payload_bytes` methods.
• gotcha Using `add_sa_binary_annotation` multiple times for the same span in Zipkin V2 span format (which `py-zipkin` predominantly uses) will raise a `ValueError`.
  Fix: The V2 span format only supports a single 'remoteEndpoint' (represented by the 'sa' annotation). Ensure you add 'sa' binary annotations only once per span.
• gotcha The 'Firehose mode' feature is explicitly marked as experimental and may be removed without prior warning.
  Fix: Avoid relying on 'Firehose mode' for critical production workflows due to its experimental status and potential for breaking changes or removal.

Install

• pip install py-zipkin Install latest version

Imports

• zipkin_span

  from py_zipkin.zipkin import zipkin_span

• create_http_headers_for_new_span

  from py_zipkin.zipkin import create_http_headers_for_new_span

• ZipkinAttrs

  from py_zipkin.zipkin import ZipkinAttrs

• Kind

  from py_zipkin.zipkin import Kind

• BaseTransportHandler

  from py_zipkin.transport import BaseTransportHandler

• ThreadLocalStack
  wrong:

  from py_zipkin.thread_local import ThreadLocalStack

  correct:

  from py_zipkin.storage import ThreadLocalStack

  The `py_zipkin.thread_local` module is deprecated. Use `py_zipkin.storage.ThreadLocalStack` instead, especially in cooperative multitasking environments.
• Stack

  from py_zipkin.storage import Stack

• SpanStorage

  from py_zipkin.storage import SpanStorage

Quickstart

This quickstart demonstrates how to use `py_zipkin` with a custom HTTP transport handler to send traces to a Zipkin collector. It shows `zipkin_span` used both as a context manager and a decorator to instrument functions and add binary annotations. A Zipkin server (e.g., `openzipkin/zipkin`) should be running and accessible at `ZIPKIN_COLLECTOR_ENDPOINT` (defaulting to `http://localhost:9411/api/v2/spans`).

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

# Configure your Zipkin collector endpoint (e.g., http://localhost:9411/api/v2/spans)
ZIPKIN_COLLECTOR_ENDPOINT = os.environ.get('ZIPKIN_COLLECTOR_ENDPOINT', 'http://localhost:9411/api/v2/spans')

# A simple HTTP transport handler for demonstration
class HTTPTransportHandler(BaseTransportHandler):
    def send(self, encoded_span):
        # The collector expects a thrift-encoded list of spans.
        try:
            requests.post(
                ZIPKIN_COLLECTOR_ENDPOINT,
                data=encoded_span,
                headers={'Content-Type': 'application/x-thrift'},
                timeout=5
            )
        except requests.exceptions.RequestException as e:
            print(f"Failed to send span to Zipkin: {e}")

    def get_max_payload_bytes(self):
        return None # No explicit limit for this example


def do_stuff(a, b):
    print(f"Doing stuff with {a} and {b}")
    return a + b

# Instantiate the transport handler
my_transport_handler = HTTPTransportHandler()

# Usage as a context manager
def my_function(x, y):
    with zipkin_span(
        service_name='my_python_service',
        span_name='my_function_span',
        transport_handler=my_transport_handler,
        port=8000, # Optional: Port of the service
        sample_rate=100.0 # Sample all traces for demonstration (0.0 - 100.0)
    ) as zipkin_context:
        result = do_stuff(x, y)
        zipkin_context.update_binary_annotations({'input_x': x, 'input_y': y, 'result': result})
        print(f"Trace for my_function completed with result: {result}")
        return result

# Usage as a decorator
@zipkin_span(
    service_name='my_python_service',
    span_name='decorated_function',
    transport_handler=my_transport_handler,
    sample_rate=50.0
)
def another_function(data):
    print(f"Processing data: {data}")
    return data.upper()

if __name__ == "__main__":
    print("--- Running context manager example ---")
    my_function(10, 20)

    print("\n--- Running decorator example ---")
    another_function("hello world")
    print("Check your Zipkin UI (e.g., http://localhost:9411/zipkin) for traces.")