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.

8Classes2Functions

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 —
ConnectionClosed 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

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