58 lines
3.4 KiB
Markdown
58 lines
3.4 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 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.
|
|
Resolved prompt and profile IDs are the exact runtime identities selected for
|
|
the invocation, including namespace qualification when supplied by an engine
|
|
view. A prompt's optional version label is descriptive metadata, not a
|
|
selection key.
|
|
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](../../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.
|