Find what's slow

Watch the counters

datumhue.stat reads a performance counter while your app runs. Two of them are about your app alone:

"cpu" near 1 means your app alone used all the time a frame gives scripts, and its work starts to spill into later frames. It is the raw value of one frame, so smooth it before you show it. This program shows a smoothed reading in a label:

local label = datumhue.ui.root:label({ text = "measuring" })
local cpu = 0

datumhue.on_update(function()
    cpu = cpu + (datumhue.stat("cpu") - cpu) * 0.05
end)

datumhue.time.every(0.25, function()
    local kib = math.floor(datumhue.stat("memory") / 1024)
    label.text = string.format("scripts %.1f%%, %d KiB", cpu * 100, kib)
end)

In this example: datumhue.ui.root UiElement:label datumhue.on_update datumhue.stat datumhue.time.every UiElement.text

• The per-frame handler moves the reading 5% of the way to each new value, which smooths out single slow frames.
• The timer writes the label four times a second, so the text stays readable.

datumhue.stat("fps") and datumhue.stat("frame_time") read the whole workstation's frame rate and frame time in seconds, both smoothed.

Record a profile

A profile shows which of your functions take the time. Run the app with --profile, make the slow moment happen, then quit:

$ datumhue run ballpit --profile ballpit.json
$ datumhue run ballpit --profile ballpit.json --open
$ datumhue pkg test ballpit --profile suite.json

• --profile writes a sampling profile when the run ends, one per app, in the speedscope format: open it in a viewer for that format to see each app's flame graph over time.
• --profile-summary with a second file name also writes a plain JSON table: each function's call count and its own and total time, with frame-time figures, to compare runs with a script.
• --report with a file name writes the profile as a web page: each app's frame-time figures and its functions, hottest first. --open writes the page and opens it in your browser.

On datumhue pkg test, the same flags profile the test suite, a repeatable workload to track over time; the profile joins the suite's report page as a section of its own (Test a package).

See also

• Test a package
• Debug an app
• How your app runs

Reference used on this page: datumhue.ui.root UiElement:label datumhue.on_update datumhue.stat datumhue.time.every UiElement.text