OpenTelemetry asyncio Instrumentation

The opentelemetry-instrumentation-asyncio package allows tracing asyncio applications. The metric for coroutine, future, is generated even if there is no setting to generate a span.

Run instrumented application

1. coroutine

# export OTEL_PYTHON_ASYNCIO_COROUTINE_NAMES_TO_TRACE=sleep

import asyncio
from opentelemetry.instrumentation.asyncio import AsyncioInstrumentor

AsyncioInstrumentor().instrument()

async def main():
    await asyncio.create_task(asyncio.sleep(0.1))

asyncio.run(main())

2. future

# export OTEL_PYTHON_ASYNCIO_FUTURE_TRACE_ENABLED=true

import asyncio
from opentelemetry.instrumentation.asyncio import AsyncioInstrumentor

AsyncioInstrumentor().instrument()

loop = asyncio.get_event_loop()

future = asyncio.Future()
future.set_result(1)
task = asyncio.ensure_future(future)
loop.run_until_complete(task)

3. to_thread

# export OTEL_PYTHON_ASYNCIO_TO_THREAD_FUNCTION_NAMES_TO_TRACE=func

import asyncio
from opentelemetry.instrumentation.asyncio import AsyncioInstrumentor

AsyncioInstrumentor().instrument()

async def main():
    await asyncio.to_thread(func)

def func():
    pass

asyncio.run(main())

asyncio metric types

• asyncio.process.duration (seconds) - Duration of asyncio process

• asyncio.process.count (count) - Number of asyncio process

API

class opentelemetry.instrumentation.asyncio.AsyncioInstrumentor(*args, **kwargs)

Bases: BaseInstrumentor

An instrumentor for asyncio

See BaseInstrumentor

methods_with_coroutine = ['create_task', 'ensure_future', 'wait_for', 'wait', 'as_completed', 'run_coroutine_threadsafe']

instrumentation_dependencies()

Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or pyproject.toml.

For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype: Collection[str]

def instrumentation_dependencies(self) -> Collection[str]:

return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.

instrument_method_with_coroutine(method_name)

Instruments specified asyncio method.

instrument_gather()

instrument_to_thread()

Return type:

None

instrument_taskgroup_create_task()

Return type:

None

trace_to_thread(func)

Trace a function, but if already instrumented, skip double-wrapping.

trace_item(coro_or_future)

Trace a coroutine or future item.

async trace_coroutine(coro)

Wrap a coroutine so that we measure its duration, metrics, etc. If already instrumented, simply ‘await coro’ to preserve call behavior.

trace_future(future)

Wrap a Future’s done callback. If already instrumented, skip re-wrapping.

record_process(start, attr, span=None, exception=None)

Record the processing time, update histogram and counter, and handle span.

Parameters:

• start (float) – Start time of the process.

• attr (dict) – Attributes for the histogram and counter.

• span – Optional span for tracing.

• exception – Optional exception occurred during the process.

Return type:

None

opentelemetry.instrumentation.asyncio.determine_state(exception)

Return type:

str

opentelemetry.instrumentation.asyncio.uninstrument_taskgroup_create_task()

Return type:

None

opentelemetry.instrumentation.asyncio.uninstrument_to_thread()

Return type:

None

opentelemetry.instrumentation.asyncio.uninstrument_gather()

Return type:

None

opentelemetry.instrumentation.asyncio.uninstrument_method_with_coroutine(method_name)

Uninstrument specified asyncio method.

Return type:

None

OTEL_PYTHON_ASYNCIO_COROUTINE_NAMES_TO_TRACE

Enter the names of the coroutines to be traced through the environment variable below, separated by commas.

OTEL_PYTHON_ASYNCIO_FUTURE_TRACE_ENABLED

To determine whether the tracing feature for Future of Asyncio in Python is enabled or not.

OTEL_PYTHON_ASYNCIO_TO_THREAD_FUNCTION_NAMES_TO_TRACE

Enter the names of the functions to be traced through the environment variable below, separated by commas.