luau_profile Module

Public Luau surface over the __luau_profile Internal FFI namespace — sampling profiler + manual regions for Luau scripts.

Purpose

Wrap the raw __luau_profile.* FFI namespace in a typed Luau table that gets auto-injected as _G.luau_profile via the prelude. Two complementary modes share one accumulator:

• Sampling profiler. Background OS thread samples the active Luau stack at a configurable rate. Output is the upstream folded-stack format so tools/perfgraph.py can render SVG flamegraphs. Time spent inside an engine binding (an FFI call, require with its compile, loadstring, a VFS read) is charged to the Luau stack that called it, under a [C],<binding>,, frame, and time inside a Luau library function (table.sort, string.rep) to the function that called it; only time with no Luau running and no binding open is charged to [engine],native,,.
• Manual regions. Synchronous begin(name) -> id / end_region(id) pair plus a span(name, fn, ...) wrapper. Works on every platform (the sampler is native-only).

Usage

-- Sampler (native only)
if luau_profile.sampling_available() then
    luau_profile.start(1000)
    runWorkload()
    luau_profile.stop()
    -- The profile as data: keep it in the engine filesystem, where `bash`
    -- and `vfs.read` reach it.
    vfs.write("/source/tmp/profile.folded", luau_profile.folded())
end

-- Manual regions (every platform)
local id = luau_profile.begin("walk")
runWalk()
luau_profile.end_region(id)

-- Scoped form (handles errors)
local result = luau_profile.span("walk", function() return walk() end)

-- In-engine UI polling — cheap, no filesystem
for _, s in ipairs(luau_profile.snapshot(10).stacks) do print(s.stack, s.self_us) end

Exports

• luau_profile.start(hz?) -> StartResult / stop() / is_running() -> boolean / reset() / sampling_available() -> boolean.
• luau_profile.snapshot(top_n?) -> Snapshot — in-process snapshot.
• luau_profile.folded() -> string — the folded-stack text, for the caller to place: vfs.write puts it in the engine filesystem.
• luau_profile.dump(path) -> DumpResult / luau_profile.dump_regions(path) -> DumpRegionsResult — the HOST filesystem, present in the trusted VM alone. An engine path (/zero/..., /source/...) is refused by name.
• luau_profile.begin(name) -> number / end_region(id) / span(name, fn, ...) -> ....