Bounded in-memory owner for canonical Kernel events.
The sink assigns schema version, run/trace identity, monotonic sequence, and
UTC timestamp. Producers supply only a canonical bounded event type and data
that normalize to JSON without key collisions. Per-event payload accounting
and aggregate accounting cover the payload and complete retained envelope,
respectively, so every retained event is consumable by TraceLog.
Under :normal policy, a full or unavailable sink ordinarily records or
projects loss without changing workflow execution. An internal normal sink
may opt into fail-closed owner loss so a session cannot continue without its
canonical recorder. Normal sinks reserve two measured terminal envelopes by
default. Private sinks reserve one run-stopped envelope so a capacity
refusal can retain a complete terminal trace.
Finalization atomically appends the bounded loss summary and run-stopped,
freezes the recorder, and returns the exact terminal batch and drop snapshot.
Runner and session startup atomically claim the recorder while retaining
run-started, so one configuration cannot execute twice or concurrently.
Later emits cannot mutate either snapshot. Drop accounting retains at most
sixteen event-type buckets plus a saturating $overflow count. The sink
monitors its owner and exits when the owner terminates.
Persistent JSONL storage is an explicit PtcRunner.Kernel.TraceLog operation
after collection, not an arbitrary callback in the runtime path.
Summary
Functions
Returns a specification to start this module under a supervisor.
Returns dropped-event counts keyed by event type.
Emits one bounded event or applies the sink's loss policy.
Returns retained canonical events in sequence order.
Returns only this sink's run and trace identity to its token holder.
Returns the configured loss policy.
Returns the event_payload_bytes one terminal payload of usage needs.
Starts a sink with one policy and the event bounds from limits.
Stops the sink. Calling it after owner-driven shutdown is harmless.
Types
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
Returns dropped-event counts keyed by event type.
@spec emit(t(), binary(), map()) :: :ok | {:error, :event_sink_error} | {:error, {:event_capture_limit_exceeded, :normal_event_count | :normal_event_bytes, pos_integer()}}
Emits one bounded event or applies the sink's loss policy.
Returns retained canonical events in sequence order.
Returns only this sink's run and trace identity to its token holder.
Returns the configured loss policy.
@spec required_terminal_payload_bytes(t(), map()) :: pos_integer() | :error
Returns the event_payload_bytes one terminal payload of usage needs.
Admission compares this against the effective limit, and the refusal reports it, so the number a caller is told to raise to is the number that refused them. Normal policy charges the saturated reachable drop map at its conservative bound rather than at whatever the current run happens to hold.
@spec start(policy(), PtcRunner.Kernel.Limits.t(), keyword()) :: {:ok, t()} | {:error, :invalid_event_sink}
Starts a sink with one policy and the event bounds from limits.
Options are :run_id, :trace_id, :owner, and the internal normal-policy
:terminal_reserve and :fail_closed. Normal sinks default to the standard
two-event terminal reserve; private sinks reserve one terminal event. IDs
must be valid UTF-8 binaries from 1 through 256 bytes; a unique run ID is
generated when omitted and is also the default trace ID.
@spec stop(t()) :: :ok
Stops the sink. Calling it after owner-driven shutdown is harmless.