wrapture-instrumentation-postgresql

Instrumentation for the PostgreSQL client libraries, applied through wrapture.

wrapture attaches bindings to arbitrary Python call sites without modifying the code being observed, and its config layer can switch on packaged instrumentation for a third-party package by name. This is the PostgreSQL package in that collection: one wrapture.Instrumentation class per client library, so tracing every query, connection and transaction your application sends to PostgreSQL is one config entry and no code.

Status: alpha, ahead of 1.0.0. Developed against wrapture's alpha series, with pre-releases published to PyPI, and until 1.0.0 is final a plain pip install wrapture-instrumentation-postgresql picks up the latest pre-release automatically, so there is no need to pin a specific version.

Why a separate package

The core wrapture-instrumentation package deliberately covers only the standard library and third-party packages that can be exercised in-process, with no separate backend product or service needed to test against. A PostgreSQL driver is exactly the kind of target the separate-package rule was drawn for: its tests need a real server, so this package's suite runs one in a docker container, and it carries the drivers as test dependencies (some of them compiled wheels) and its own release cadence, so the core package's test matrix stays light. One package covers every client library for the one backend: psycopg, psycopg2 and asyncpg.

Installation

$ pip install wrapture-instrumentation-postgresql

Installing it brings wrapture and nothing else. No driver is a dependency: each instrumentation is inert until its driver is present, and wrapture checks the installed version against the range the instrumentation supports at apply time.

Using it

An [[instrument]] entry in wrapture.toml names the target:

[[instrument]]
name = "psycopg"

[[sink]]
type = "printer"

and the runner applies it before the application starts, so the patch is in place before the driver is imported:

$ python -m wrapture -m myapp

The same config works through autowrapt injection (AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py); through manual setup, a few lines in the application's own startup where wrapping the launch from outside is awkward; and, in a test, through wrapture.instrumentation("psycopg") scoping the instrumentation to a block. The ad-hoc tracing guide covers the config file itself.

To see what is installed, what it supports in the current environment, and what settings it takes:

$ python -m wrapture.tools instrumentation --verbose

Provided instrumentation

The entry point name is the config's name""; the linked per-target README is the full user documentation: what records, what the events carry, the setting, and what is deliberately not traced.

What is not traced

By design, and where it goes:

• Fetching rows: a query event closes when its execute returns, so time spent iterating rows afterwards is the application's, and a server-side cursor's FETCHes are not recorded (its DECLARE is).

• Pool checkouts (psycopg_pool): a connection taken from a pool records its queries like any other, but taking and returning it are not database operations and are not recorded.

• A connection taken from an asyncpg pool does not yet record its queries: the pool proxy calls the connection's methods through the class, a calling convention wrapture's signature check does not yet handle. The fix is on wrapture's side.

• LISTEN/NOTIFY, large objects and two-phase commit are out of scope.

Adding a target

Each client library is its own subpackage and entry point here. The subpackage's __init__.py holds one wrapture.Instrumentation subclass and imports only wrapture (and the package's own common.py, which imports only wrapture too); everything that touches the driver lives in sibling modules imported inside the hook. The class is registered in pyproject.toml under [project.entry-points."wrapture.instrumentation"], and gets its own test suite under tests/<target>/ and a README.md linked from the table above. The instrumentation packages page of the wrapture documentation is the full contract; TESTING.md here covers the tests and the server they run against.

License

BSD 2-Clause. See LICENSE.