wrapture-instrumentation

Instrumentation for common Python packages, 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 project is the collection of that packaged instrumentation: one wrapture.Instrumentation class per target package (Flask first, more to follow), each registered under the bare target name, so that tracing a framework is one config entry and no code.

Status: pre-alpha. The package is being built target by target against wrapture's alpha series, with development releases published to PyPI. Flask is the first target and covers its basics; see the table below.

Installation

$ pip install wrapture-instrumentation

Installing it brings wrapture and nothing else. No target package is a dependency: the instrumentation for a package you do not have is inert, and wrapture checks the installed version of each target against the range the instrumentation supports at apply time.

Using it

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

[[instrument]]
name = "flask"

[[sink]]
type = "printer"

and the runner applies it before the application starts, so the patches are in place before the framework is imported:

$ python -m wrapture -m myapp

The same config works through autowrapt injection (AUTOWRAPT_BOOTSTRAP=wrapture python myapp.py) and, in a test, through wrapture.instrumentation("flask") scoping the instrumentation to a block. The ad-hoc tracing guide covers the config file itself.

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

$ python -m wrapture.tools instrumentation --verbose

and to generate the [[instrument]] entries to paste into a config, every one disabled and every setting commented out at its default:

$ python -m wrapture.tools instrumentation --toml

Provided instrumentation

The entry point name is the config's name; the table summarizes each instrumentation, and the linked per-target README is its full user documentation: what records, what the events carry, the settings, and what is deliberately not traced. Settings, further choke points and wider version ranges are being added target by target.

Adding a target

Each target lives under src/wrapture_instrumentation/ in a role directory named for its category, as <category>/<target>: framework/flask, external/requests, database/sqlite3. The target's own name is its module path with dots as underscores (external/urllib_request for urllib.request, server/xmlrpc_server for xmlrpc.server), and the category says what kind of thing the target is and, with it, which part of wrapture the instrumentation mostly uses:

• framework/: web frameworks, and their extensions as compound names (framework/flask_restful).

• external/: outbound HTTP and RPC clients and service SDKs.

• database/: DB-API drivers and SQL toolkits.

• datastore/: other stores and caches.

• task/: task queues. messaging/: brokers and their clients.

• server/: servers handling inbound requests, WSGI and ASGI servers included.

• template/: template engines.

A new category is added when a target fits none of these. The role directories are the collection form of the layout: a package instrumenting a single target skips them and uses the flat <category>_<target> name (external_requests), the same words joined by an underscore instead of a directory. Either way the layout is internal; the entry point name, and so the name a config uses, is always the bare target.

The subpackage's __init__.py holds one wrapture.Instrumentation subclass, with one @wrapture.instrumentation_hook method per trigger module, and imports only wrapture; everything that touches the target lives in sibling submodules named for what they patch (app.py for flask.app), themselves importing only wrapture at top level. The class is registered in pyproject.toml under [project.entry-points."wrapture.instrumentation"], and gets its own test suite under tests/<category>/<target>/, mirroring the source layout. Each subpackage also carries a README.md, its user documentation, rendered by GitHub when browsing the directory and linked from the table above; the module docstrings stay the implementation commentary. The instrumentation packages page of the wrapture documentation is the full contract; TESTING.md here covers the tests.

License

BSD-2-Clause, as wrapture.