Skip to main content

Module trace

Module trace 

Source
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§

CollectingTraceObserver
A trace observer that collects events into a shared vector.
NoopTraceObserver
A no-op trace observer that silently discards all events.

Enums§

EventValue
Opaque value type for trace event info dictionaries.
OnEventAction
Control result returned by TraceObserver::on_event.
TraceEvent
Typed lifecycle events emitted by the transport layer.
TracePhase
Lifecycle phase of a trace event.

Traits§

TraceObserver
Callback trait for receiving trace events from the transport layer.

Functions§

event_to_httpcore_name
Map a TraceEvent to the httpcore 1.0.9 dotted event name.
event_to_info
Convert a TraceEvent into the flat dictionary representation that httpcore’s trace callback receives.