Registry / observability / opentelemetry-instrumentation-psycopg

opentelemetry-instrumentation-psycopg

JSON →
library0.65b0pypypi✓ verified 23d ago

This library provides OpenTelemetry automatic instrumentation for the `psycopg` (PostgreSQL driver, version 3.x) library, enabling the collection of traces and metrics from database interactions. It is part of the `opentelemetry-python-contrib` repository, with the current version being 0.62b0, and releases typically follow the contrib project's cadence.

pip install opentelemetry-instrumentation-psycopg
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-psycopg
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.

PsycopgInstrumentor
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

This quickstart demonstrates how to instrument `psycopg` globally. It initializes a basic OpenTelemetry setup with a console exporter and then calls `PsycopgInstrumentor().instrument()` to automatically wrap all subsequent `psycopg.connect()` calls and database operations. The example attempts to connect to a PostgreSQL database and execute a simple query, printing any connection errors without halting execution.

import psycopg from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor import os # Configure OpenTelemetry TracerProvider resource = Resource.create({"service.name": "my-psycopg-app"}) tracer_provider = TracerProvider(resource=resource) span_processor = SimpleSpanProcessor(ConsoleSpanExporter()) tracer_provider.add_span_processor(span_processor) trace.set_tracer_provider(tracer_provider) # Instrument psycopg connections globally PsycopgInstrumentor().instrument() # Connect to a dummy database and perform an operation try: # Replace with your actual connection string or environment variables # For demonstration, we'll try a local connection that might fail if no postgres is running db_name = os.environ.get('PG_DB_NAME', 'test_db') db_user = os.environ.get('PG_DB_USER', 'postgres') db_password = os.environ.get('PG_DB_PASSWORD', 'mysecretpassword') db_host = os.environ.get('PG_DB_HOST', 'localhost') # Note: This connection might fail if a PostgreSQL instance isn't available. # The instrumentation will still attempt to trace the 'connect' call. conn = psycopg.connect( host=db_host, user=db_user, password=db_password, dbname=db_name ) cursor = conn.cursor() cursor.execute("SELECT 1;") result = cursor.fetchone() print(f"Database query result: {result}") cursor.close() conn.close() except psycopg.OperationalError as e: print(f"Could not connect to PostgreSQL or execute query: {e}") print("Please ensure a PostgreSQL instance is running and accessible.") print("Psycopg operations (attempted) have been instrumented.")
opentelemetry-instrument --version
Debug
Known issues
gotchaAs a beta package (`b0` suffix), `opentelemetry-instrumentation-psycopg` is subject to breaking changes without prior deprecation periods. APIs and behaviors may evolve with future releases.
fix
Review `opentelemetry-python-contrib` release notes (CHANGELOG.md) regularly when upgrading and be prepared for potential adjustments to your code or configuration.
affects: All `b0` versions
breakingIncluding SQL comments (like traceparent) directly within the `db.statement` span attribute became opt-in as of `opentelemetry-python-contrib` version 1.29.0/0.50b0. Previously, it might have been included by default.
fix
If you relied on SQL comments being present in `db.statement`, you must explicitly enable them during instrumentation setup by passing `enable_commenter=True` to the `instrument()` method: `PsycopgInstrumentor().instrument(enable_commenter=True)`.
affects: >=1.29.0/0.50b0 of `opentelemetry-python-contrib` (which includes this instrumentation)
gotchaWhen using `psycopg` connection pooling, ensure compatibility with the OpenTelemetry instrumentation. While specific issues were reported for `psycopg2` and Python versions 3.6-3.8 leading to recursion errors with `ThreadedConnectionPool`, general complexities can arise with any pooling setup. Ensure your `psycopg` version (3.1.0+) and Python version (3.9+) meet requirements.
fix
Test thoroughly with your specific `psycopg` and pooling library versions. Refer to `opentelemetry-python-contrib` GitHub issues for known pooling-related problems. Ensure your Python environment meets `psycopg`'s and OpenTelemetry's minimum requirements (Python >=3.9 for this instrumentation and `psycopg` >=3.1.0).
affects: All versions, especially with connection pooling
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
psycopgrequiredThe PostgreSQL driver being instrumented. Requires psycopg version 3.1.0 or higher.
opentelemetry-sdkrequiredRequired for a full OpenTelemetry setup (e.g., configuring exporters, resource detectors). While not a direct install dependency of this specific instrumentation, it is essential for end-to-end tracing.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
opentelemetry-instrumentation-psycopg — pip install opentelemetry-instrumentation-psycopg · libregistry