Registry /
observability / opentelemetry-instrumentation-threading
This library provides instrumentation for Python's built-in `threading` module, ensuring that OpenTelemetry trace context is correctly propagated across threads. It does not produce telemetry data on its own but facilitates the linking of spans across different threads. Currently in beta (version 0.61b0), it is part of the `opentelemetry-python-contrib` project, which maintains a frequent release cadence.
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
build_error
glibcpy 3.10–3.925 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ThreadingInstrumentor
✓ from opentelemetry.instrumentation.threading import ThreadingInstrumentor
This quickstart demonstrates how to initialize OpenTelemetry with console export, then apply the `ThreadingInstrumentor`. A parent span is created in the main thread, and a child span is created within a function executed by `threading.Thread`. The instrumentation ensures that the child span correctly references the parent span, illustrating proper context propagation across thread boundaries.
import threading
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.threading import ThreadingInstrumentor
# 1. Set up OpenTelemetry TracerProvider
resource = Resource.create({"service.name": "my-threaded-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument the threading module
ThreadingInstrumentor().instrument()
tracer = trace.get_tracer(__name__)
def threaded_task():
"A function to be run in a separate thread."
with tracer.start_as_current_span("child-thread-span") as child_span:
print(f"Inside threaded_task. Active span: {child_span.context.span_id:x}")
# Simulate work
import time
time.sleep(0.1)
if __name__ == "__main__":
with tracer.start_as_current_span("main-thread-span") as parent_span:
print(f"Main thread. Active span: {parent_span.context.span_id:x}")
my_thread = threading.Thread(target=threaded_task)
my_thread.start()
my_thread.join()
print("Application finished.")
# Ensure all spans are exported before exiting
provider.shutdown()
Debug
Known issues
gotchaThis instrumentation only handles context propagation for `threading.Thread`. It does NOT automatically create spans or metrics. You must still configure a `TracerProvider` and create spans (either manually or via other instrumentations) to see any telemetry data. [5]fixEnsure `opentelemetry.sdk.trace.TracerProvider` is configured and active, and use other instrumentations (e.g., `requests`, `flask`) or manual tracing to generate spans.
affects: All versions
breakingDirectly calling `Thread.run()` instead of `Thread.start()` after instrumentation can lead to an `AttributeError` (e.g., `AttributeError: 'Thread' object has no attribute '_otel_context'`) and broken context propagation. [4]fixAlways use `my_thread.start()` to begin thread execution after creating a `threading.Thread` instance. Avoid calling the `run()` method directly.
affects: 0.60b1 and potentially subsequent beta versions
gotchaThis library is currently in beta (`0.61b0`). Beta packages may have unstable APIs, and breaking changes can occur between minor versions. Always consult release notes when upgrading.fixPin your dependency to a specific beta version (e.g., `opentelemetry-instrumentation-threading==0.61b0`) and carefully review the `CHANGELOG` before upgrading to a new beta release.
affects: All beta versions (e.g., 0.x.x.bY)
gotchaWhile this instrumentation aims to solve context propagation, complex multi-threading patterns (especially with `concurrent.futures.ThreadPoolExecutor` in older Python versions or custom thread pool implementations) might still experience broken context. Python 3.12+ `contextvars` improve `threading.Thread` propagation, but explicit context management might still be needed in some edge cases. [1, 6]fixIf traces appear broken, debug context propagation. Tools like `opentelemetry.context.get_current()` and `opentelemetry.context.attach()` can be used for manual context management in problematic areas, though this instrumentation aims to automate it for `threading.Thread`.
affects: All versions
breakingAttempting to install a non-existent or incorrectly named OpenTelemetry package, such as `opentelemetry-exporter-console`, will result in `pip` installation errors (e.g., `No matching distribution found`). The console exporter is typically provided directly by the `opentelemetry-sdk` and is not a separate PyPI package.fixReview your `pip` install commands and `requirements.txt` to ensure all OpenTelemetry packages are correctly named and available on PyPI. For console output, utilize the `ConsoleSpanExporter` class directly from `opentelemetry.sdk.trace.export` instead of trying to install a dedicated `opentelemetry-exporter-console` package.
affects: All versions
gotchaThe test environment failed to find or install `opentelemetry-exporter-console`. This package is frequently used for demonstrating or testing OpenTelemetry functionality, and its absence can prevent tests from executing or telemetry data from being exported and observed.fixEnsure that `opentelemetry-exporter-console` is correctly specified in the test environment's `requirements.txt` or explicitly installed. Verify that the Python version and environment (e.g., Alpine Linux) are compatible with available distributions of the exporter, providing necessary build tools or using a Python version with pre-built wheels if applicable.
affects: All versions
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for tracing context.
opentelemetry-instrumentationrequiredBase classes for OpenTelemetry instrumentations.
wraptrequiredUsed for function wrapping and patching.
opentelemetry-sdkoptionalRequired to set up a TracerProvider and exporters for telemetry, though not a direct PyPI dependency of the instrumentation itself.