PtcRunner.Kernel.EventSink (PtcRunner v0.14.0)

Copy Markdown View Source

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. 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

Types

policy()
t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

dropped(sink)

Returns dropped-event counts keyed by event type.

emit(sink, type, data)

Emits one bounded event or applies the sink's loss policy.

events(sink)

Returns retained canonical events in sequence order.

identity(sink)

Returns only this sink's run and trace identity to its token holder.

policy(sink)

Returns the configured loss policy.

start(policy, limits, opts \\ [])

Starts a sink with one policy and the event bounds from limits.

stop(sink)

Stops the sink. Calling it after owner-driven shutdown is harmless.

Types

policy()

@type policy() :: :normal | :private

t()

@type t() :: %PtcRunner.Kernel.EventSink{
  fail_closed?: boolean(),
  pid: pid(),
  policy: policy(),
  token: reference()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

dropped(sink)

@spec dropped(t()) :: map()

Returns dropped-event counts keyed by event type.

emit(sink, type, data)

@spec emit(t(), binary(), map()) :: :ok | {:error, :event_sink_error}

Emits one bounded event or applies the sink's loss policy.

events(sink)

@spec events(t()) :: [map()]

Returns retained canonical events in sequence order.

identity(sink)

@spec identity(t()) ::
  {:ok, %{run_id: binary(), trace_id: binary()}} | {:error, :event_sink_error}

Returns only this sink's run and trace identity to its token holder.

policy(sink)

@spec policy(t()) :: policy() | {:error, :event_sink_error}

Returns the configured loss policy.

start(policy, limits, opts \\ [])

@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 nothing. 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.

stop(sink)

@spec stop(t()) :: :ok

Stops the sink. Calling it after owner-driven shutdown is harmless.