counts

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 24 Imported by: 0

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

View Source
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

func Cells(size int, phases map[string]Metrics) map[string]map[string]int64

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 LiveCurve

func LiveCurve(intervals []Interval) []int64

LiveCurve is the native live set (bytes) after each measured turn, in turn order.

func Phases

func Phases(intervals []Interval) map[string]Metrics

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

func SteadyGrowth(live []int64) int64

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

type Interval struct {
	Name string
	M    Metrics
}

Interval is the counts between one mark of the workload and the next.

func Merge

func Merge(a, b []Interval) ([]Interval, error)

Merge combines two passes over the same recording, interval by interval; a metric both report keeps a's value.

func ReplayNative

func ReplayNative(rec *Recording) ([]Interval, error)

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

func SettleWarm(intervals []Interval, n int) []Interval

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 Item

type Item struct {
	Kind byte
	Body []byte
}

Item is one decoded item.

type Mark

type Mark struct {
	Name string
	At   int
}

Mark is a named boundary of the workload.

type Metrics

type Metrics map[string]int64

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 ReadCall

type ReadCall struct {
	Request []byte
	Answer  []byte
	Rows    int // rows in the answer
}

ReadCall is one pig.read call and the host's answer.

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

func NewRecorder(path string) (*Recorder, error)

NewRecorder starts a recording at path.

func (*Recorder) Close

func (r *Recorder) Close() error

Close finishes the recording and returns the first error of any write.

func (*Recorder) Mark

func (r *Recorder) Mark(name string)

Mark records a boundary of the workload.

func (*Recorder) RowsChanged

func (r *Recorder) RowsChanged(n uint64)

RowsChanged records the rows the store changed for the commits of the last step.

func (*Recorder) Stepper

func (r *Recorder) Stepper(inner *core.Session) *RecordingStepper

Stepper wraps a native session so the recording holds its events, its reads and its steps. It satisfies the sqlhost.Stepper of the host that drives it, and forwards SetReader.

func (*Recorder) UUID

func (r *Recorder) UUID(next func() string) func() string

UUID wraps the host's uuidv7 generator so each value the core takes is recorded.

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.

func Load

func Load(path string) (*Recording, error)

Load reads and groups a recording. Slices alias the file's bytes.

func Parse

func Parse(data []byte) (*Recording, error)

Parse groups a recording held in memory. Slices of the result alias data.

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.

func (*RecordingStepper) Step

func (s *RecordingStepper) Step(ev abi.Event) *abi.Step

Step records the event, delivers it and records the digest of the step.

type ReplayError

type ReplayError struct {
	Build string
	Entry int
	Kind  abi.EventKind
	What  string
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL