py-zipkin 1.2.8

py_zipkin

py_zipkin提供了一个上下文管理器/装饰器以及一些实用工具，以方便在Python应用程序中使用Zipkin。

安装

pip install py_zipkin

使用

py_zipkin需要一个transport_handler对象，该对象处理将zipkin消息记录到中心日志服务（如kafka或scribe）。

py_zipkin.zipkin.zipkin_span是启动zipkin跟踪或在现有跟踪中记录span的主要工具。zipkin_span可以用作上下文管理器或装饰器。

使用 #1：使用给定的采样率启动跟踪

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)

使用 #2：跟踪服务调用

与用法#1的区别在于，zipkin_attrs是单独计算并传递的，因此无需sample_rate参数。

# 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

用法#3：在持续跟踪中记录跨度

这也可以在自身内部使用，以产生连续嵌套的跨度。

@zipkin_span(service_name='my_service', span_name='some_function')
def some_function(a, b):
    return do_stuff(a, b)

其他工具

zipkin_span.update_binary_annotations()可以在zipkin跟踪中用于添加到现有的二进制注释集。

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()可用于向当前跨度添加带有'sa'键的二进制注释。此函数允许用户指定被调用服务的目标地址（如果目标不支持zipkin，则很有用）。有关'sa'二进制注释的更多信息，请参阅http://zipkin.io/pages/data_model.html。

注意：V2跨度格式仅支持1个"sa"端点（由remoteEndpoint表示），因此如果您尝试为同一跨度设置多个"sa"注释，则add_sa_binary_annotation现在将引发ValueError。

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()创建了一组可以转发到其他服务的请求的HTTP头部。

headers = {}
headers.update(create_http_headers_for_new_span())
http_client.get(
    path='some_url',
    headers=headers,
)

传输

py_zipkin（目前）使用thrift编码跨度。实际的传输层是可插拔的。

实现新传输处理器的推荐方法是子类化py_zipkin.transport.BaseTransportHandler并实现send和get_max_payload_bytes方法。

send接收一个已编码的thrift列表作为参数。get_max_payload_bytes应返回您的传输支持的最大有效负载大小，或者如果可以发送任意大的消息，则返回None。

将跨度发送到收集器的最简单方法是通过HTTP POST。以下是一个使用requests库的简单HTTP传输示例。这假设您的Zipkin收集器正在localhost:9411运行。

注意：较旧版本的py_zipkin建议将传输处理器实现为一个具有单个参数的函数。这仍然受支持并且应与当前py_zipkin版本兼容，但现在已弃用。

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'},
        )

如果您有通过Kafka（在生产环境中可能会这样做）发送跨度的能力，可以使用kafka-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)

在多线程环境中使用

如果您想在合作多线程环境中使用py_zipkin，例如asyncio，则需要显式传递py_zipkin.storage.Stack的实例作为zipkin_span和create_http_headers_for_new_span的参数context_stack。默认情况下，py_zipkin使用线程局部存储来存储属性，该存储在py_zipkin.storage.ThreadLocalStack中定义。

此外，您还需要显式传递py_zipkin.storage.SpanStorage的实例作为zipkin_span的参数span_storage。

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模式[实验性]

"Firehose模式"记录100%的跨度，无论采样率如何。如果您想将这些跨度区别对待，例如将它们发送到具有有限保留期的不同后端，则很有用。它与正常操作协同工作，但可能会有额外的开销。为了使用此功能，您需要添加一个firehose_handler，就像添加transport_handler一样。

此功能应被视为实验性的，并且可能随时无警告地删除。如果您使用此功能，请确保异步发送，以避免每个请求的额外开销。

许可证

版权（c）2018，Yelp，Inc。保留所有权利。Apache v2

1.2.8 (2023-03-23)

• 在py_zipkin.encoding中添加回导出
• 修复mypy测试

1.2.7 (2023-02-06)

• 放弃对Python 3.6的支持

1.2.6 (2023-02-06)

• 放弃对V1_THRIFT编码的支持

1.0.0 (2022-06-09)

• 放弃对Python 2.7的支持（最低支持的Python版本是3.5）
• 使用版本3.19重新编译protobuf

0.21.0 (2021-03-17)

• 默认编码现在是V2 JSON。如果您想保留旧的V1 thrift编码，则需要指定它。

0.20.2 (2021-03-11)

• 在注释无法转换为str()的异常时，不要崩溃

0.20.1 (2020-10-27)

• 支持 PRODUCER 和 CONSUMER 范围

0.20.0 (2020-03-09)

• 添加 create_http_headers 辅助函数

0.19.0 (2020-02-28)

• 添加 zipkin_span.add_annotation() 方法
• 为 Python 线程添加自动检测
• 允许创建 Tracer 的副本
• 添加 extract_zipkin_attrs_from_headers() 辅助函数

0.18.7 (2020-01-15)

• 公开 encoding.create_endpoint 辅助函数

0.18.6 (2019-09-23)

• 使用 V2_JSON 编码时确保标签是字符串

0.18.5 (2019-08-08)

• 添加 testing.MockTransportHandler 模块

0.18.4 (2019-08-02)

• 修复 thriftpy2 导入以允许 cython 模块

0.18.3 (2019-05-15)

• 修复解码 thrift 标签字符串时的 unicode 错误

0.18.2 (2019-03-26)

• 在发出跟踪时处理异常并记录错误
• 确保无论发出结果如何，都要清除跟踪器

