{"id":3193,"library":"opentelemetry-instrumentation-aiopg","title":"OpenTelemetry aiopg Instrumentation","description":"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.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","instrumentation","database","postgresql","asyncio","aiopg","tracing"],"install":[{"cmd":"pip install opentelemetry-instrumentation-aiopg","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"The core library being instrumented. Required versions are >=0.13.0, <2.0.0.","package":"aiopg","optional":false},{"reason":"Required for OpenTelemetry API calls.","package":"opentelemetry-api","optional":false},{"reason":"Required for OpenTelemetry SDK setup (tracer provider, exporters, etc.).","package":"opentelemetry-sdk","optional":false},{"reason":"Internal dependency for common DB-API instrumentation, typically installed automatically.","package":"opentelemetry-instrumentation-dbapi","optional":false}],"imports":[{"symbol":"AiopgInstrumentor","correct":"from opentelemetry.instrumentation.aiopg import AiopgInstrumentor"}],"quickstart":{"code":"import asyncio\nimport aiopg\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.aiopg import AiopgInstrumentor\nimport os\n\n# Configure OpenTelemetry (replace with your actual exporter/provider setup)\nresource = Resource.create({\"service.name\": \"aiopg-service\"})\nprovider = TracerProvider(resource=resource)\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(span_processor)\ntrace.set_tracer_provider(provider)\n\n# Instrument aiopg\nAiopgInstrumentor().instrument()\n\nasync def fetch_data():\n    dsn = os.environ.get('POSTGRES_DSN', 'dbname=test user=postgres password=password host=localhost')\n    print(f\"Connecting to PostgreSQL with DSN: {dsn}\")\n    async with aiopg.connect(dsn) as conn:\n        async with conn.cursor() as cur:\n            await cur.execute(\"SELECT 1 + 1\")\n            result = await cur.fetchone()\n            print(f\"DB Query Result: {result}\")\n\nasync def main():\n    await fetch_data()\n\nif __name__ == \"__main__\":\n    # Ensure PostgreSQL is running and accessible or configure a dummy DSN for testing\n    # For a real setup, provide POSTGRES_DSN env var, e.g., 'dbname=yourdb user=youruser password=yourpass host=yourhost'\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All beta versions (e.g., 0.x.x) up to 1.0 stable release, as per semantic convention migration plan."},{"fix":"Be prepared for potential minor breaking changes in point releases. Monitor the `opentelemetry-python-contrib` GitHub repository for release notes and issues.","message":"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.","severity":"gotcha","affected_versions":"All versions prior to 1.0.0"},{"fix":"Remove `opentelemetry-instrumentation-aiopg` if `opentelemetry-instrumentation-sqlalchemy` is present and handling database calls.","message":"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.","severity":"gotcha","affected_versions":"All versions when used with SQLAlchemy"},{"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.","message":"Failing to call `AiopgInstrumentor().instrument()` early in your application's lifecycle will result in no automatic tracing of `aiopg` database operations.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<= 0.61b0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}