---
id: opentelemetry-instrumentation-psycopg
version: "0.65b0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# opentelemetry-instrumentation-psycopg — OpenTelemetry psycopg instrumentation

License: permissive · Maintenance: active · Downloads: 5.7M/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 5.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

psycopg tracing instrumentation, opentelemetry database monitoring, sql query observability, psycopg performance metrics, distributed tracing postgresql, database instrumentation opentelemetry, observability, distributed-tracing, postgresql

[View on SkillFed](https://skillfed.io/packages/opentelemetry-instrumentation-psycopg) · [View on PyPI](https://pypi.org/project/opentelemetry-instrumentation-psycopg/)