OpenTelemetry Threading Instrumentation

Warnings

• gotcha This 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]
  Fix: Ensure `opentelemetry.sdk.trace.TracerProvider` is configured and active, and use other instrumentations (e.g., `requests`, `flask`) or manual tracing to generate spans.
• breaking Directly 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]
  Fix: Always use `my_thread.start()` to begin thread execution after creating a `threading.Thread` instance. Avoid calling the `run()` method directly.
• gotcha This 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.
  Fix: Pin 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.
• gotcha While 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]
  Fix: If 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`.

Install

• pip install opentelemetry-instrumentation-threading opentelemetry-sdk opentelemetry-exporter-console Install package and core OTel components

Imports

• ThreadingInstrumentor

  from opentelemetry.instrumentation.threading import ThreadingInstrumentor

Quickstart

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()