Request summaries and query budgets¶
Route and timing¶
event.http.route is the matched template, such as /v1/items/{item_id}.
event.path and url.path remain the received path. Unknown routes omit
http.route; metrics use <unmatched>. At lifespan startup, fastapi-observer
also inspects the registered routing table once and logs route.duplicate or
route.shadowed warnings when an earlier static or less-specific route masks a
later route (for example /users/{id} registered before /users/me).
For duration_ms, app_duration_ms, db.ms and http.ms, see
what the durations mean. The streaming and
payload fields use a monotonic clock rounded to three decimals:
| Field | Meaning | When unknown |
|---|---|---|
response_start_ms |
Request entry through send(http.response.start) completion |
null if no response-start send succeeded |
first_body_ms |
Request entry through the first nonempty body chunk send | null if no nonempty body was sent |
stream_duration_ms |
First nonempty body send through final body/trailer completion (0.0 for single-chunk responses) |
null if empty or interrupted |
response_bytes |
Total bytes sent across http.response.body chunks |
0 for empty responses |
For after_disconnect_ms and after_disconnect_calls, see
client disconnects.
Per-request diagnostics and 422 validation errors¶
When one or more anomalies occur during an HTTP request or WebSocket session,
event.diagnostics lists the triggered machine-readable tags on that request's
log record:
Tag in event.diagnostics |
Trigger |
|---|---|
db.n_plus_one |
The same SQL statement text (compared by SHA-256, never logged) executed >= 10 times in the request |
db.slow_query |
One SQL statement took at least OBS_SLOW_QUERY_MS (default 1000 ms) |
http.n_plus_one |
Outbound HTTP calls to the same method, host and path (with numeric, UUID and long hex path segments collapsed) ran >= 10 times in the request. The warning names the method and host only, since a path can hold a secret |
db.connection_held_during_http |
A SQLAlchemy connection stayed checked out across an outbound HTTP call and was held >= 10 × db.ms (or remained checked out at request end) |
db.connection_held_idle |
Without an outbound HTTP call, SQLAlchemy connections were held >= 10 × db.ms and >= 100 ms longer than the queries ran |
db.pool_exhausted |
Request started while a watched SQLAlchemy QueuePool was at full capacity |
threadpool.saturated |
Request started while AnyIO's worker thread pool had 0 free tokens and calls were waiting for one |
event_loop.blocked |
The event-loop watchdog detected a stall while this request was in flight |
gc.pause |
Garbage collection stopped the process for >= 100 ms in total while an HTTP request ran; the line also gets gc_pause_ms |
In a WebSocket session, the two N+1 counts start again at each message sent or
received, and gc.pause is skipped because cumulative GC time spans the
whole connection lifetime. One query per message is not reported, however long
the session lasts; ten for one message is.
On 422 Unprocessable Entity responses, event.validation_errors captures up to
16 failed field locations and error types ([{"loc": "body.items.0.price", "type": "greater_than"}],
never raw input values), and increments fastapiobserver_http_validation_errors_total{route, field}
with list indices normalized to [] (body.items.[].price).
When a request also has a recording OpenTelemetry server span, fastapiobserver.db.n_plus_one,
fastapiobserver.threadpool.saturated, and fastapiobserver.db.pool_exhausted are attached as span
events (at most once each per request) without raw SQL or engine URLs.
SQL execution detail¶
The db.sqlalchemy breakdown of attempted, failed and in-flight queries is
described in database tracing.
Observation coverage¶
Every terminal record includes observation.coverage:
| Value | Meaning |
|---|---|
unknown |
No dependency observation was recorded |
instrumented_clients |
Observations came from attached native hooks (sqlalchemy, httpx, httpx2, requests) |
caller_reported |
Only explicit/manual reports were observed |
partial |
Sampled spans, mixed manual/native sources, unfinished calls (in_flight), or span-tracking overflow (dropped_spans) |
Sampling policy and delivery¶
log_sampling records Observer's retention decision before queue delivery:
{"owner": "observer", "inclusion_probability": 0.1, "reason": "sampled"}
Reasons are all, sampled, warning, failure, slow, or no_identity
(or {"owner": "application", "inclusion_probability": null, "reason": "unknown"}
when configure_logging=False). Use unsampled Prometheus request metrics for
SLO traffic counts rather than inverse-weighting sampled logs.
Native query-budget assertion¶
from sqlalchemy import create_engine, text
from fastapiobserver.db_queries import count_queries
from fastapiobserver.testing import assert_query_budget
engine = create_engine("sqlite://")
count_queries(engine) # Or install_observability(..., db_engine=engine).
with assert_query_budget(engine, 1) as budget:
with engine.connect() as connection:
connection.execute(text("SELECT 1"))
assert budget.count == 1
assert_query_budget requires no pytest plugin or OTel provider and counts all
admitted before_cursor_execute attempts on the target Engine or AsyncEngine
within the active contextvars scope. See
examples/query_budget.py.