Registry / observability / opentelemetry-instrumentation-aiopg

opentelemetry-instrumentation-aiopg

JSON →
library0.65b0pypypi✓ verified 23d ago

This library provides OpenTelemetry instrumentation for `aiopg`, an async PostgreSQL adapter for asyncio. It allows for automatic tracing of database operations, generating spans and attributes according to OpenTelemetry semantic conventions. It is part of the broader `opentelemetry-python-contrib` project, currently in a beta development status (version 0.62b0), and receives frequent updates.

pip install opentelemetry-instrumentation-aiopg
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-aiopg
observabilitypythonv0.65b0
Install
2.6s avg
Import
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.7MB
glibc
py 3.103.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.
fix
Consult 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.
fix
Be 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.
fix
Remove `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.
fix
Ensure `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.
fix
Upgrade 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.
Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
3
Resources