Registry /
observability / opentelemetry-instrumentation-aiopg
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.000s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AiopgInstrumentor
✓ from opentelemetry.instrumentation.aiopg import AiopgInstrumentor
✗ from opentelemetry.instrumentation.aiopg import AiopgInstrumentor
This quickstart demonstrates how to instrument `aiopg` using `AiopgInstrumentor`. It sets up a basic OpenTelemetry `TracerProvider` with a `ConsoleSpanExporter` and then calls `AiopgInstrumentor().instrument()` to enable automatic tracing. Subsequently, any `aiopg` database operations will generate spans. Remember to replace the `ConsoleSpanExporter` with a proper OTLP exporter for production use and provide a valid PostgreSQL DSN via environment variables or directly.
import asyncio
import aiopg
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.aiopg import AiopgInstrumentor
import os
# Configure OpenTelemetry (replace with your actual exporter/provider setup)
resource = Resource.create({"service.name": "aiopg-service"})
provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)
trace.set_tracer_provider(provider)
# Instrument aiopg
AiopgInstrumentor().instrument()
async def fetch_data():
dsn = os.environ.get('POSTGRES_DSN', 'dbname=test user=postgres password=password host=localhost')
print(f"Connecting to PostgreSQL with DSN: {dsn}")
async with aiopg.connect(dsn) as conn:
async with conn.cursor() as cur:
await cur.execute("SELECT 1 + 1")
result = await cur.fetchone()
print(f"DB Query Result: {result}")
async def main():
await fetch_data()
if __name__ == "__main__":
# Ensure PostgreSQL is running and accessible or configure a dummy DSN for testing
# For a real setup, provide POSTGRES_DSN env var, e.g., 'dbname=yourdb user=youruser password=yourpass host=yourhost'
asyncio.run(main())
Debug
Known issues
breakingOpenTelemetry Python is gradually migrating to stable semantic conventions. This might introduce breaking changes to span attribute names or values, particularly for HTTP-related instrumentations first, then other types, which could affect dashboards or alerts relying on specific attributes.fixConsult the `opentelemetry-python-contrib` CHANGELOG and semantic conventions documentation for updates before upgrading. Adapt your observability queries and dashboards if attribute names change.
affects: All beta versions (e.g., 0.x.x) up to 1.0 stable release, as per semantic convention migration plan.
gotchaThe `opentelemetry-instrumentation-aiopg` library is in beta status (Development Status :: 4 - Beta), meaning its API and produced telemetry are subject to change before a stable 1.0 release.fixBe prepared for potential minor breaking changes in point releases. Monitor the `opentelemetry-python-contrib` GitHub repository for release notes and issues.
affects: All versions prior to 1.0.0
gotchaIf you are using SQLAlchemy with aiopg, you should typically instrument SQLAlchemy directly using `opentelemetry-instrumentation-sqlalchemy` and *not* `opentelemetry-instrumentation-aiopg` to avoid duplicate events and incorrect tracing.fixRemove `opentelemetry-instrumentation-aiopg` if `opentelemetry-instrumentation-sqlalchemy` is present and handling database calls.
affects: All versions when used with SQLAlchemy
gotchaFailing to call `AiopgInstrumentor().instrument()` early in your application's lifecycle will result in no automatic tracing of `aiopg` database operations.fixEnsure `AiopgInstrumentor().instrument()` is called before any `aiopg` connections are established or operations are performed. For complex applications, consider OpenTelemetry Python's automatic instrumentation (via `opentelemetry-instrument`) or programmatic instrumentation.
affects: All versions
gotchaWhile a fix was implemented for 'multiple nested spans when aiopg.pool is used' in earlier versions, ensure you are on the latest minor release to benefit from such fixes.fixUpgrade to the latest version of `opentelemetry-instrumentation-aiopg` to ensure all known issues related to span generation, especially with connection pools, are resolved.
affects: <= 0.61b0
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
aiopgrequiredThe core library being instrumented. Required versions are >=0.13.0, <2.0.0.
opentelemetry-apirequiredRequired for OpenTelemetry API calls.
opentelemetry-sdkrequiredRequired for OpenTelemetry SDK setup (tracer provider, exporters, etc.).
opentelemetry-instrumentation-dbapirequiredInternal dependency for common DB-API instrumentation, typically installed automatically.