Insider.Collector.Session (Insider v0.1.0)

Copy Markdown View Source

Host-owned, opt-in composition of bounded development/test/CI collectors.

This is not a transport, deployment, tracing, mutation, or production enablement API. Its opaque handle is a local ownership capability; callers must not serialize or forward it outside their trusted host boundary.

See Supervised collector sessions for the collectors, bounds, and ownership rules.

Summary

Functions

Flushes bounded collector inboxes and returns fixed-schema scalar accounting.

Drains the bounded Logger and Telemetry inboxes and returns scalar ingress accounting.

Reads redacted recorder events after cursor, without a freeze trigger.

Records one event that a caller outside the collectors built, such as a live one-shot inspection, into the running session's Recorder.

Stops the session's ingress for good and keeps its Recorder readable.

Types

receipt()

@type receipt() :: map()

Functions

flush_evidence(handle, timeout_ms \\ 5000)

@spec flush_evidence(Insider.Collector.Session.Handle.t(), pos_integer()) ::
  {:ok, map()} | {:error, term()}

Flushes bounded collector inboxes and returns fixed-schema scalar accounting.

The result excludes event bodies, payloads, process handles, and raw status maps. A successful call permanently quiesces the session Poller before draining currently visible Logger and Telemetry inbox entries and sampling Recorder counters. Empty visible inboxes do not prove that concurrent application emitters stopped; terminal cleanup still requires stop/1 or kill/1.

flush_ingress_evidence(handle, timeout_ms \\ 5000)

@spec flush_ingress_evidence(Insider.Collector.Session.Handle.t(), pos_integer()) ::
  {:ok, map()} | {:error, term()}

Drains the bounded Logger and Telemetry inboxes and returns scalar ingress accounting.

This is a nonterminal workload-boundary operation. It does not inspect or quiesce the Poller, does not inspect the Recorder, and cannot prove that external emitters have paused.

health(handle)

@spec health(Insider.Collector.Session.Handle.t()) :: {:ok, map()} | {:error, term()}

kill(handle)

@spec kill(Insider.Collector.Session.Handle.t()) ::
  {:ok, receipt()} | {:error, term()}

read_events(handle, cursor, options \\ [])

@spec read_events(
  Insider.Collector.Session.Handle.t(),
  non_neg_integer() | :latest,
  keyword()
) ::
  {:ok, map()} | {:error, term()}

Reads redacted recorder events after cursor, without a freeze trigger.

The call first drains the visible Logger and Telemetry inboxes, then reads the session Recorder with Insider.Recorder.read_since/3 and passes every returned event through Insider.Redaction under the session's trusted recorder classification policy. An event whose redaction fails is withheld and counted in "redaction_withheld" (its receipt is listed in "withheld_receipts"); its receipt still advances the cursor. Cursor :latest is the newest receipt after the drain, so the read returns no events and "cursor" reports where it started.

The result also carries cumulative scalar loss accounting: exact receipt eviction for the read range, Recorder admission counters, and the Logger, Telemetry, and Poller ingress counters, so callers can report every gap. Options: :limit (1..1,000), :max_bytes (1..16 MiB), and :timeout_ms (1..5,000, default 5,000). A redaction deadline truncates the batch. "truncated_by" names what ended a truncated read: "limit", "max_bytes", or "deadline" (otherwise nil).

record_event(handle, event, timeout_ms \\ 5000)

@spec record_event(
  Insider.Collector.Session.Handle.t(),
  Insider.Event.t(),
  pos_integer()
) ::
  :ok | {:dropped, atom()} | {:error, term()}

Records one event that a caller outside the collectors built, such as a live one-shot inspection, into the running session's Recorder.

The session process records it, so it is serialised with the seal: after seal_ingress/2 it is refused with :sealed. Returns :ok, the Recorder's {:dropped, reason}, or {:error, reason}.

seal_ingress(handle, timeout_ms \\ 5000)

@spec seal_ingress(Insider.Collector.Session.Handle.t(), pos_integer()) ::
  {:ok, map()} | {:error, term()}

Stops the session's ingress for good and keeps its Recorder readable.

The Poller stops, the Telemetry handler is detached before its inbox is drained, and the Logger filter is removed before its inbox is drained, so after the reply nothing more is recorded and every event that was admitted is in the Recorder. read_events/3 keeps working; stop/1 or kill/1 still ends the session, and its receipt reports each component's cleanup as it was at the seal. The live owner seals a session before it copies it for the last time, so no recorded event is lost to a stop.

start(host_policy, options)

@spec start(Insider.Runtime.HostPolicy.t(), keyword()) ::
  {:ok, Insider.Collector.Session.Handle.t()} | {:error, term()}

stop(handle)

@spec stop(Insider.Collector.Session.Handle.t()) ::
  {:ok, receipt()} | {:error, term()}