Function pyo3_tracing_subscriber::add_submodule

source · 
pub fn add_submodule(
    fully_qualified_namespace: &str,
    name: &str,
    py: Python<'_>,
    parent_module: &PyModule
) -> PyResult<()>
Expand description

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.

§Arguments

  • fully_qualified_namespace - the fully qualified namespace of the parent Python module to which the tracing submodule should be added. This may be a nested namespace, such as my_package.my_module.
  • name - the name of the tracing subscriber submodule within the specified parent module. This should not be a nested namespace.
  • py - the Python GIL token.
  • parent_module - the parent module to which the tracing subscriber submodule should be added.

§Errors

  • PyErr if the submodule cannot be added.

§Additional Details

This function will add the following:

  • Tracing - a Python context manager which initializes the configured tracing subscriber.
  • GlobalTracingConfig - a Python context manager which sets the configured tracing subscriber as the global default (ie tracing::subscriber::set_global_default). The Tracing context manager can be used only once per process with this configuration.
  • CurrentThreadTracingConfig - a Python context manager which sets the configured tracing subscriber as the current thread default (ie tracing::subscriber::set_default). As the context manager exits, the guard is dropped and the tracing subscriber can be re-initialized with another default. Note, the default tracing subscriber will not capture traces across async/await boundaries that call pyo3_asyncio::tokio::future_into_py.
  • BatchConfig - a Python context manager which configures the tracing subscriber to export trace data in batch. As the Tracing context manager enters, a Tokio runtime is initialized and will run in the background until the context manager exits.
  • SimpleConfig - a Python context manager which configures the tracing subscriber to export trace data in a non-batch manner. This only initializes a Tokio runtime if the underlying layer requires an asynchronous runtime to export trace data (ie the opentelemetry-otlp layer).
  • layers - a submodule which contains different layers to add to the tracing subscriber. Currently supported:
    • tracing::fmt - a layer which exports trace data to stdout in a non-OpenTelemetry data format.
    • opentelemetry-stdout - a layer which exports trace data to stdout (requires the layer-otel-otlp-file feature).
    • opentelemetry-otlp - a layer which exports trace data to an OpenTelemetry collector (requires the layer-otel-otlp feature).
  • subscriber - a submodule which contains utilities for initialing the tracing subscriber with the configured layer. Currently, the tracing subscriber is initialized as tracing::subscriber::Registry::default().with(layer).

The following exceptions are added to the submodule:

  • TracingContextManagerError - raised when the Tracing context manager’s methods are not invoked in the correct order or multiplicity.
  • TracingStartError - raised if the user-specified tracing layer or subscriber fails to build and initialize properly upon context manager entry.
  • TracingShutdownError - raised if the tracing layer or subscriber fails to shutdown properly on context manager exit.

For detailed Python usage documentation, see the stub files written by [pyo3_tracing_subscriber::stubs::write_stub_files].