Psycopg

The logfire.instrument_psycopg() function can be used to instrument the Psycopg PostgreSQL driver with Logfire. It works with both the psycopg2 and psycopg (i.e. Psycopg 3) packages.

See the documentation for the OpenTelemetry Psycopg Instrumentation or the OpenTelemetry Psycopg2 Instrumentation package for more details.

Installation

Install logfire with the psycopg extra:

pip

Terminal

pip install 'logfire[psycopg]'

uv

Terminal

uv add 'logfire[psycopg]'

Or with the psycopg2 extra:

pip

Terminal

pip install 'logfire[psycopg2]'

uv

Terminal

uv add 'logfire[psycopg2]'

Usage

Let’s setup a PostgreSQL database using Docker and run a Python script that connects to the database using Psycopg to demonstrate how to use Logfire with Psycopg.

Setup a PostgreSQL Database Using Docker

First, we need to initialize a PostgreSQL database. This can be easily done using Docker with the following command:

Terminal

docker run --rm --name postgres \
    -e POSTGRES_USER=user \
    -e POSTGRES_PASSWORD=secret \
    -e POSTGRES_DB=database \
    -p 5432:5432 \
    -d postgres

This command will create a PostgreSQL database, that you can connect with postgres://user:[email protected]:5432/database.

Run the Python script

The following Python script connects to the PostgreSQL database and executes some SQL queries:

import psycopg

import logfire

logfire.configure()

# To instrument the whole module:
logfire.instrument_psycopg(psycopg)
# or
logfire.instrument_psycopg('psycopg')
# or just instrument whichever modules (psycopg and/or psycopg2) are installed:
logfire.instrument_psycopg()

connection = psycopg.connect('dbname=database user=user password=secret host=0.0.0.0 port=5432')

# Or instrument just the connection:
logfire.instrument_psycopg(connection)

with logfire.span('Create table and insert data'), connection.cursor() as cursor:
    cursor.execute('CREATE TABLE IF NOT EXISTS test (id serial PRIMARY KEY, num integer, data varchar);')

    # Insert some data
    cursor.execute('INSERT INTO test (num, data) VALUES (%s, %s)', (100, 'abc'))
    cursor.execute('INSERT INTO test (num, data) VALUES (%s, %s)', (200, 'def'))

    # Query the data
    cursor.execute('SELECT * FROM test')

If you go to your project on the UI, you will see the span created by the script.

SQL Commenter

To add SQL comments to the end of your queries to enrich your database logs with additional context, use the enable_commenter parameter:

import logfire

logfire.configure()
logfire.instrument_psycopg(enable_commenter=True)

This can only be used when instrumenting the whole module, not individual connections.

By default the SQL comments will include values for the following keys:

• db_driver
• dbapi_threadsafety
• dbapi_level
• libpq_version
• driver_paramstyle
• opentelemetry_values

You can exclude any of these keys by passing a dictionary with those keys and the value False to commenter_options, e.g:

import logfire

logfire.configure()
logfire.instrument_psycopg(
    enable_commenter=True,
    commenter_options={'db_driver': False, 'dbapi_threadsafety': False},
)

API Reference

instrument_psycopg

def instrument_psycopg(
    conn_or_module: PsycopgConnection | Psycopg2Connection,
    kwargs: Any = {},
) -> None
def instrument_psycopg(
    conn_or_module: None | Literal['psycopg', 'psycopg2'] | ModuleType = None,
    enable_commenter: bool = False,
    commenter_options: PsycopgCommenterOptions | None = None,
    kwargs: Any = {},
) -> None

Instrument a psycopg connection or module so that spans are automatically created for each query.

Uses the OpenTelemetry instrumentation libraries for psycopg and psycopg2.

Returns

None

Parameters

conn_or_module : Any Default: None

Can be:

• The psycopg (version 3) or psycopg2 module.
• The string 'psycopg' or 'psycopg2' to instrument the module.
• None (the default) to instrument whichever module(s) are installed.
• A psycopg or psycopg2 connection.

enable_commenter : bool Default: False

Adds comments to SQL queries performed by Psycopg, so that database logs have additional context.

commenter_options : PsycopgCommenterOptions | None Default: None

Configure the tags to be added to the SQL comments.

**kwargs : Any Default: \{\}

Additional keyword arguments to pass to the OpenTelemetry instrument methods, for future compatibility.

CommenterOptions

Bases: TypedDict

The commenter_options parameter for instrument_psycopg.

Attributes

db_driver

Include the database driver name in the comment e.g. ‘psycopg2’.

Type: bool

dbapi_threadsafety

Include the DB-API threadsafety value in the comment.

Type: bool

dbapi_level

Include the DB-API level in the comment.

Type: bool

libpq_version

Include the libpq version in the comment.

Type: bool

driver_paramstyle

Include the driver paramstyle in the comment e.g. ‘driver_paramstyle=pyformat’

Type: bool

opentelemetry_values

Enabling this flag will add traceparent values to the comment.

Type: bool