0.18.1 (2019-02-22)

• 修复 0.18.0 中引入的 ThreadLocalStack() 错误

0.18.0 (2019-02-13)

• 修复多线程问题
• 添加 Tracer 模块

0.17.1 (2019-02-05)

• 在内部范围中忽略 transport_handler 覆盖，因为这会导致范围被丢弃。

0.17.0 (2019-01-25)

• 支持 Python 3.7
• py-zipkin 现在依赖于 thriftpy2 而不是 thriftpy。它们可以在同一代码库中同时存在，因此升级应该是安全的。

0.16.1 (2018-11-16)

• 处理解码 thrift 跟踪时的 null 时间戳

0.16.0 (2018-11-13)

• py_zipkin 现在能够将 V1 thrift 范围转换为 V2 JSON

0.15.1 (2018-10-31)

• 将 DeprecationWarnings 改为 logging.warning

0.15.0 (2018-10-22)

• 添加对 V2 JSON 编码的支持。
• 修复影响 V1 JSON 的 TransportHandler 错误。

0.14.1 (2018-10-09)

• 修复 0.13.0 中引入的内存泄漏。

0.14.0 (2018-10-01)

• 支持 V1 范围的 JSON 编码。
• 允许在创建后覆盖 span_name。

0.13.0 (2018-06-25)

• 删除已过时的 zipkin_logger.debug() 接口。
• py_zipkin.stack 已重命名为 py_zipkin.storage。如果您导入此模块，则需要更新您的代码。

0.12.0 (2018-05-29)

• 支持传输处理器的最大有效载荷大小。
• 现在应将传输处理器实现为扩展 py_zipkin.transport.BaseTransportHandler 的类。

0.11.2 (2018-05-23)

• 不要覆盖传入的注释

0.11.1 (2018-05-23)

• 即使请求没有被采样，也要将二进制注释添加到范围中。这解决了 firehose 范围的二进制注释问题。

0.11.0 (2018-02-08)

• 添加对“firehose 模式”的支持，无论采样率如何，都会记录 100% 的范围。

0.10.1 (2018-02-05)

• 如果传递为 None，则 context_stack 将默认为 ThreadLocalStack()

0.10.0 (2018-02-05)

• 添加对使用显式进程内上下文存储的支持，而不是使用 thread_local。这允许您在协作多任务环境中使用 py_zipkin，例如 asyncio。
• py_zipkin.thread_local 现已弃用。相反，请使用 py_zipkin.stack.ThreadLocalStack()
• 跟踪 Id 和范围 Id 生成性能改进。
• 128 位跟踪 Id 现在以纪元时间戳开头，以支持与 AWS X-Ray 的轻松互操作性。

0.9.0 (2017-07-31)

• 添加批量范围发送。请注意，范围现在以列表的形式发送。

0.8.3 (2017-07-10)

• 在配置了日志处理程序时要谨慎，以避免抛出 NullHandler 属性错误

0.8.2 (2017-06-30)

• 在客户端范围上下文中不要记录 ss 和 sr 注释
• 如果发生异常，添加错误二进制注释

0.8.1 (2017-06-16)

• 修复服务器发送时间，以更准确地反映服务器实际发送的时间
• 用 logging_end 替换 logging_start 注释

0.8.0 (2017-06-01)

• 添加 128 位跟踪 id 支持
• 添加显式指定范围的宿主机的功能
• 如果无法自动确定主机，添加异常处理
• 可以添加 SERVER_ADDR ('sa') 二进制注释到范围中
• py36 支持

0.7.1 (2017-05-01)

• 修复了在未采样的跟踪中的子范围上 update_binary_annotations 失败的 bug

0.7.0 (2017-03-06)

• 简化了根和非根范围的 update_binary_annotations

0.6.0 (2017-02-03)

• 添加了对强制 zipkin_span 报告时间戳/持续时间的支持。更改了 zipkin_span 的 API，但默认回滚到现有行为。

0.5.0 (2017-02-01)

• 正确设置服务器和本地范围的时间戳/持续时间
• 更新 thrift 规范以包含这些新字段
• zipkin_span 入口点应该是向后兼容的

0.4.4 (2016-11-29)

• 添加当 Zipkin 日志开始时的可选注释

0.4.3 (2016-11-04)

• 修复 zipkin_span 装饰器中的错误

0.4.2 (2016-11-01)

• 在记录跨度时对transport_handler保持防御性。

0.4.1 (2016-10-24)

• 增加在创建新的ZipkinAttrs时覆盖span_id的能力。

0.4.0 (2016-10-20)

• 添加了start和stop函数，作为更友好的enter和exit函数版本。

0.3.1 (2016-09-30)

• 为thrift.create_endpoint添加了新参数，允许在代表其他主机的代理机器上创建thrift Endpoint对象。

0.2.1 (2016-09-30)

• 正式发布v0.2.0。不小心推送了一个没有正确版本升级的v0.2.0，所以v0.2.1是新的真实版本。请使用这个版本而不是v0.2.0。

0.2.0 (2016-09-30)

• 修复了当zipkin_attrs和sample_rate被传递，但zipkin_attrs.is_sampled=True时，会生成新的zipkin_attrs的问题。

0.1.2 (2016-09-29)

• 修复了采样算法，该算法总是以大于50%的速率进行采样。

0.1.1 (2016-07-05)

• 是第一个具有上下文管理器和装饰器功能的py_zipkin版本。