Raxol.AgentClientProtocol.Telemetry (Raxol Agent Client Protocol v0.1.0)

Copy Markdown View Source

The classified registry of every :telemetry event this package emits.

This module exists because the package already detected its own impossible states and then did nothing about them: Session emits [:raxol, :acp, :zero_updates_turn] (and logs a warning) when a turn completes without a single session/update for a non-empty prompt, and a bug that did exactly that shipped anyway -- because no test ever asserted on the event. Detection without enforcement is not a guard.

The three classes

  • :invariant -- can only fire if RAXOL ITSELF is wrong. Enforced: it must never fire during our own test run. Raxol.AgentClientProtocol.Test.InvariantSentinel turns any occurrence into a test failure.
  • :peer -- caused by the remote agent/client misbehaving: a malformed frame, an unknown notification, a duplicate or late id. Negative tests drive these on purpose. Not enforced.
  • :operational -- normal life: a delivery decision, backpressure shed, a policy verdict, an idle reap. Not enforced.

The classification criterion, applied literally

If a peer, the network, the filesystem, the clock, or a user of this library can cause the event, it is NOT an invariant. Err toward :peer or :operational: a false invariant makes the suite flaky and gets the whole mechanism deleted, which is strictly worse than a missed one.

Adding an event

The package's test suite parses lib/ for [:raxol, ...] event literals and fails if any is missing from events/0 (or if events/0 claims an event no source file mentions). A new event therefore cannot land without someone classifying it here, and the one-line WHY comment on each row below is the artifact that author reads.

Summary

Types

class()

Enforcement class. See the moduledoc for the criterion.

event()

Telemetry event name, as passed to :telemetry.execute/3.

Functions

classify(event)

The class of event, or nil when it is not registered.

events()

Every telemetry event this package emits, mapped to its enforcement class.

invariant_events()

The :invariant subset of events/0, sorted. This is what the sentinel arms.

Types

class()

@type class() :: :invariant | :peer | :operational

Enforcement class. See the moduledoc for the criterion.

event()

@type event() :: [atom()]

Telemetry event name, as passed to :telemetry.execute/3.

Functions

classify(event)

@spec classify(event()) :: class() | nil

The class of event, or nil when it is not registered.

events()

@spec events() :: %{required(event()) => class()}

Every telemetry event this package emits, mapped to its enforcement class.

invariant_events()

@spec invariant_events() :: [event()]

The :invariant subset of events/0, sorted. This is what the sentinel arms.