Profile
System.Profile is a builtin member of System; it needs no import. System.Profile.measure names a section of a program for the profile, and System.Profile.steps counts the steps of the running task. Both work the same whether the profile is on or off, so they can stay in the code.
Steps are the unit of work of the VM: the entries that --max-steps counts. They repeat exactly from run to run, so they are the numbers to compare. Wall time changes with the machine and its load.
System.Profile.measure #
System.Profile.measure(label: String, block: Fn[T]) -> TRuns the block once and gives back its value. The block takes no parameters; a function value of no parameters works too (System.Profile.measure("load", &load)).
def total(n: Int) -> Int
sum = 0
for k in 0...n
sum += k
end
sum
end
def main() -> Void
t = System.Profile.measure("total") do total(1000) end
puts(t)
end499500A block that uses try gives a Result. Give the call a Result type, so the block knows it gives one:
def parse(text: String) -> Result[Int]
n = try text.to_i
ok(n)
end
def main() -> Void
r: Result[Int] = System.Profile.measure("parse") do
a = try parse("12")
b = try parse("30")
ok(a + b)
end
puts(r.unwrap_or(0))
end42Without the profile, a measure is one block call: one step and the block’s own work. With the profile on (below), each label gets a section row:
calls: how many times a measure of the label ran.steps,us,gc_ms: the steps of the task, the wall time in microseconds and the garbage collector’s time in milliseconds, from the start of the block to its end.
Sections are inclusive: a section holds the sections nested in it, so outer below counts the steps of both inner calls too. A label that runs inside itself in the same task (recursion) counts every call, but its steps and time only once, for the outermost call. Steps are those of the task that runs the measure, so a measure in a task counts only that task’s steps; time is wall time, and it goes on while the task waits. A measure whose block ends in a runtime error or a cancel counts as a call with no steps.
def work(n: Int) -> Int
sum = 0
i = 0
while i < n
sum += i
i += 1
end
sum
end
def main() -> Void
both = System.Profile.measure("outer") do
a = System.Profile.measure("inner") do work(100) end
b = System.Profile.measure("inner") do work(200) end
a + b
end
puts(both)
end24850System.Profile.steps #
System.Profile.steps() -> IntThe steps the running task has run so far. The count is the same on every run of the same work, with or without the profile, so a test can hold code to a step budget. Each task has its own count.
def work(n: Int) -> Int
sum = 0
for k in 0...n
sum += k
end
sum
end
def cost(n: Int) -> Int
before = System.Profile.steps()
work(n)
System.Profile.steps() - before
end
def main() -> Void
puts(cost(100) == cost(100))
puts(cost(200) > cost(100))
endtrue
trueThe profile report #
Set AGENTICA_VM_TRACE=profile to get a report on stderr when the run ends (AGENTICA_VM_TRACE_FILE=PATH writes it to a file instead). After the rows of functions, files and builtins come up to 30 section rows, the most steps first:
AGENTICA_VM_TRACE=profile agentica sections.agc
...
agc-trace +0.004012 profile section calls=1 steps=2241 us=33 gc_ms=0 name=outer
agc-trace +0.004015 profile section calls=2 steps=2228 us=31 gc_ms=0 name=inneragentica FILE.agc prints two reports, the front end’s and then the program’s; the sections are in the program’s.
A program that calls a native module also gets one native row per module function that ran, such as native calls=2 us=48 mode=dirty name=crunch module=demo: its calls, the microseconds spent in C, and whether it is a short or a dirty function.
The report ends with what the VM ran, for work on the VM itself: an events line (instructions, frame reloads and how builtin calls went), an op row for each opcode with its share of the instructions, and the 20 most common pair rows of two opcodes run one after the other.
A run keeps up to 4096 labels. Every label after that counts in one [overflow] section (the frame measure[overflow] in folded stacks), so a label built from data, such as "item #{i}", cannot grow the profile without bound.
One file for each process #
A test run starts many VMs (the front end, the runner, each test file, the program under test), and they all get the same environment, so they all append to one AGENTICA_VM_TRACE_FILE. Write {pid} in the file name and each process replaces it with its own process id, so each writes a file of its own:
AGENTICA_VM_TRACE=profile AGENTICA_PROFILE_FORMAT=folded AGENTICA_VM_TRACE_FILE=/tmp/suite-{pid}.folded agentica test
ls /tmp/suite-*.foldedEvery {pid} in the name is replaced, however many there are, and the pattern works for every trace category and for the report as well as for folded stacks. A name that is 4096 bytes or longer after the replacement cannot be opened, and tracing is off, as for any other file that cannot be opened. The file is opened in append mode, so a process that reuses a pid appends to the old file: use an empty directory for each run. agentica test --timing shows which files and scenarios are slow, so you know which of the files to read.
Flame graphs #
Add AGENTICA_PROFILE_FORMAT=folded to the profile to get folded stacks instead of the report: one line per distinct stack, the frames from the outermost in, separated by ;, then a space and the weight in steps. flamegraph.pl, inferno and speedscope read this format.
AGENTICA_VM_TRACE=profile AGENTICA_PROFILE_FORMAT=folded AGENTICA_VM_TRACE_FILE=app.folded agentica app.agc
flamegraph.pl app.folded > app.svg
inferno-flamegraph app.folded > app.svgA file looks like this:
main@app.agc:25;measure:outer;block@app.agc:27:32;measure:inner;block@app.agc:28:34;work@app.agc:1 1000
main@app.agc:25;Int.times;block@app.agc:40:11 1000- A function is
name@FILE:LINE, a blockblock@FILE:LINE:COL, a lambdalambda@FILE:LINE:COL, a native loop or callback (Int.times,List.map) its builtin’s name, and aSystem.Profile.measuremeasure:LABEL. - The VM takes a sample of the running task’s stack every 1000 steps, each with a weight of 1000.
AGENTICA_PROFILE_SAMPLE=Nsets N (1 to 1000000000);AGENTICA_PROFILE_SAMPLE=1counts every step, and the weights then add up to the report’ssteps. - Sampling counts steps, not time, so the file is the same on every run of the same program, on every system. There is no time weight, since it would differ from run to run.
- Stacks deeper than 512 frames keep the outer and inner halves around a
...frame. A;, a%or a control character in a name is written as%XX(%3B,%25), so two different stacks never share a line. - The file keeps up to 1,048,576 distinct stacks (and 256 MiB of frames). Past that, the weight of each new stack goes to one
[truncated]line at the end, and anagc-trace folded profile fullline follows it. - Use
AGENTICA_VM_TRACE_FILE: on stderr, the lines mix with what the program writes there. Withagentica FILE.agc, the file holds the program’s stacks only;agentica check FILE.agcwrites the front end’s.
Linux perf #
The profile counts steps. To see where the CPU time goes, run the program under Linux perf with AGENTICA_PERF_MAP=1: the JIT then writes /tmp/perf-PID.map, one line for each function it compiles, and perf report shows those functions by name (agentica:NAME) instead of bare [JIT] addresses. The map is off by default and costs nothing when off; the file stays after the run, so remove it when you are done.
AGENTICA_PERF_MAP=1 perf record -g agentica app.agc
perf reportPerformance notes #
- With the profile off,
System.Profile.stepsis one builtin call; leaveSystem.Profile.measureandSystem.Profile.stepsin the code. - The profile counts every step and instruction and times every builtin call, so a profiled run is slower, most on a loop of cheap builtin calls such as String methods. Folded output adds more, the more often it samples.
- Rank by steps; use
usto compare builtins and sections in one run, and time the program without the profile. - The profile runs on one scheduler: a profiled run uses one unless
--schedulersorAGENTICA_SCHEDULERSasks for more, which it refuses.