Registry /
observability / opentelemetry-instrumentation-psycopg
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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.7MB
glibcpy 3.10–3.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.fixReview `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.fixIf 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.fixTest 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.