Skip to content

Experimental Python operations

fastapiobserver.experimental.observe_operation() observes a sync or async operation outside a request, such as a job or a CLI command, with the same logging, SQLAlchemy and HTTP helpers. Its interface and event schema can change in any release; the FastAPI interface and request fields keep their usual compatibility.

import logging

from fastapiobserver.experimental import observe_operation

with observe_operation("catalog.import"):
    logging.getLogger("catalog").info("catalog.imported")

async def import_catalog():
    async with observe_operation("catalog.import"):
        await fetch_catalog()

Configure logging before entering the operation. To use the library's JSON queue:

from fastapiobserver import ObservabilitySettings, setup_logging
from fastapiobserver.logging import flush_logging, shutdown_logging

setup_logging(ObservabilitySettings(service="catalog-import"))
# Run operations here.
flush_logging()
shutdown_logging()  # Only the owner stops shared logging, after all work ends.

To keep application-owned logging, pass logger=logging.getLogger("my.application"). The terminal record gets its correlation fields before your handlers run. Your own log calls still need their usual correlation filters.

Each operation ends with one operation.completed, operation.failed or operation.cancelled record. Its fields, nesting and ownership rules are in the draft contract.

Dependency diagnostics

Register SQLAlchemy's native hook once for each engine:

from fastapiobserver.db_queries import count_queries

count_queries(engine)  # For an AsyncEngine, use engine.sync_engine.

For HTTP clients, use instrument_httpx_client(client) or instrument_requests_session() as described in outbound HTTP diagnostics.

Run the Python-only example, which makes two SQLite queries and one loopback HTTP request:

python -m pip install fastapi-observer sqlalchemy httpx
python examples/python_operation.py

Custom clients and callbacks

For a client with no helper, record completed work on the operation object:

with observe_operation("catalog.import") as operation:
    operation.record_call("db", 0.005)  # seconds; each invocation is one call
    operation.record_call("http", 0.020, error="read_timeout")

For work that finishes in a callback, take a start handle and finish it from the callback:

with observe_operation("catalog.import") as operation:
    call = operation.start_call("db")
    # Start custom-client work; finish and join its callback before leaving.
    call.finish()

finish() returns True only for the first completion. The callback example runs SQLite work on an executor and records it through a handle: python examples/callback_operation.py.

Do not record a call by hand that a helper or a sampled span already counts.

Limits

  • FastAPI and Starlette are still installed with the package, though the operation API imports without them.
  • Slow operations do not write their held records, and N+1 warnings are not logged for operations.
  • Held records and the log queue are limited by count, not by size.
  • A blocking application handler blocks the operation. A logging error never replaces the operation's result or exception, but its record is lost.

See decisions 0016 and 0017, and the 2.2.1 baseline.