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
mainuntil 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.