Documentation
¶
Overview ¶
Package counts is the Durable core's deterministic count gate (Durable plan 2, item 9) and its flight recorder format.
A run of the production native stack (sqlhost on SQLite, the driver, the bench workload on a fixture of N turns) is recorded as the stream of everything the core was given: its events, the answers to its pig.read calls and the ids pig.uuidv7 returned. The core is a pure function of that stream (ABI section 3, ADR D8: the clock and randomness are inputs), so Replay drives the same core again with no storage, no model and no goroutines, as the native build and as the Go and TinyGo Wasm builds, and counts what it costs: rows read and written, crossings, bytes allocated, mallocs, the live set, the Wasm linear memory high-water and, on an instrumented module, Wasm instructions. Every count is a function of the stream and the binary, never of the clock or the machine. A replay also compares each step with the step the recorded run produced, so a count is never reported for a core that behaved differently.
The same stream is the deterministic replay of a trap report (host/cf/src/observe.ts writes it): a stream captured from a failing Durable Object replays here under a debugger.
Index ¶
- Constants
- func Cells(size int, phases map[string]Metrics) map[string]map[string]int64
- func LiveCurve(intervals []Interval) []int64
- func Phases(intervals []Interval) map[string]Metrics
- func SteadyGrowth(live []int64) int64
- type Entry
- type Interval
- type Item
- type Mark
- type Metrics
- type ReadCall
- type Recorder
- type Recording
- type RecordingStepper
- type ReplayError
- type WasmOptions
Constants ¶
const ( // ItemABI is the abi_id the core spoke: 64 ASCII bytes, first in the file. ItemABI byte = iota + 1 // ItemEvent is one event delivered to the core: u8 event kind, f64 now, the wire payload (abi.Event.Wire). ItemEvent // ItemRead is one pig.read call the core made during the step of the last event: u32 request length, the request // (abi.AppendReadRequest), the answer (abi.AppendAnswer). ItemRead // ItemUUID is one pig.uuidv7 value the core asked for during the step: 36 ASCII bytes. ItemUUID // ItemStep is the SHA-256 of the step the core returned for the last event, in its wire form (abi.AppendStep). ItemStep // ItemMark names a boundary of the workload: u8 name bytes. ItemMark // ItemRowsChanged is the rows the host's store changed applying the commits of the last step: u64. It is a record of the // host, not an input of the core. ItemRowsChanged )
Item kinds of a recording. A recording is a sequence of items, each u8 kind, u32 body length, body (little endian).
Variables ¶
This section is empty.
Functions ¶
func Cells ¶
Cells turns the phases of a size into the flattened cells of the contract's count baseline: "impl/size" to "cold.metric" and "warm.metric". Only the counts that replay measures and the contract's own counters do not are exported; "turns" and the per-interval gauges stay in the report.
func Phases ¶
Phases folds the intervals of a workload into the two the gate reports, the ones durable/contract/cli/counts.mjs calls cold and warm: "cold" is everything up to the end of the first measured turn (the open and the first turn), "warm" every later turn, summed. Warm also carries "<scope>.liveGrowthPerTurn" (liveGrowth): the growth of the live set per turn across the warm turns, the figure that is zero when a turn with no live work retains nothing, and "turns", the warm turns.
func SteadyGrowth ¶
SteadyGrowth is the live set's growth per turn over the second half of the turns: what a conversation still keeps once its first turns have built whatever a context window needs. It reads the half with liveGrowth, the one estimator of the gate, so one object a conservative collector keeps at a single reading does not count. A flat curve is 0; a falling one is negative.
Types ¶
type Entry ¶
type Entry struct {
Kind abi.EventKind
Now float64
Wire []byte
Reads []ReadCall
UUIDs []string
Digest [sha256.Size]byte
// Verified is whether the recording holds the step the core returned. A recording the host's flight recorder wrote does
// not (it never hashes a step): its replay runs the core on the inputs and compares nothing.
Verified bool
RowsChanged uint64
}
Entry is one event with what the core asked for while it ran and what it returned.
type Interval ¶
Interval is the counts between one mark of the workload and the next.
func Merge ¶
Merge combines two passes over the same recording, interval by interval; a metric both report keeps a's value.
func ReplayNative ¶
ReplayNative drives the native core through the recording and returns the storage counts (which every build shares) and the native build's own: bytes allocated and mallocs inside Step, and the live set (the heap after a collection, less what the replay held before it started) at the end of each interval. The host side of a step, decoding the event and the read answers, happens outside the measured region.
func ReplayWasm ¶
func ReplayWasm(ctx context.Context, rec *Recording, wasm []byte, o WasmOptions) ([]Interval, error)
ReplayWasm drives one Wasm core through the recording under wazero and returns its counts per interval. Every step is compared with the step of the recorded run.
func SettleWarm ¶
SettleWarm drops the first n warm turns of a workload (the turns after the cold one), so Phases folds only the later ones. It serves the gate's live-set window: a live set that rises in a few bounded steps early (a buffer or table reaching its working capacity) and then stays flat is not growth, and the slope over the settled turns reads it as zero, while retention that every turn adds shows in any window. Fewer warm turns than n leave none.
type Metrics ¶
Metrics are the counts of one interval of a replay, by name. A name is "<scope>.<metric>": scope "storage" (what the host stores and serves, the same for every build), "native", "tinygo" or "go". Counters add across intervals; gauges (the live set, linear memory) take their value at the end of the last one.
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder writes a recording. Its methods are safe for concurrent use: the owner goroutine of a host records events, and the workload records marks between turns.
func NewRecorder ¶
NewRecorder starts a recording at path.
func (*Recorder) RowsChanged ¶
RowsChanged records the rows the store changed for the commits of the last step.
type Recording ¶
type Recording struct {
ABI string
Entries []Entry
// Marks[i] names the boundary before Entries[At]; a mark after the last event has At == len(Entries).
Marks []Mark
}
Recording is a loaded recording, grouped by event.
type RecordingStepper ¶
type RecordingStepper struct {
// contains filtered or unexported fields
}
RecordingStepper is a core.Session that records what it is given.
func (*RecordingStepper) SetReader ¶
func (s *RecordingStepper) SetReader(read core.Reader)
SetReader installs the host's read, recording each request and answer.
type ReplayError ¶
ReplayError is a replay that stopped because the core did not do what the recorded run did.
func (*ReplayError) Error ¶
func (e *ReplayError) Error() string
type WasmOptions ¶
type WasmOptions struct {
// Build names the scope of the metrics: "tinygo" or "go".
Build string
// Allocs counts calls of the runtime's allocator by name (TinyGo keeps the name section: runtime.alloc,
// runtime.growHeap and runtime.runGC, which every collection cycle runs, the allocator's own and an explicit one). A module without the names reports no allocation counts.
Allocs bool
// Live asks the core for mem_stats at the end of every interval: its live heap after a full collection.
Live bool
// Fuel instruments the module (fuel.Instrument) and reports instructions per interval.
Fuel bool
}
WasmOptions choose what one pass over a Wasm core measures. The passes are separate because each perturbs the run: a listener on every allocation slows it, mem_stats collects garbage, and an instrumented module is a different binary.