Module observe 

Typed runtime and policy observations, separate from effect replay records. Witness receives facts and ObservationLog retains a bounded trace. Optional timestamps come from a host-supplied Clock, not replay identity.

use rig_core::observe::ObservationLog;

let log = ObservationLog::with_capacity(128);
log.finalize();
assert!(log.trace().finalized);

Structs

AdapterAnalysis

Analysis-only response metadata. Never use identifiers as operation join keys.

AdapterContext

A caller-supplied witness and logical operation identity.

AdapterErrorEnvelope

Original provider error-envelope fields, separate from Rig retry classification.

AdapterObservation

One fact about a provider operation, independently of its effect record.

AdapterUsage

The counters of the Usage the decoder normalized into the reply’s end, observed once when the reply ends; an attempt that fails before its end observes none. Unreported is None.

AdapterVerdict

Sparse provider metadata: a present field supersedes its previous value.

Emitter

Stable emitter name and optional version.

Observation

One observed fact.

ObservationLog

The bounded in-memory sink, in one of two shapes. A capture (Self::with_capacity, the default) keeps the first capacity facts and counts the rest as dropped: the trace is a complete prefix or says how much of the session it missed, which is what a comparison wants. A ring (Self::ring) keeps the last capacity facts and counts what it let go: a long-running host always sees its recent past, which is what a dashboard wants. Either way Self::drain takes what is kept and starts over, so a host that exports periodically never fills up.

ObservationSink

Where a payload projector writes its observation facts.

ObservationTrace

The serializable trace a sink produces: the analysis artifact.

Reason

A structured reason: a stable code and an optional free-text detail. The code is what a comparison keys on; the detail is for a reader.

Subject

What an observation is about. Every field is optional because facts exist before an effect has an id (a gate decides a pending intent), and some have no effect at all (a run ending). Correlation never depends on a runtime handle: scope is the program’s serde id, order the driver’s dispatch order, effect/parent the record’s ids.

Enums

Action

The fact: one the provider request boundary saw, or a host’s own (Action::Host).

AdapterEnding

How a provider attempt closed, distinct from the run’s ending.

AdapterErrorBoundary

Boundary identified by the adapter’s original typed error, not its message.

AdapterEvent

Metadata from the provider boundary. Request/response bodies are not included.

Stage

Where a fact was seen: the handler side (the provider request boundary), or the host.

Constants

DEFAULT_CAPACITY

The default capacity of an ObservationLog.

Traits

Clock

A host-owned monotonic clock: what a sink stamps Observation::at from. rig-core reads no clock itself; a test supplies a counter.

HostAction

A host-defined action: a named, serde-typed fact a host policy emits through Action::Host. The kind is declared once per type, so a trace names every host fact and a consumer deserializes it back.

Witness

Where observations go: the seam a driver and a host emit through. A witness is shared, so it takes &self; it must never block the caller.

Functions

diagnostic_url_secrets

The secrets a URL carries for diagnostic redaction: userinfo and known credential query parameters, origin-form request URIs included. The returned values are secrets: keep them runtime-only and never write them into a diagnostic or an artifact.

scrub_diagnostic

Bounds diagnostic text and removes control characters. Known credentials or credential markers redact the whole message; oversized messages are replaced rather than truncated to a potentially sensitive prefix.