Module perf 

Perf traces as the contract hands them to agents (ADR-0046 §7): the frames’ records a session kept, read as a stream (PerfRead), summed up (summary), and written as JSON lines (lines).

run --perf answers a PerfSummary, and with --perf-out writes every kept frame as a line; the MCP server’s perf tool answers the records since a number.

In a debug build of a game’s tool program each record has the heap’s counts too (FrameRecord::heap), from the program’s own heap counter (shuyi_alloc_count::global), and the summary sums them up (HeapSummary). The counter counts the whole program: every thread’s allocations. Where it counts by memory tag, run --perf takes a heap snapshot before its script and one after its last frame, and the summary has what held the heap and what grew (add_heap); the trace file ends with the two snapshots and their diff (heap_lines).

Structs

HeapSummary

How the heap’s counts add up over a trace’s records, in bytes asked for.

PerfRead

The records a session kept from a number on: a read of its stream.

PerfSummary

What a trace’s records add up to.

SpanSummary

A span’s name and how its time adds up over the records.

Constants

HEAP_ROWS

How many of a snapshot’s rows, and of a diff’s, a PerfSummary keeps.

HEAP_THREADS

The limit of heap counts from this program’s own counter while it ran another thread beside the game’s.

HEAP_UNCOUNTED

The limit of records measured with no heap counts.

HEAP_UNTAGGED

The limit of heap counts with no snapshot by tag: the heap was counted, but not by memory tag.

RESET

The limit of a read whose since is past its next.

TEXT_CHANGES

How many of a diff’s changes the line for people names.

TIMES

The limit every answer with perf has: what its times are.

TOP_SPANS

How many of the spans with the most time a PerfSummary names.

Functions

add_heap

Adds the heap snapshots first (before a run) and last (after it) to summary: last’s first HEAP_ROWS rows, and the diff from first to last with its first HEAP_ROWS.

dropped_limit

The limit of a trace that dropped dropped earlier frames.

heap_limits

The limits of records’ heap counts: none counted, or counted by this program’s own counter (process) while another thread ran (other_threads).

heap_lines

The heap snapshots first and last as a trace’s last lines: a PerfLine::Snapshot each, then the PerfLine::Diff between them.

heap_summary

How the heap’s counts add up over the records that have them, or None for none.

heap_text

diff’s line for people: heap grew 120.0 KB from frame 0 to 600: update +96.0 KB, image +24.0 KB, ai +4.0 KB, its TEXT_CHANGES largest changes; heap shrank … for fewer bytes, heap held its size … for as many; None when nothing changed.

lines

records as a trace: a PerfLine::Frame each, as JSON, a line each, oldest first.

millis

us microseconds as milliseconds with one decimal, rounded to the nearest tenth, in integers: 1250 is 1.3.

note_other_thread

Notes that this program runs a thread beside the game’s, from now on.

other_threads

Whether this program ran a thread beside the game’s (note_other_thread).

summary

What records add up to, or None for no records; nothing dropped and no file.

text

summary’s line for people: perf: 600 frames, frame p50 1.2 ms p99 3.4 ms worst 8.0 ms; span ai 0.8 ms mean; heap peak 4.1 MB, then what grew in the heap (heap_text) and the trace file’s.

unmeasured_limit

The limit of a session that measured nothing after frames frames.