Module

lifecycle

Connection lifecycle events — structured, immutable records.

Each event captures a moment in a connection's lifecycle as a frozen dataclass. Events are designed for aggregation, replay, and observability — not logging. They form the foundation of the full-stack effect observability system.

Events are produced by the worker and consumed by an optional LifecycleCollector. The default collector (NoopCollector) discards all events with zero overhead. Replace it with a BufferedCollectoror custom implementation to capture events.

All timestamps usetime.monotonic_ns()for high-resolution, monotonic ordering that is not affected by system clock adjustments.

9Classes2Functions

Classes

ConnectionOpened 8 ▼
A new TCP connection was accepted.

A new TCP connection was accepted.

Attributes

Name Type Description
connection_id int —
worker_id int —
client_addr str —
client_port int —
server_addr str —
server_port int —
protocol str —
timestamp_ns int —
RequestStarted 6 ▼
An HTTP request head was fully parsed.

An HTTP request head was fully parsed.

Attributes

Name Type Description
connection_id int —
worker_id int —
method str —
path str —
http_version str —
timestamp_ns int —
ResponseCompleted 6 ▼
An HTTP response was fully sent.

An HTTP response was fully sent.

Attributes

Name Type Description
connection_id int —
worker_id int —
status int —
bytes_sent int —
duration_ms float —
timestamp_ns int —
ClientDisconnected 4 ▼
The client closed the connection unexpectedly.

The client closed the connection unexpectedly.

Attributes

Name Type Description
connection_id int —
worker_id int —
during_streaming bool —
timestamp_ns int —
ConnectionCompleted 7 ▼
The TCP connection was closed (by either side).

The TCP connection was closed (by either side).

Attributes

Name Type Description
connection_id int —
worker_id int —
requests_served int —
total_bytes_sent int —
duration_ms float —
reason str —
timestamp_ns int —
LifecycleCollector 1 ▼
Interface for consuming lifecycle events. Implementations must be thread-safe — in free-threading …

Interface for consuming lifecycle events.

Implementations must be thread-safe — in free-threading mode, multiple workers (threads) will callrecord()concurrently.

Methods

record 1 ▼
Record a lifecycle event.
def record(self, event: LifecycleEvent) -> None
Parameters
Name Type Description
event —
NoopCollector 1 ▼
Default collector — discards all events. Zero overhead: the ``record()`` method is an empty functi…

Default collector — discards all events.

Zero overhead: therecord()method is an empty function body. Used when no observability is configured.

Methods

record 1 ▼
Discard the event.
def record(self, event: LifecycleEvent) -> None
Parameters
Name Type Description
event —
BufferedCollector 5 ▼
Thread-safe collector that buffers events for batch processing. Events accumulate in an internal l…

Thread-safe collector that buffers events for batch processing.

Events accumulate in an internal list. Callflush()to retrieve and clear the buffer, or register anon_flushcallback for automatic batch processing.

Thread-safe viathreading.Lock— safe for free-threading mode where multiple worker threads produce events concurrently.

Methods

record 1 ▼
Append an event to the buffer. If ``max_buffer_size`` is set and reached, the …
def record(self, event: LifecycleEvent) -> None

Append an event to the buffer.

Ifmax_buffer_sizeis set and reached, the buffer is automatically flushed.

Parameters
Name Type Description
event —
flush 0 list[LifecycleEvent] ▼
Retrieve and clear the buffered events.
def flush(self) -> list[LifecycleEvent]
Returns
list[LifecycleEvent] List of events accumulated since the last flush.
Internal Methods 3 ▼
__init__ 2 ▼
def __init__(self, *, max_buffer_size: int = 0, on_flush: Callable[[list[LifecycleEvent]], None] | None = None) -> None
Parameters
Name Type Description
max_buffer_size — Default:0
on_flush — Default:None
_flush_locked 0 list[LifecycleEvent] ▼
Flush the buffer while holding the lock. Returns the batch.
def _flush_locked(self) -> list[LifecycleEvent]
Returns
list[LifecycleEvent]
__len__ 0 int ▼
def __len__(self) -> int
Returns
int
LoggingCollector 2 ▼
Logs lifecycle events as structured JSON for production observability. Converts lifecycle events i…

Logs lifecycle events as structured JSON for production observability.

Converts lifecycle events into structured log entries with correlation IDs, durations, and rich context for debugging production issues.

Features:

  • Logs slow requests when duration exceeds threshold
  • Structured JSON output when log_format="json"
  • Correlation via connection_id and worker_id
  • Zero overhead when log level filters out debug logs
  • Thread-safe for free-threading mode

Methods

record 1 ▼
Log a lifecycle event as structured output. Logs at different levels based on …
def record(self, event: LifecycleEvent) -> None

Log a lifecycle event as structured output.

Logs at different levels based on event type:

  • ConnectionOpened: DEBUG
  • RequestStarted: DEBUG
  • ResponseCompleted: INFO (slow requests), DEBUG (fast)
  • ClientDisconnected: WARNING
  • ConnectionCompleted: DEBUG
Parameters
Name Type Description
event —
Internal Methods 1 ▼
__init__ 3 ▼
def __init__(self, *, slow_request_threshold_ms: float = 5000.0, log_format: str = 'json', health_check_path: str | None = None) -> None
Parameters
Name Type Description
slow_request_threshold_ms — Default:5000.0
log_format — Default:'json'
health_check_path — Default:None

Functions

next_connection_id 0 int ▼
Return a globally unique, monotonically increasing connection ID. Thread-safe …
def next_connection_id() -> int

Return a globally unique, monotonically increasing connection ID.

Thread-safe — uses a lock for correctness under free-threading.

Returns
int
monotonic_ns 0 int ▼
Return the current monotonic clock value in nanoseconds.
def monotonic_ns() -> int
Returns
int