Compatibility baseline: 2.2.1¶
The compatibility probe¶
tests/fixtures/compatibility-2.2.1.json records the 27 stable root exports,
function parameters and defaults, configuration-model defaults and validation
aliases, the log schema version, and representative success, 404 and exception
records. scripts/compatibility_probe.py generated it from the v2.2.1 tag,
and tests/test_release_compatibility.py runs the same probe against the
current source on every test run.
The probe normalizes timestamps, generated request IDs, elapsed durations, the
library version and exception stack locations. Field names and outcomes must
match exactly. It leaves out fields and settings added since 2.2.1, which have their own
contract tests: ObservabilitySettings.slow_query_ms, http.route, observation,
log_sampling, response_bytes, response_start_ms, first_body_ms and
stream_duration_ms.
To reproduce the baseline without importing the current source:
baseline_dir=$(mktemp -d)
git archive v2.2.1 src | tar -x -C "$baseline_dir"
PYTHONPATH="$baseline_dir/src" python scripts/compatibility_probe.py > /tmp/baseline.json
diff -u tests/fixtures/compatibility-2.2.1.json /tmp/baseline.json
The installed dependencies must support 2.2.1. The probe starts no exporter and contacts no backend.
Claims and their tests¶
| Claim | Evidence | Limit |
|---|---|---|
| One-call FastAPI setup and repeated lifespans | test_fastapi_install.py, test_lifespan_teardown.py |
FastAPI/Starlette remain required installation dependencies |
| Concurrent request correlation | test_context_isolation.py, test_trust_boundary.py |
Copied thread contexts share request state; arbitrary new threads need explicit handoff |
| Response/stream timing excludes background work | test_response_timing.py, test_production_runtime.py |
Measured at ASGI send completion, not client receipt; the final record follows application completion; the sent status is kept |
| Structured logs and application-owned logging | test_logging_schema_contract.py, test_application_logging.py, test_existing_logging_example.py |
With configure_logging=False, the application's handlers own free-text sanitization, delivery and shutdown |
| SQLAlchemy counts without tracing | test_request_insights.py, test_sqlalchemy_integration.py, test_sql_execution_details.py |
Explicit engines; db.count counts successful executions, db.sqlalchemy also counts attempts and failures; SQLite sync/async is tested |
| HTTP diagnostics without tracing | test_http_calls.py, test_propagation.py |
Explicit HTTPX/HTTPX2 or Requests helpers; streamed calls complete at consumption/closure |
| N+1 warnings avoid raw SQL | test_hardening.py, test_request_insights.py |
Full-statement SHA-256; 128 per-request fingerprints, 1,024 retained warning keys; a hash is not anonymization |
| Diagnostic span events | test_diagnostic_spans.py, test_sqlalchemy_integration.py |
At most three per request, on existing recording server spans; pool pressure is a snapshot, not a measured wait |
| Field/header redaction | test_security_redaction.py, test_body_media_allowlist.py |
Name-based; SQL tracing payloads need their own review |
| Bounded queue and blocked-sink behavior | test_log_queue_controls.py, test_logging_shutdown.py, test_production_runtime.py |
Limits count records, not bytes; application handlers can block |
| Fork safety and recycled workers | test_fork_queue_listener.py, test_processes.py |
POSIX only |
| Prometheus labels stay bounded | test_route_template_cardinality.py, test_metrics_contracts.py |
Queue, pool and process collectors are left out in multiprocess mode |
| OTLP delivery and borrowed providers | test_otlp_export_integration.py, test_otel_lifecycle.py, test_application_logging.py |
Best-effort delivery: OTLP retries can duplicate records, and a killed process loses queued ones |
| Production and release gates | test_production_runtime.py, test_release_ref.py, shared validation workflow |
The release budgets apply to the test workload. CPU comparisons are manual; test_compare_overhead.py checks only their arithmetic |
Configuration compatibility covers the OBS_* names in
configuration, the OBS_PROFILE defaults, the standard
OTEL_EXPORTER_OTLP_*, OTEL_TRACES_SAMPLER_ARG, OTEL_RESOURCE_ATTRIBUTES,
OTEL_METRIC_EXPORT_INTERVAL and OTEL_SDK_DISABLED variables, and
service-name precedence. test_config_settings.py, test_profiles.py and
test_otel_integration.py test that precedence.
Submodule interfaces with a narrower stability promise than the root exports:
logging flush, level and stats helpers; SQLAlchemy tracing and
uninstrumentation; HTTP uninstrumentation; metrics registration and backends;
sink registration; and the Strawberry integration. HTTP request histograms keep
their names, buckets and service, environment, method, path and
status_code labels.