luau_profile

The luau_profile namespace — 10 functions.

globals/luau_profile/begin

globals/luau_profile/begin(name: string) -> number

Open a named manual region. Returns an opaque integer id; pass it back to end_region(id) to close and record elapsed wall-clock under name.

globals/luau_profile/dump

globals/luau_profile/dump(path: string) -> DumpResult

Write the folded-stack dump to path, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged.

globals/luau_profile/dump_regions

globals/luau_profile/dump_regions(path: string) -> DumpRegionsResult

Write per-region stats to path as JSON.

globals/luau_profile/end_region

globals/luau_profile/end_region(id: number)

Close a region previously opened by begin(name). Records elapsed wall-clock under the region's name. Silently no-ops on unknown id (typically a double-close or swapped-out VM).

globals/luau_profile/is_running

globals/luau_profile/is_running() -> boolean

True iff the background sampler is currently running.

globals/luau_profile/reset

globals/luau_profile/reset()

Clear every accumulated sample and region stat. The sampler keeps running if it was already on; only the data is wiped.

globals/luau_profile/sampling_available

globals/luau_profile/sampling_available() -> boolean

True on platforms where the background sampler can run (native targets), false on WASM. Manual regions work everywhere — only the sampler is platform-gated.

globals/luau_profile/snapshot

globals/luau_profile/snapshot(top_n: number?) -> Snapshot

Snapshot the current accumulator without touching the filesystem — cheap enough for per-frame UI polling. top_n truncates stacks to the N hottest entries; omitting it returns all stacks sorted descending by self_us. regions is always returned in full (sorted by total_us).

globals/luau_profile/start

globals/luau_profile/start(hz: number?) -> StartResult

Start the background Luau sampling profiler at hz samples per second (default 1000, clamped to [1, 100000]). Idempotent — calling while already running is a no-op. Returns { available, hz } — available = false on WASM (no std::thread). Manual regions work regardless.

globals/luau_profile/stop

globals/luau_profile/stop()

Stop the background sampler. Blocks until the sampler thread joins (typically <1ms). Safe when not running. Does not clear the accumulator — call reset() to drop samples.