py_zipkin 使用文档

py_zipkin 使用文档

1. 项目的目录结构及介绍

py_zipkin 是一个用于在 Python 应用程序中实现 Zipkin 追踪的库。以下是 py_zipkin 项目的目录结构及其介绍：

py_zipkin/
├── __init__.py
├── logging_helper.py
├── transport.py
├── zipkin.py
├── encoding/
│   ├── __init__.py
│   ├── v1.py
│   ├── v2.py
├── testing/
│   ├── __init__.py
│   ├── test_logging_helper.py
│   ├── test_transport.py
│   ├── test_zipkin.py
│   ├── test_encoding/
│       ├── __init__.py
│       ├── test_v1.py
│       ├── test_v2.py

• __init__.py: 初始化文件，定义了包的入口点。
• logging_helper.py: 包含与日志记录相关的辅助函数。
• transport.py: 定义了传输 Zipkin 追踪数据的方法。
• zipkin.py: 核心文件，包含 Zipkin 追踪的主要逻辑。
• encoding/: 包含不同版本的 Zipkin 编码实现。
  • v1.py: Zipkin V1 编码实现。
  • v2.py: Zipkin V2 编码实现。
• testing/: 包含测试文件和测试辅助工具。
  • test_logging_helper.py: 测试 logging_helper.py 的单元测试。
  • test_transport.py: 测试 transport.py 的单元测试。
  • test_zipkin.py: 测试 zipkin.py 的单元测试。
  • test_encoding/: 包含编码相关的单元测试。
    • test_v1.py: 测试 Zipkin V1 编码的单元测试。
    • test_v2.py: 测试 Zipkin V2 编码的单元测试。

2. 项目的启动文件介绍

py_zipkin 库本身是一个用于集成到现有 Python 应用程序中的库，因此它没有传统的“启动文件”。相反，你需要在你的应用程序中导入并使用 py_zipkin 的相关模块来实现追踪功能。

以下是一个简单的示例，展示如何在你的应用程序中使用 py_zipkin：

from py_zipkin.zipkin import zipkin_span
from py_zipkin.transport import SimpleHTTPTransport

def my_function():
    with zipkin_span(
        service_name='my_service',
        span_name='my_function',
        transport_handler=SimpleHTTPTransport('http://localhost:9411/api/v2/spans'),
        sample_rate=100.0,
    ):
        # 你的业务逻辑代码
        pass

if __name__ == '__main__':
    my_function()

在这个示例中，zipkin_span 是一个上下文管理器，用于在函数调用期间创建 Zipkin 追踪 span。你需要提供服务名称、span 名称、传输处理程序和采样率等参数。

3. 项目的配置文件介绍

py_zipkin 库没有专门的配置文件，因为它主要通过代码进行配置。你需要在代码中指定 Zipkin 服务器的地址、服务名称、span 名称、传输处理程序和采样率等参数。

以下是一个配置示例：

from py_zipkin.transport import SimpleHTTPTransport

ZIPKIN_SERVER_URL = 'http://localhost:9411/api/v2/spans'
SERVICE_NAME = 'my_service'
SAMPLE_RATE = 100.0  # 采样率，100.0 表示全部采样

transport_handler = SimpleHTTPTransport(ZIPKIN_SERVER_URL)

在这个示例中，我们定义了 Zipkin 服务器的 URL、服务名称和采样率，并在创建 zipkin_span 时使用这些配置。

通过这种方式，你可以在你的应用程序中灵活地配置和使用 py_zipkin 库来实现 Zipkin 追踪功能。