{"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":"python","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":[{"wrong":"from opentelemetry.instrumentation.aiopg import AiopgInstrumentor","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,"search_vec":"'0.62':52 'accord':29 'adapt':14 'aiopg':2,10,63 'allow':18 'async':12 'asyncio':16,62 'attribut':28 'automat':20 'b0':53 'beta':48 'broader':39 'contrib':43 'convent':33 'current':45 'databas':23,60 'develop':49 'frequent':56 'generat':25 'instrument':3,8,59 'librari':5 'opentelemetri':1,7,31,41,58 'opentelemetry-python-contrib':40 'oper':24 'part':36 'postgresql':13,61 'project':44 'provid':6 'python':42 'receiv':55 'semant':32 'span':26 'status':50 'trace':21,64 'updat':57 'version':51","created_at":"2026-04-11T09:25:00.482240+00:00","updated_at":"2026-04-16T17:39:34.826410+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n  File \"/tmp/tmp1xkvq46a/venv/lib/python3.12/site-packages/opentelemetry/instrumentation/aiopg/__init__.py\", line 69, in <module>\n    from opentelemetry.instrumentation.aiopg import wrappers\n  File \"/tmp/tmp1xkvq46a/venv/lib/p"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.65b0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/open-telemetry/opentelemetry-python-contrib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opentelemetry-instrumentation-aiopg/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-28","next_check":"2026-07-10","install_tag":null}}