{"library":"py-zipkin","title":"py-zipkin","description":"py-zipkin is a Python library that provides utilities, including a context manager and decorator, to facilitate the usage of Zipkin for distributed tracing in Python applications. It enables instrumenting code to send trace data to a Zipkin collector. The library is actively maintained with irregular releases, the latest being v1.2.8 released in early 2023.","language":"python","status":"active","last_verified":"Mon May 18","install":{"commands":["pip install py-zipkin"],"cli":null},"imports":["from py_zipkin.zipkin import zipkin_span","from py_zipkin.zipkin import create_http_headers_for_new_span","from py_zipkin.zipkin import ZipkinAttrs","from py_zipkin.zipkin import Kind","from py_zipkin.transport import BaseTransportHandler","from py_zipkin.storage import ThreadLocalStack","from py_zipkin.storage import Stack","from py_zipkin.storage import SpanStorage"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import requests\nimport os\nfrom py_zipkin.zipkin import zipkin_span\nfrom py_zipkin.transport import BaseTransportHandler\n\n# Configure your Zipkin collector endpoint (e.g., http://localhost:9411/api/v2/spans)\nZIPKIN_COLLECTOR_ENDPOINT = os.environ.get('ZIPKIN_COLLECTOR_ENDPOINT', 'http://localhost:9411/api/v2/spans')\n\n# A simple HTTP transport handler for demonstration\nclass HTTPTransportHandler(BaseTransportHandler):\n    def send(self, encoded_span):\n        # The collector expects a thrift-encoded list of spans.\n        try:\n            requests.post(\n                ZIPKIN_COLLECTOR_ENDPOINT,\n                data=encoded_span,\n                headers={'Content-Type': 'application/x-thrift'},\n                timeout=5\n            )\n        except requests.exceptions.RequestException as e:\n            print(f\"Failed to send span to Zipkin: {e}\")\n\n    def get_max_payload_bytes(self):\n        return None # No explicit limit for this example\n\n\ndef do_stuff(a, b):\n    print(f\"Doing stuff with {a} and {b}\")\n    return a + b\n\n# Instantiate the transport handler\nmy_transport_handler = HTTPTransportHandler()\n\n# Usage as a context manager\ndef my_function(x, y):\n    with zipkin_span(\n        service_name='my_python_service',\n        span_name='my_function_span',\n        transport_handler=my_transport_handler,\n        port=8000, # Optional: Port of the service\n        sample_rate=100.0 # Sample all traces for demonstration (0.0 - 100.0)\n    ) as zipkin_context:\n        result = do_stuff(x, y)\n        zipkin_context.update_binary_annotations({'input_x': x, 'input_y': y, 'result': result})\n        print(f\"Trace for my_function completed with result: {result}\")\n        return result\n\n# Usage as a decorator\n@zipkin_span(\n    service_name='my_python_service',\n    span_name='decorated_function',\n    transport_handler=my_transport_handler,\n    sample_rate=50.0\n)\ndef another_function(data):\n    print(f\"Processing data: {data}\")\n    return data.upper()\n\nif __name__ == \"__main__\":\n    print(\"--- Running context manager example ---\")\n    my_function(10, 20)\n\n    print(\"\\n--- Running decorator example ---\")\n    another_function(\"hello world\")\n    print(\"Check your Zipkin UI (e.g., http://localhost:9411/zipkin) for traces.\")","lang":"python","description":"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`).","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-18","installed_version":"1.2.8","pypi_latest":"1.2.8","is_stale":false,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":1.6,"avg_import_s":0.16,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.13,"mem_mb":5.7,"disk_size":"18.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.1,"mem_mb":5.6,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.23,"mem_mb":6.3,"disk_size":"20.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.7,"import_time_s":0.2,"mem_mb":6.3,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.18,"mem_mb":5.9,"disk_size":"12.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.18,"mem_mb":5.9,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.16,"mem_mb":6,"disk_size":"11.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.17,"mem_mb":6,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.12,"mem_mb":5.6,"disk_size":"17.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"py-zipkin","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.8,"import_time_s":0.11,"mem_mb":5.6,"disk_size":"18M"}]}}