Skip to content

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 install 'logfire[psycopg]'

uv add 'logfire[psycopg]'

rye add logfire -E psycopg

poetry add 'logfire[psycopg]'

Or with the psycopg2 extra:

pip install 'logfire[psycopg2]'

uv add 'logfire[psycopg2]'

rye add logfire -E psycopg2

poetry 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:

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:secret@0.0.0.0:5432/database.

Run the Python script

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

import logfire
import psycopg

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 

instrument_psycopg(
    conn_or_module: PsycopgConnection | Psycopg2Connection,
    **kwargs: Any,
) -> None

instrument_psycopg(
    conn_or_module: (
        None | Literal["psycopg", "psycopg2"] | ModuleType
    ) = None,
    enable_commenter: bool = False,
    commenter_options: CommenterOptions | None = None,
    **kwargs: Any,
) -> None

instrument_psycopg(
    conn_or_module: Any = None,
    enable_commenter: bool = False,
    commenter_options: CommenterOptions | 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.

Parameters:

Name Type Description Default
conn_or_module
Any

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.
 None
enable_commenter
bool

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

 False
commenter_options
CommenterOptions | None

Configure the tags to be added to the SQL comments.

 None
**kwargs
Any

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

 {}

logfire.integrations.psycopg.CommenterOptions

Bases: TypedDict

The commenter_options parameter for instrument_psycopg.

db_driver instance-attribute 
db_driver: bool

Include the database driver name in the comment e.g. 'psycopg2'.

dbapi_threadsafety instance-attribute 
dbapi_threadsafety: bool

Include the DB-API threadsafety value in the comment.

dbapi_level instance-attribute 
dbapi_level: bool

Include the DB-API level in the comment.

libpq_version instance-attribute 
libpq_version: bool

Include the libpq version in the comment.

driver_paramstyle instance-attribute 
driver_paramstyle: bool

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

opentelemetry_values instance-attribute 
opentelemetry_values: bool

Enabling this flag will add traceparent values to the comment.