0016: Prove Python operations through existing seams¶
Status: accepted, for the opt-in experiment ยท Reviewed: 2026-11-04
Context¶
The SQLAlchemy and HTTP helpers already count calls without tracing, but they store the counts on a FastAPI request's state. A job, a CLI command or a message handler outside a request got nothing. A second logging and telemetry pipeline for that code would repeat redaction, correlation, lifecycle and call counting.
Decision¶
fastapiobserver.experimental.observe_operation()reuses the request state and the client hooks (experimental.py). The 27 root exports stay as they are.- It works with
withandasync with, and nests. Each scope resets its context variables with their tokens on exit. A child's counts are its own. A closed operation refuses late writes and drops its totals, fingerprints, held records and user context. - It borrows logging, clients and providers. The terminal record gets its correlation fields before any queue. The application owns handlers, sanitizing and the final flush.
- Root exports that need FastAPI load on first access, and the plugin module imports framework types for type checking only. Installation dependencies and the fork-reset module paths stay the same.
- It ships as an alpha in the existing
fastapi-observerdistribution. A separate package name, more adapters and a portable contract are later decisions.
Evidence¶
test_release_compatibility.pycompares the public interface, configuration and representative FastAPI output with a fixture taken from thev2.2.1tag.test_core_imports.py:test_experimental_operation_never_imports_frameworks_or_optional_clientsfails if an operation imports a framework or an optional client, andtest_python_operation_example_uses_real_sql_and_loopback_http_without_frameworksruns the SQLite and HTTP example.test_experimental_operations.pycovers nesting, threads, concurrent tasks, cancellation, late completion, log sampling and failures.test_existing_tracing_bridges_do_not_change_native_operation_totalsruns at trace sampling ratios 0, 0.1 and 1.
What it cost¶
- Operations reuse
RequestState, which is named for requests. Moving every module waits for a second real consumer. - A normal install still pulls in FastAPI and Starlette.
- The operation schema,
0.1.0, is experimental. Operations get no slow-request promotion, no N+1 warnings and no lifecycle or provider API. - The bundled example is the only application validated.