3.2 KiB
Internal Execution Observation
internal/observation owns one invocation's run ID, presence-aware token
aggregation, measured phase totals, and synchronous metadata event delivery.
Its event values and callback type live in internal/domain so internal
requests can carry them without depending on the recorder package. The
recorder supplies run IDs to the runner and receives attempt and
retry-delay measurements from the generation coordinator. Ordinary Run
lifecycle instrumentation spans the facade and runner boundaries.
Prepared execution starts only after its private payload is atomically claimed;
the facade receives that invocation's recorder privately and emits the terminal
event after public error mapping. Failed claims and preparation emit nothing.
The facade masks inherited recorder and prepared-claim state when entering preparation or execution. Delegated calls from an injected collaborator retain the caller's cancellation, deadline, and unrelated context values, but do not reuse the enclosing invocation's accounting. Only the new request's observer (or the claimed handle's retained observer) enables its observation lifecycle.
A recorder keeps only counters, resolved identity fields, and the selected callback. It has no global history, queue, goroutine, or mutex held across a callback. The caller supplies normalized failure metadata; the recorder never parses an error string or receives provider bodies, credentials, headers, or other content. Events are values with no mutable containers. Callback panics propagate to the caller. Per-operation callbacks are ordered and synchronous; different operations may invoke the same callback concurrently. The recorder marks each measured phase's end before delivery, so callback work does not inflate provider duration. Terminal phase durations sum measured phases, while wall duration may also include preparation, validation, and callbacks. Panics do not promise a terminal event.
Attempt usage is known when its explicit presence bit is true. For legacy
injected clients without presence metadata, nonzero counts are known and
zeros are unknown. Aggregate values sum known contributions; Known means
at least one reported value, while Complete means every dispatched attempt
reported the field. Zero dispatched attempts produce known, complete zero
totals. Non-dispatched acquisitions contribute capacity wait but no usage or
generation duration. Terminal totals count dispatched attempts, transient
attempts above the first in a generation, and repair generations with at least
one dispatch. A terminal event is an aggregate and must not be added to its
attempt events.
Smoke diagnostics mask inherited execution-recorder state while invoking
generation or HTTP collaborators. Their private attempt evidence is assembled
into a SmokeTestReport; it does not create ordinary run events or enter an
enclosing run's observation totals.
The recorder tests own usage presence, phase sums, event ordering, empty-run accounting, identity snapshots, and callback panic behavior. The generation coordinator owns attempt and retry-delay measurements and emits their completion events after releasing active permits.