0018: Add diagnostic detail without changing established counters¶
Status: accepted, for the experiment ยท Reviewed: 2026-11-05
Context¶
A request's path is not a bounded route. A sum of call durations hides whether the calls overlapped. db.count counts successful queries only, so failed attempts were invisible. Native hooks, manual reports and sampled spans each see a different share of the calls. And deciding to keep a log record is separate from delivering it.
Decision¶
- Resolve the route once and reuse it for response metrics, the request line and N+1 diagnostics, as
http.route. Keep the response and application durations and the existing metric labels. - Keep
db.countanddb.msas successful executions. Adddb.sqlalchemy, a separate summary of attempted, succeeded, failed and in-flight queries, completed by the owner-capturing handles from 0017 and onehandle_errorhook. - Build dependency summaries from the same state snapshot for requests and operations.
observationnames fixed sources and reports unfinished calls and span-tracking drops. A configured provider is never taken as proof that every call was seen. - Record the sampling decision as
log_samplingon terminal records before they reach the queue. With application-owned logging the reason isunknown. A cached decision keeps its original probability. - Add
fastapiobserver.testing.assert_query_budget(engine, max_queries), which subscribes to the native cursor hook. It requires attached hooks, counts failed attempts and nested scopes, and lets application exceptions through. It never reads log output. - Test the configured redaction policy with generated bodies through JSON output, real in-memory OTLP records and the stderr fallback. Hypothesis stays a development dependency.
Evidence¶
test_sql_execution_details.pyruns sync and async engines, includingtest_only_failed_sql_keeps_legacy_success_count_at_zeroandtest_connection_failures_are_not_reported_as_cursor_execution_attempts.test_observation_metadata.pycovers each coverage value, borrowed loggers, sampled fallback and overflow, andtest_sampling_probability_tracks_the_cached_decision_across_reconfiguration.test_query_budget.pyincludestest_budget_refuses_unattached_native_hooks_instead_of_passing_zero, nested budgets, threads and a real FastAPI request.test_redaction_properties.pygenerates encoded, nested and truncated inputs through JSON, OTLP and stderr.
What it cost¶
- Every new field is optional. The 2.2.1 compatibility probe leaves them out, and each has its own contract test.
- A request whose only queries failed now has an explicit
db.countof 0 next todb.sqlalchemy.failed. - The extra snapshots and metadata add serialization work to every terminal record.
log_samplingdescribes selection, not delivery. A query budget covers one engine's cursor-entry layer, not other databases or work outside its context.