aiotrace 0.1.0

OpenTelemetry-native async context propagation for asyncio

aiotrace – Async context propagation for OpenTelemetry

Fixes OpenTelemetry context propagation across asyncio boundaries: create_task, Queue, Lock, Event, Semaphore, TaskGroup, and run_in_executor (thread pool).

Problem

OpenTelemetry stores the current span in a contextvars.ContextVar. When asyncio tasks are created or resumed, Python copies/shallow-copies these contextvars. On Python < 3.9.17 / 3.10.7 / 3.11.1, Task.__step does not restore the task's own context, causing:

• Spans created in child tasks appearing under the wrong parent
• Context leaking between producer/consumer queues
• Lost context when using run_in_executor (threads)

Quick Start

import asyncio
from opentelemetry import trace
from aiotrace import install

install()

tracer = trace.get_tracer(__name__)

async def child():
    with tracer.start_as_current_span("child"):
        pass

async def main():
    with tracer.start_as_current_span("parent"):
        await asyncio.create_task(child())

asyncio.run(main())

Manual Usage (no monkey-patching)

from aiotrace import create_task_with_context, PropagatingQueue

# Use explicit wrapper instead of monkey-patch
task = create_task_with_context(some_coro())

# Explicit propagating queue
queue = PropagatingQueue()
await queue.put(item)
item = await queue.get()

Installation

pip install aiotrace

What Gets Patched

Primitive	Replacement	Description
asyncio.create_task	Wrapped	Captures OTEL context at task creation, restores inside child
asyncio.Queue	PropagatingQueue	Re-attaches context after get()/put() resume
asyncio.Lock	PropagatingLock	Re-attaches context after acquire()
asyncio.Event	PropagatingEvent	Re-attaches context after wait()
asyncio.Semaphore	PropagatingSemaphore	Re-attaches context after acquire()
asyncio.Condition	PropagatingCondition	Re-attaches context after wait()
asyncio.TaskGroup (3.11+)	PropagatingTaskGroup	Captures context at create_task()

API

install(patch_queue=True, patch_locks=True)

Monkey-patches asyncio primitives. Safe to call multiple times (idempotent).

uninstall()

Restores original asyncio primitives.

PropagatingQueue(maxsize=0)

Drop-in replacement for asyncio.Queue with context propagation.

PropagatingLock, PropagatingEvent, PropagatingSemaphore, PropagatingCondition

Drop-in replacements for synchronization primitives.

create_task_with_context(coro, *, name=None, otel_ctx=None)

Create a task with explicit OTEL context propagation.

run_in_executor_with_context(executor, func, *args)

Schedule a function in a thread pool with OTEL context.

Requirements

• Python 3.8–3.12
• opentelemetry-api >= 1.20.0

License

MIT