PyO3 跟踪订阅者

背景

这是什么

pyo3_tracing_subscriber 提供了一个 PyModule，可以添加到上游 pyo3 扩展模块中，以便从 Python 支持配置和初始化 Rust 跟踪订阅者。

这不是什么

• 从您的上游包中导入的任何初始化过的跟踪订阅者 不会 从任何其他 pyo3 扩展模块收集跟踪。换句话说，任何 pyo3 扩展模块都需要分别导出跟踪配置和上下文管理器，而它们又必须分别初始化，以便从相应的 pyo3 扩展模块捕获 Rust 跟踪。
• 目前，仅支持三个跟踪订阅者层
  • tracing_subscriber::fmt，它以人类可读的格式将跟踪写入文件（或 stdout）。
  • opentelemetry-stdout，它以 OTLP 格式将跟踪写入文件（或 stdout）。仅在 layer-otel-otlp-file 功能可用。
  • opentelemetry-otlp，它将跟踪发送到 OpenTelemetry OTLP 终端点。仅在 layer-otel-otlp 功能可用。
• 这不会从 Python 将 OpenTelemetry 上下文传播到 Rust（或反之亦然）。使用 pyo3-opentelemetry 包来实现该功能。

用法

有关完整功能的示例，请参阅此包仓库中的 examples/pyo3-opentelemetry-lib/src/lib.rs 示例。

假设有一个名为 "my_module" 的 pyo3 扩展模块，它希望从 "my_module._tracing_subscriber" 中公开跟踪订阅者配置和上下文管理器类，从 Rust

use pyo3::prelude::*;

#[pymodule]
fn my_module(py: Python, m: &PyModule) -> PyResult<()> {
    // Add your own Python classes, functions and modules.

    let tracing_subscriber = PyModule::new(py, "_tracing_subscriber")?;
    pyo3_tracing_subscriber::add_submodule(
        "my_module._tracing_subscriber",
        py,
        tracing_subscriber,
    )?;
    m.add_submodule(tracing_subscriber)?;
    Ok(())
}

然后用户可以从 Python 初始化一个将日志记录到 stdout 的跟踪订阅者

import my_module
from my_module._tracing_subscriber import (
    GlobalTracingConfig,
    SimpleConfig,
    Tracing,
    subscriber,
)
from pyo3_opentelemetry_lib._tracing_subscriber.layers import file


def main():
    tracing_configuration = GlobalTracingConfig(
        export_process=SimpleConfig(
            subscriber=subscriber.Config(
                layer=file.Config()
            )
        )
    )
    with Tracing(config=config):
        result = my_module.example_function()
        my_module.other_example_function(result)

if __name__ == '__main__':
    main()

构建 Python 模拟文件

此包提供了一个方便的方法，使用 stubs 功能将模拟文件添加到您的 Python 源代码中。

给定一个名为 "my_module" 的 pyo3 扩展模块，该模块使用 pyo3-tracing-subscriber crate 来公开来自 "my_module._tracing_subscriber" 的跟踪订阅者配置和上下文管理器类，在上游 build.rs 文件中

use pyo3_tracing_subscriber_stubs::write_stub_files;

fn main() {
    let target_dir = std::path::Path::new("./my_module/_tracing_subscriber");
    std::fs::remove_dir_all(target_dir).unwrap();
    write_stub_files(
        "my_module",
        "_tracing_subscriber",
        target_dir,
        true, // layer_otel_otlp_file feature enabled
        true, // layer_otel_otlp feature enabled
    )
    .unwrap();
}