37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# 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 currently supplies run IDs to the runner and receives attempt and
|
|
retry-delay measurements from the generation coordinator. Run lifecycle
|
|
instrumentation for ordinary `Run` runs at 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
The [recorder tests](../../internal/observation/recorder_test.go) own usage
|
|
presence, phase sums, event ordering, empty-run accounting, identity snapshots,
|
|
and callback panic behavior. The [generation coordinator](generation.md) owns
|
|
attempt and retry-delay measurements and emits their completion events after
|
|
releasing active permits.
|