# lifecycle URL: /pounce/api/lifecycle/ Section: api Description: 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 ``BufferedCollector`` or custom implementation to capture events. All timestamps use ``time.monotonic_ns()`` for high-resolution, monotonic ordering that is not affected by system clock adjustments. --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/lifecycle/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flifecycle%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flifecycle%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flifecycle%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flifecycle%2Findex.txt) 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 `BufferedCollector`or custom implementation to capture events. All timestamps use`time.monotonic_ns()`for high-resolution, monotonic ordering that is not affected by system clock adjustments. 11Classes1Function ## 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` 8 ▼ An HTTP response was fully sent. ``method`` is the HTTP request method (e.g. ``"GET"``). Use the … An HTTP response was fully sent. `method` is the HTTP request method (e.g. `"GET"`). Use the sentinel`"unknown"`on error/early-out paths where the method is not known, never the empty string — metrics key the `http_requests_total`counter on this label. #### Attributes Name Type Description `connection_id` `int` — `worker_id` `int` — `status` `int` — `bytes_sent` `int` — `duration_ms` `float` — `timestamp_ns` `int` — `method` `str` — `streaming` `bool` — `StreamOpened` 5 ▼ A streaming HTTP response started and remains open. A streaming HTTP response started and remains open. #### Attributes Name Type Description `connection_id` `int` — `worker_id` `int` — `method` `str` — `path` `str` — `timestamp_ns` `int` — `StreamClosed` 5 ▼ A streaming HTTP response ended. A streaming HTTP response ended. #### Attributes Name Type Description `connection_id` `int` — `worker_id` `int` — `duration_ms` `float` — `reason` `str` — `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 … Bases: `Protocol` Interface for consuming lifecycle events. Implementations must be thread-safe — in free-threading mode, multiple workers (threads) will call`record()`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: the`record()`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. Call`flush()`to retrieve and clear the buffer, or register an`on_flush`callback for automatic batch processing. Thread-safe via`threading.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. If`max_buffer_size`is 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`