opentelemetry-instrumentation-psycopg

What it is and what it does

This package integrates OpenTelemetry tracing into psycopg database connections, automatically instrumenting SQL queries to emit spans that capture execution details. It sits between your application and the psycopg driver, intercepting database operations and forwarding them to your configured OpenTelemetry exporters (e.g., Jaeger, Datadog, or any OTLP-compatible backend).

It is built on the OpenTelemetry instrumentation framework and depends on three core OpenTelemetry packages: opentelemetry-api, opentelemetry-instrumentation, and opentelemetry-instrumentation-dbapi. Once installed and initialized, it requires minimal code changes—typically a single call to PsycopgInstrumentor().instrument()—and then all psycopg queries become visible in your distributed tracing system. It is currently in Beta status and supports Python 3.10 through 3.14.

Use it for:

• Monitor slow database queries in production by capturing query spans and latency in your tracing backend.
• Debug application performance issues by correlating database operations with upstream HTTP requests in distributed traces.
• Audit database activity in compliance-sensitive applications by exporting query details to a centralized observability platform.
• Measure database connection pool utilization and query patterns across microservices.
• Integrate PostgreSQL query tracing into an existing OpenTelemetry observability stack.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds OpenTelemetry tracing instrumentation to psycopg database connections, automatically capturing SQL queries and performance metrics for observability.

Yes, if you are already using OpenTelemetry and need database observability for psycopg. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a safe choice. The Beta status is acceptable for most observability use cases, though you should verify it covers your specific psycopg version and tracing requirements before deploying to production.

Install

opentelemetry-instrumentation-psycopg on PyPI

pip install opentelemetry-instrumentation-psycopg

uv add opentelemetry-instrumentation-psycopg

poetry add opentelemetry-instrumentation-psycopg

Installing opentelemetry-instrumentation-psycopg

Before you install

Low friction install with three lightweight OpenTelemetry runtime dependencies. Actively maintained with a recent release; last commit on 2026-08-14 and repository shows 1086 stars.

License in practice

Apache-2.0 permissive license allows use in most projects, including commercial ones, with minimal restrictions.

Quickstart

pip install opentelemetry-instrumentation-psycopg

from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

PsycopgInstrumentor().instrument()

Requires Python 3.10 or later; psycopg must already be installed in your environment.

Verify before relying

• Whether instrumentation works with both psycopg2 and psycopg3, or only one version.
• What specific span attributes and metrics are captured beyond basic query tracing.
• Whether there is performance overhead from instrumentation in high-throughput scenarios.

Package facts

Evidence: opentelemetry_instrumentation_psycopg-0.65b0-py3-none-any.whl

Tags

More Monitoring packages