OpenTelemetry aiopg Instrumentation

0.62b0 · active · verified Sat Apr 11

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.

Warnings

breaking OpenTelemetry 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.
gotcha The `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.
gotcha If 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.
gotcha Failing 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.
gotcha While 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.

Install

pip install opentelemetry-instrumentation-aiopg Install latest version

Imports

AiopgInstrumentor

from opentelemetry.instrumentation.aiopg import AiopgInstrumentor

Quickstart

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())

view raw JSON →