Skip to content

Design decisions

Each record says what was decided, the evidence for it and what it cost. Read the matching one before changing that part of the library. To challenge a decision, open an issue that argues with its evidence.

# Decision In one line
0001 Pure ASGI middleware BaseHTTPMiddleware adds about 153 µs per request and hides context the endpoint sets.
0002 Logs leave through a bounded queue With a slow handler, logging costs the caller about 19 µs per call instead of 1.3 to 1.5 ms. Under overload the oldest lines are dropped and counted.
0003 Identity headers count only from known peers Request ID, traceparent and client IP come only from addresses in OBS_TRUSTED_CIDRS.
0004 Redact before anything leaves the process No handler but ours on the root logger. Written after the 1.5.0 leak.
0005 Route templates as metric labels One series per route, not per URL, and scanner 404s share one <unmatched> label.
0006 Hand work to OpenTelemetry and prometheus_client Use them for what they already do, and accept that their changes reach us.
0007 New destinations and controls are opt-in Sinks from other packages, the control plane, metrics and OTLP export stay off until configured.
0008 One state object per request Held log lines, user context, query totals and log bytes reach the middleware from sync endpoints and span processors. Costs about 2 µs per request.
0009 Sample logs per request, by trace ID A request's INFO lines are kept or dropped together, the same way as its trace in every service. Failed and slow requests are always kept.
0010 Trace with FastAPI's own OpenTelemetry On FastAPI 0.142+, FastAPI traces requests itself, and its own log export stays off so error logs go through redaction.
0011 Every unmatched request shares one label Preflights, rejected requests and scanners share <unmatched>, and made-up methods share _OTHER.
0012 No sinks from installed packages Custom sinks are registered in code with register_sink(). The entry-point loader and OBS_LOG_SINKS are gone.
0013 Every setting has one name The library's own variables start with OBS_, OpenTelemetry's are the specification's, and nothing is read from a field's bare name.
0014 Diagnosis works without tracing SQLAlchemy queries and N+1 are counted from SQLAlchemy's events; the production profile turns the loop watchdog on, and held DEBUG logs stay opt-in.
0015 Application-owned logging Install diagnostics through an existing logging pipeline, retaining its sanitizer and exporters.
0016 Experimental Python operations Reuse context, logging and client hooks for opt-in manual operations, preserving the FastAPI interface.
0017 Completed-call ownership Capture ownership at start, invalidate weak handles at closure and share recording across native/manual/span sources.
0018 Additive diagnostic metadata Preserve existing counts while exposing native failures, coverage, sampling policy and scoped query budgets.
0019 Stream timing and diagnostic events Measure successful ASGI sends and annotate existing server spans with bounded, safe diagnostic facts.

Writing a new record

  • Use the next number, and the same four parts: Context, Decision, Evidence, What it cost.
  • Keep it to about one screen.
  • Link code and tests at a release tag once one contains them, and at main until then.
  • Put any measurement script in examples/benchmarks/, so the numbers can be reproduced.
  • When a decision changes, write a new record that supersedes the old one, and mark the old one superseded. Don't rewrite it.