Crate pyo3_tracing_subscriber

This crate provides utilities for configuring and initializing a tracing subscriber from Python. Because Rust pyo3-based Python packages are binaries, these utilities are exposed as a pyo3::types::PyModule which can then be added to upstream pyo3 libraries.

Features

• pyo3 - enables the Python bindings for the tracing subscriber. This feature is enabled by default.
• extension-module - enables the Python extension module for the tracing subscriber. This feature is enabled by default.
• layer-otel-otlp-file - exports trace data with opentelemetry-stdout. See crate::layers::otel_otlp_file.
• layer-otel-otlp - exports trace data with opentelemetry-otlp. See crate::layers::otel_otlp.
• stubs - supports writing stub files in your Python source code from your Rust build scripts. See crates::stubs. This should only be used in build scripts with default features disabled.

Requirements and Limitations

• The tracing subscribers initialized and configured only capture tracing data for the pyo3 library which adds the pyo3-tracing-subscriber module. Separate Python libraries require separate bootstrapping.
• Python users can initialize tracing subscribers using context managers either globally, in which case they can only initialize once, or per-thread, which is incompatible with Python async/await.
• The OTel OTLP layer requires a heuristic based timeout upon context manager exit to ensure trace data on the Rust side is flushed to the OTLP collector. This issue currently persists despite calls to force_flush on the opentelemetry_sdk::trace::TracerProvider and opentelemetry::global::shutdown_tracer_provider.

Examples

use pyo3::prelude::*;
use tracing::instrument;

const MY_PACKAGE_NAME: &str = "example";
const TRACING_SUBSCRIBER_SUBMODULE_NAME: &str = "tracing_subscriber";

#[pymodule]
fn example(py: Python, m: &PyModule) -> PyResult<()> {
    // add your functions, modules, and classes
    pyo3_tracing_subscriber::add_submodule(
        MY_PACKAGE_NAME,
        TRACING_SUBSCRIBER_SUBMODULE_NAME,
        py,
        m,
    )?;
    Ok(())
}

Then in Python:

import asyncio
from example.tracing_subscriber import Tracing


async main():
    async with Tracing():
      
     # do stuff
        pass


if __name__ == "__main__":
    asyncio.run(main())

Related Crates

• pyo3-opentelemetry - propagates OpenTelemetry contexts from Python into Rust.

Macros

create_init_submodule

A macro for initializing a submodule.

py_wrap_error

A macro for wrapping a Rust error as a type error. Implements [ToPythonError].

wrap_error

A macro for wrapping a Rust error.

Structs

Tracing

A Python class that implements the context manager interface. It is initialized with a configuration. Upon entry it builds and installs the configured tracing subscriber. Upon exit it shuts down the tracing subscriber.

Functions

add_submodule

Add the tracing submodule to the given module. This will add the submodule to the sys.modules dictionary so that it can be imported from Python.