opentelemetry-instrumentation-asyncpg

What it is and what it does

This package integrates asyncpg, an async PostgreSQL driver, with OpenTelemetry's distributed tracing framework. When installed and initialized, it automatically wraps asyncpg database calls to emit spans containing query details, execution time, and connection metadata. These spans flow into your OpenTelemetry collector pipeline, enabling centralized observability of database activity across microservices.

The instrumentation is designed to be lightweight and non-intrusive: it hooks into asyncpg at import time and requires only a single initialization call. It depends on three core OpenTelemetry packages (api, instrumentation, and semantic-conventions) and is currently in beta, meaning the API may evolve but the core functionality is stable enough for production use in applications that can tolerate minor version changes.

Use it for:

• Trace slow PostgreSQL queries in async Python services to identify bottlenecks.
• Correlate database queries with HTTP requests and other spans in a distributed system.
• Export asyncpg activity to observability platforms (Jaeger, Datadog, etc.) for centralized monitoring.
• Debug connection pool exhaustion and query timing issues in high-concurrency async applications.
• Build service dependency maps by analyzing which services query which databases.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds distributed tracing to PostgreSQL queries executed via the asyncpg library, capturing query details and timing as OpenTelemetry spans.

Yes, if you run asyncpg in a service that already uses OpenTelemetry or are building observability infrastructure. The low install friction, active maintenance, and zero known vulnerabilities make it safe to adopt. Beta status is not a blocker—it reflects the project's maturity model, not instability. Skip it if you have no observability pipeline or don't need query-level tracing.

Install

opentelemetry-instrumentation-asyncpg on PyPI

pip install opentelemetry-instrumentation-asyncpg

uv add opentelemetry-instrumentation-asyncpg

poetry add opentelemetry-instrumentation-asyncpg

Installing opentelemetry-instrumentation-asyncpg

Before you install

Low friction: pure Python wheel with three lightweight OpenTelemetry dependencies. Actively maintained with a recent release (29 days old) and steady commit activity. Beta status reflects ongoing development but no known stability issues.

License in practice

Apache-2.0 permissive license allows use in most commercial and open-source projects with minimal restrictions; attribution required.

Quickstart

pip install opentelemetry-instrumentation-asyncpg

from opentelemetry.instrumentation.asyncpg import AsyncPGInstrumentor

AsyncPGInstrumentor().instrument()

Requires Python 3.10 or later; asyncpg must be installed separately for instrumentation to function.

Verify before relying

• Whether instrumentation works with all asyncpg versions or has specific version constraints.
• Performance overhead of tracing on high-volume query workloads.
• Compatibility with specific OpenTelemetry exporters and backends.

Package facts

Evidence: opentelemetry_instrumentation_asyncpg-0.65b0-py3-none-any.whl

Tags

More Monitoring packages