Metadata-Version: 2.1
Name: py-zipkin
Version: 1.2.8
Summary: Library for using Zipkin in Python.
Home-page: https://github.com/Yelp/py_zipkin
Author: Yelp, Inc.
Author-email: opensource+py-zipkin@yelp.com
License: Copyright Yelp 2019
Description: [![Build Status](https://travis-ci.org/Yelp/py_zipkin.svg?branch=master)](https://travis-ci.org/Yelp/py_zipkin)
        [![Coverage Status](https://img.shields.io/coveralls/Yelp/py_zipkin.svg)](https://coveralls.io/r/Yelp/py_zipkin)
        [![PyPi version](https://img.shields.io/pypi/v/py_zipkin.svg)](https://pypi.python.org/pypi/py_zipkin/)
        [![Supported Python versions](https://img.shields.io/pypi/pyversions/py_zipkin.svg)](https://pypi.python.org/pypi/py_zipkin/)
        
        py_zipkin
        ---------
        
        py_zipkin provides a context manager/decorator along with some utilities to
        facilitate the usage of Zipkin in Python applications.
        
        Install
        -------
        
        ```
        pip install py_zipkin
        ```
        
        Usage
        -----
        
        py_zipkin requires a `transport_handler` object that handles logging zipkin
        messages to a central logging service such as kafka or scribe.
        
        `py_zipkin.zipkin.zipkin_span` is the main tool for starting zipkin traces or
        logging spans inside an ongoing trace. zipkin_span can be used as a context
        manager or a decorator.
        
        #### Usage #1: Start a trace with a given sampling rate
        
        ```python
        from py_zipkin.zipkin import zipkin_span
        
        def some_function(a, b):
            with zipkin_span(
                service_name='my_service',
                span_name='my_span_name',
                transport_handler=some_handler,
                port=42,
                sample_rate=0.05, # Value between 0.0 and 100.0
            ):
                do_stuff(a, b)
        ```
        
        #### Usage #2: Trace a service call
        
        The difference between this and Usage #1 is that the zipkin_attrs are calculated
        separately and passed in, thus negating the need of the sample_rate param.
        
        ```python
        # Define a pyramid tween
        def tween(request):
            zipkin_attrs = some_zipkin_attr_creator(request)
            with zipkin_span(
                service_name='my_service',
                span_name='my_span_name',
                zipkin_attrs=zipkin_attrs,
                transport_handler=some_handler,
                port=22,
            ) as zipkin_context:
                response = handler(request)
                zipkin_context.update_binary_annotations(
                    some_binary_annotations)
                return response
        ```
        
        #### Usage #3: Log a span inside an ongoing trace
        
        This can be also be used inside itself to produce continuously nested spans.
        
        ```python
        @zipkin_span(service_name='my_service', span_name='some_function')
        def some_function(a, b):
            return do_stuff(a, b)
        ```
        
        #### Other utilities
        
        `zipkin_span.update_binary_annotations()` can be used inside a zipkin trace
        to add to the existing set of binary annotations.
        
        ```python
        def some_function(a, b):
            with zipkin_span(
                service_name='my_service',
                span_name='some_function',
                transport_handler=some_handler,
                port=42,
                sample_rate=0.05,
            ) as zipkin_context:
                result = do_stuff(a, b)
                zipkin_context.update_binary_annotations({'result': result})
        ```
        
        `zipkin_span.add_sa_binary_annotation()` can be used to add a binary annotation
        to the current span with the key 'sa'. This function allows the user to specify the
        destination address of the service being called (useful if the destination doesn't
        support zipkin). See http://zipkin.io/pages/data_model.html for more information on the
        'sa' binary annotation.
        
        > NOTE: the V2 span format only support 1 "sa" endpoint (represented by remoteEndpoint)
        > so `add_sa_binary_annotation` now raises `ValueError` if you try to set multiple "sa"
        > annotations for the same span.
        
        ```python
        def some_function():
            with zipkin_span(
                service_name='my_service',
                span_name='some_function',
                transport_handler=some_handler,
                port=42,
                sample_rate=0.05,
            ) as zipkin_context:
                make_call_to_non_instrumented_service()
                zipkin_context.add_sa_binary_annotation(
                    port=123,
                    service_name='non_instrumented_service',
                    host='12.34.56.78',
                )
        ```
        
        `create_http_headers_for_new_span()` creates a set of HTTP headers that can be forwarded
        in a request to another service.
        
        ```python
        headers = {}
        headers.update(create_http_headers_for_new_span())
        http_client.get(
            path='some_url',
            headers=headers,
        )
        ```
        
        Transport
        ---------
        
        py_zipkin (for the moment) thrift-encodes spans. The actual transport layer is
        pluggable, though.
        
        The recommended way to implement a new transport handler is to subclass
        `py_zipkin.transport.BaseTransportHandler` and implement the `send` and
        `get_max_payload_bytes` methods.
        
        `send` receives an already encoded thrift list as argument.
        `get_max_payload_bytes` should return the maximum payload size supported by your
        transport, or `None` if you can send arbitrarily big messages.
        
        The simplest way to get spans to the collector is via HTTP POST. Here's an
        example of a simple HTTP transport using the `requests` library. This assumes
        your Zipkin collector is running at localhost:9411.
        
        > NOTE: older versions of py_zipkin suggested implementing the transport handler
        > as a function with a single argument. That's still supported and should work
        > with the current py_zipkin version, but it's deprecated.
        
        ```python
        import requests
        
        from py_zipkin.transport import BaseTransportHandler
        
        
        class HttpTransport(BaseTransportHandler):
        
            def get_max_payload_bytes(self):
                return None
        
            def send(self, encoded_span):
                # The collector expects a thrift-encoded list of spans.
                requests.post(
                    'http://localhost:9411/api/v1/spans',
                    data=encoded_span,
                    headers={'Content-Type': 'application/x-thrift'},
                )
        ```
        
        If you have the ability to send spans over Kafka (more like what you might do
        in production), you'd do something like the following, using the
        [kafka-python](https://pypi.python.org/pypi/kafka-python) package:
        
        ```python
        from kafka import SimpleProducer, KafkaClient
        
        from py_zipkin.transport import BaseTransportHandler
        
        
        class KafkaTransport(BaseTransportHandler):
        
            def get_max_payload_bytes(self):
                # By default Kafka rejects messages bigger than 1000012 bytes.
                return 1000012
        
            def send(self, message):
                kafka_client = KafkaClient('{}:{}'.format('localhost', 9092))
                producer = SimpleProducer(kafka_client)
                producer.send_messages('kafka_topic_name', message)
        ```
        
        Using in multithreading environments
        ------------------------------------
        
        If you want to use py_zipkin in a cooperative multithreading environment,
        e.g. asyncio, you need to explicitly pass an instance of `py_zipkin.storage.Stack`
        as parameter `context_stack` for `zipkin_span` and `create_http_headers_for_new_span`.
        By default, py_zipkin uses a thread local storage for the attributes, which is
        defined in `py_zipkin.storage.ThreadLocalStack`.
        
        Additionally, you'll also need to explicitly pass an instance of
        `py_zipkin.storage.SpanStorage` as parameter `span_storage` to `zipkin_span`.
        
        ```python
        from py_zipkin.zipkin import zipkin_span
        from py_zipkin.storage import Stack
        from py_zipkin.storage import SpanStorage
        
        
        def my_function():
            context_stack = Stack()
            span_storage = SpanStorage()
            await my_function(context_stack, span_storage)
        
        async def my_function(context_stack, span_storage):
            with zipkin_span(
                service_name='my_service',
                span_name='some_function',
                transport_handler=some_handler,
                port=42,
                sample_rate=0.05,
                context_stack=context_stack,
                span_storage=span_storage,
            ):
                result = do_stuff(a, b)
        ```
        
        
        Firehose mode [EXPERIMENTAL]
        ----------------------------
        
        "Firehose mode" records 100% of the spans, regardless of
        sampling rate. This is useful if you want to treat these spans
        differently, e.g. send them to a different backend that has limited
        retention. It works in tandem with normal operation, however there may
        be additional overhead. In order to use this, you add a
        `firehose_handler` just like you add a `transport_handler`.
        
        This feature should be considered experimental and may be removed at
        any time without warning. If you do use this, be sure to send
        asynchronously to avoid excess overhead for every request.
        
        
        License
        -------
        
        Copyright (c) 2018, Yelp, Inc. All Rights reserved. Apache v2
        
        1.2.8 (2023-03-23)
        -------------------
        - Add back exports in py_zipkin.encoding
        - Fix mypy tests
        
        1.2.7 (2023-02-06)
        -------------------
        - Drop support for Python 3.6
        
        1.2.6 (2023-02-06)
        -------------------
        - Drop support for V1_THRIFT encoding
        
        1.0.0 (2022-06-09)
        -------------------
        - Droop Python 2.7 support (minimal supported python version is 3.5)
        - Recompile protobuf using version 3.19
        
        0.21.0 (2021-03-17)
        -------------------
        - The default encoding is now V2 JSON. If you want to keep the old
          V1 thrift encoding you'll need to specify it.
        
        0.20.2 (2021-03-11)
        -------------------
        - Don't crash when annotating exceptions that cannot be str()'d
        
        0.20.1 (2020-10-27)
        -------------------
        - Support PRODUCER and CONSUMER spans
        
        0.20.0 (2020-03-09)
        -------------------
        - Add create_http_headers helper
        
        0.19.0 (2020-02-28)
        -------------------
        - Add zipkin_span.add_annotation() method
        - Add autoinstrumentation for python Threads
        - Allow creating a copy of Tracer
        - Add extract_zipkin_attrs_from_headers() helper
        
        0.18.7 (2020-01-15)
        -------------------
        - Expose encoding.create_endpoint helper
        
        0.18.6 (2019-09-23)
        -------------------
        - Ensure tags are strings when using V2_JSON encoding
        
        0.18.5 (2019-08-08)
        -------------------
        - Add testing.MockTransportHandler module
        
        0.18.4 (2019-08-02)
        -------------------
        - Fix thriftpy2 import to allow cython module
        
        0.18.3 (2019-05-15)
        -------------------
        - Fix unicode bug when decoding thrift tag strings
        
        0.18.2 (2019-03-26)
        -------------------
        - Handled exception while emitting trace and log the error
        - Ensure tracer is cleared regardless span of emit outcome
        
        0.18.1 (2019-02-22)
        -------------------
        - Fix ThreadLocalStack() bug introduced in 0.18.0
        
        0.18.0 (2019-02-13)
        -------------------
        - Fix multithreading issues
        - Added Tracer module
        
        0.17.1 (2019-02-05)
        -------------------
        - Ignore transport_handler overrides in an inner span since that causes
          spans to be dropped.
        
        0.17.0 (2019-01-25)
        -------------------
        - Support python 3.7
        - py-zipkin now depends on thriftpy2 rather than thriftpy. They
          can coexist in the same codebase, so it should be safe to upgrade.
        
        0.16.1 (2018-11-16)
        -------------------
        - Handle null timestamps when decoding thrift traces
        
        0.16.0 (2018-11-13)
        -------------------
        - py_zipkin is now able to convert V1 thrift spans to V2 JSON
        
        0.15.1 (2018-10-31)
        -------------------
        - Changed DeprecationWarnings to logging.warning
        
        0.15.0 (2018-10-22)
        -------------------
        - Added support for V2 JSON encoding.
        - Fixed TransportHandler bug that was affecting also V1 JSON.
        
        0.14.1 (2018-10-09)
        -------------------
        - Fixed memory leak introduced in 0.13.0.
        
        0.14.0 (2018-10-01)
        -------------------
        - Support JSON encoding for V1 spans.
        - Allow overriding the span_name after creation.
        
        0.13.0 (2018-06-25)
        -------------------
        - Removed deprecated `zipkin_logger.debug()` interface.
        - `py_zipkin.stack` was renamed as `py_zipkin.storage`. If you were
          importing this module, you'll need to update your code.
        
        0.12.0 (2018-05-29)
        -------------------
        - Support max payload size for transport handlers.
        - Transport handlers should now be implemented as classes
          extending py_zipkin.transport.BaseTransportHandler.
        
        0.11.2 (2018-05-23)
        -------------------
        - Don't overwrite passed in annotations
        
        0.11.1 (2018-05-23)
        -------------------
        - Add binary annotations to the span even if the request is not being
          sampled. This fixes binary annotations for firehose spans.
        
        0.11.0 (2018-02-08)
        -------------------
        - Add support for "firehose mode", which logs 100% of the spans
          regardless of sample rate.
        
        0.10.1 (2018-02-05)
        -------------------
        - context_stack will now default to `ThreadLocalStack()` if passed as
          `None`
        
        0.10.0 (2018-02-05)
        -------------------
        - Add support for using explicit in-process context storage instead of
          using thread_local. This allows you to use py_zipkin in cooperative
          multitasking environments e.g. asyncio
        - `py_zipkin.thread_local` is now deprecated. Instead use
          `py_zipkin.stack.ThreadLocalStack()`
        - TraceId and SpanId generation performance improvements.
        - 128-bit TraceIds now start with an epoch timestamp to support easy
          interop with AWS X-Ray
        
        0.9.0 (2017-07-31)
        ------------------
        - Add batch span sending. Note that spans are now sent in lists.
        
        0.8.3 (2017-07-10)
        ------------------
        - Be defensive about having logging handlers configured to avoid throwing
          NullHandler attribute errors
        
        0.8.2 (2017-06-30)
        ------------------
        - Don't log ss and sr annotations when in a client span context
        - Add error binary annotation if an exception occurs
        
        0.8.1 (2017-06-16)
        ------------------
        - Fixed server send timing to more accurately reflect when server send
          actually occurs.
        - Replaced logging_start annotation with logging_end
        
        0.8.0 (2017-06-01)
        ------------------
        - Added 128-bit trace id support
        - Added ability to explicitly specify host for a span
        - Added exception handling if host can't be determined automatically
        - SERVER_ADDR ('sa') binary annotations can be added to spans
        - py36 support
        
        0.7.1 (2017-05-01)
        ------------------
        - Fixed a bug where `update_binary_annotations` would fail for a child
          span in a trace that is not being sampled
        
        0.7.0 (2017-03-06)
        ------------------
        - Simplify `update_binary_annotations` for both root and non-root spans
        
        0.6.0 (2017-02-03)
        ------------------
        - Added support for forcing `zipkin_span` to report timestamp/duration.
          Changes API of `zipkin_span`, but defaults back to existing behavior.
        
        0.5.0 (2017-02-01)
        ------------------
        - Properly set timestamp/duration on server and local spans
        - Updated thrift spec to include these new fields
        - The `zipkin_span` entrypoint should be backwards compatible
        
        0.4.4 (2016-11-29)
        ------------------
        - Add optional annotation for when Zipkin logging starts
        
        0.4.3 (2016-11-04)
        ------------------
        - Fix bug in zipkin_span decorator
        
        0.4.2 (2016-11-01)
        ------------------
        - Be defensive about transport_handler when logging spans.
        
        0.4.1 (2016-10-24)
        ------------------
        - Add ability to override span_id when creating new ZipkinAttrs.
        
        0.4.0 (2016-10-20)
        ------------------
        - Added `start` and `stop` functions as friendlier versions of the
          __enter__ and __exit__ functions.
        
        0.3.1 (2016-09-30)
        ------------------
        - Adds new param to thrift.create_endpoint allowing creation of
          thrift Endpoint objects on a proxy machine representing another
          host.
        
        0.2.1 (2016-09-30)
        ------------------
        - Officially "release" v0.2.0. Accidentally pushed a v0.2.0 without
          the proper version bump, so v0.2.1 is the new real version. Please
          use this instead of v0.2.0.
        
        0.2.0 (2016-09-30)
        ------------------
        - Fix problem where if zipkin_attrs and sample_rate were passed, but
          zipkin_attrs.is_sampled=True, new zipkin_attrs were being generated.
        
        0.1.2 (2016-09-29)
        ------------------
        - Fix sampling algorithm that always sampled for rates > 50%
        
        0.1.1 (2016-07-05)
        ------------------
        - First py_zipkin version with context manager/decorator functionality.
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Provides: py_zipkin
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: protobuf