Expand description
Core trace observer abstraction for HTTPX-compatible request tracing.
This module defines a typed event vocabulary derived from httpcore 1.0.9, plus a callback trait that transports use to emit lifecycle events. The Python binding implements this trait and bridges to user-supplied trace callables without holding the GIL during network waits.
§Reconciliation with metrics and metadata
Trace covers request/response lifecycle (send_request_headers,
receive_response_headers) consistently across direct, proxy, SOCKS,
UDS, and H3 paths. Connector-level observations (DNS/connect/TLS
attempts, H3 creations/evictions, proxy CONNECT outcomes, 101 upgrades)
are counted in crate::TransportMetrics instead of duplicating the
event taxonomy: metrics are cheap, always-on, and atomic, while trace
callbacks are per-request, synchronous, and user-controlled.
ConnectTcp, ConnectUnixSocket, StartTls, Retry, Close, and
body/close events remain part of the httpcore-compatible vocabulary
for facade compatibility, but only request/response header events are
emitted today. Emitting DNS/connect/TLS trace events consistently
across all five transport families would require plumbing observers
into tower connectors; until that is done uniformly, those phases are
observed via metrics to avoid contradictory duplicate lifecycle events.
Existing event names and phases remain compatible.
Structs§
- Collecting
Trace Observer - A trace observer that collects events into a shared vector.
- Noop
Trace Observer - A no-op trace observer that silently discards all events.
Enums§
- Event
Value - Opaque value type for trace event info dictionaries.
- OnEvent
Action - Control result returned by
TraceObserver::on_event. - Trace
Event - Typed lifecycle events emitted by the transport layer.
- Trace
Phase - Lifecycle phase of a trace event.
Traits§
- Trace
Observer - Callback trait for receiving trace events from the transport layer.
Functions§
- event_
to_ httpcore_ name - Map a
TraceEventto the httpcore 1.0.9 dotted event name. - event_
to_ info - Convert a
TraceEventinto the flat dictionary representation that httpcore’s trace callback receives.