luau_profile

The luau_profile namespace — 35 functions.

globals/luau_profile/begin

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.

Parameters

• name string — Region name; aggregated across opens.

Returns number — Region id.

local id = luau_profile.begin("walk"); ...; luau_profile.end_region(id)

globals/luau_profile/dump

luau_profile.dump(path: string) -> DumpResult

Write the folded-stack dump to path on the HOST filesystem, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged. A path naming the engine filesystem (/zero/..., or a bare root such as /source/...) is refused, and says so: luau_profile.folded() with vfs.write puts the dump there.

Parameters

• path string — Absolute host filesystem path to write.

Returns DumpResult — { ok, path, samples, stacks, bytes }.

local r = luau_profile.dump("/tmp/profile.folded")

globals/luau_profile/dump_regions

luau_profile.dump_regions(path: string) -> DumpRegionsResult

Write per-region stats to path as JSON, on the HOST filesystem. A path naming the engine filesystem is refused, the same way dump refuses one.

Parameters

• path string — Absolute host filesystem path to write.

Returns DumpRegionsResult — { ok, path, regions, bytes }.

luau_profile.dump_regions("/tmp/regions.json")

globals/luau_profile/end_region

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).

Parameters

• id number — Region id returned by begin().

luau_profile.end_region(id)

globals/luau_profile/folded

luau_profile.folded() -> string

The folded-stack dump as a string, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged. The same bytes dump writes, handed back instead of written, so the profile can go wherever the caller keeps it: vfs.write puts it in the engine filesystem, where bash and vfs.read reach it.

Returns string — Folded-stack text; empty when nothing was sampled.

vfs.write("/source/tmp/sample.folded", luau_profile.folded())

globals/luau_profile/is_running

luau_profile.is_running() -> boolean

True iff the background sampler is currently running.

Returns boolean — Sampler running state.

if luau_profile.is_running() then luau_profile.stop() end

globals/luau_profile/reset

luau_profile.reset()

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

luau_profile.reset()

globals/luau_profile/sampling_available

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.

Returns boolean — Whether start() would actually spawn a sampler.

if luau_profile.sampling_available() then luau_profile.start() end

globals/luau_profile/snapshot

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).

Parameters

• top_n number (optional) — Truncate stacks to this many entries; omit for all.

Returns Snapshot — Profile snapshot.

local snap = luau_profile.snapshot(10)

globals/luau_profile/start

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.

Parameters

• hz number (optional) — Sampling rate in Hz.

Returns StartResult — Effective sampler state.

luau_profile.start(500)

globals/luau_profile/stop

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.

luau_profile.stop()

modules/luau_profile/README

require("@builtin/modules/api/engine/luau_profile") -- luau_profile (also available as global 'luau_profile')

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

Usage: local luau_profile = require("@builtin/modules/api/engine/luau_profile") Also available as global: luau_profile

modules/luau_profile/begin

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.

Parameters

• name string — Region name; aggregated across opens.

local id = luau_profile.begin("walk"); ...; luau_profile.end_region(id)

modules/luau_profile/dump

dump(path: string): DumpResult

Write the folded-stack dump to path on the HOST filesystem, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged. A path naming the engine filesystem (/zero/..., or a bare root such as /source/...) is refused, and says so: luau_profile.folded() with vfs.write puts the dump there.

Parameters

• path string — Absolute host filesystem path to write.

local r = luau_profile.dump("/tmp/profile.folded")

modules/luau_profile/dump_regions

dump_regions(path: string): DumpRegionsResult

Write per-region stats to path as JSON, on the HOST filesystem. A path naming the engine filesystem is refused, the same way dump refuses one.

Parameters

• path string — Absolute host filesystem path to write.

luau_profile.dump_regions("/tmp/regions.json")

modules/luau_profile/end_region

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).

Parameters

• id number — Region id returned by begin().

luau_profile.end_region(id)

modules/luau_profile/folded

folded(): string

The folded-stack dump as a string, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged. The same bytes dump writes, handed back instead of written, so the profile can go wherever the caller keeps it: vfs.write puts it in the engine filesystem, where bash and vfs.read reach it.

vfs.write("/source/tmp/sample.folded", luau_profile.folded())

modules/luau_profile/is_running

is_running(): boolean

True iff the background sampler is currently running.

if luau_profile.is_running() then luau_profile.stop() end

modules/luau_profile/reset

reset()

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

luau_profile.reset()

modules/luau_profile/sampling_available

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.

if luau_profile.sampling_available() then luau_profile.start() end

modules/luau_profile/snapshot

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).

Parameters

• top_n number? (optional) — Truncate stacks to this many entries; omit for all.

local snap = luau_profile.snapshot(10)

modules/luau_profile/span<T...>

span<T...>(name: string, fn: () -> T..., ...): T...

Call fn(...) inside a manual region named name. The region is closed even if fn raises (the call goes through pcall internally). Returns whatever fn returned.

Parameters

• name string — Region name.
• fn () -> T... — Function to invoke with the trailing varargs.

local r = luau_profile.span("walk", function() return walk() end)

modules/luau_profile/start

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.

Parameters

• hz number? (optional) — Sampling rate in Hz.

luau_profile.start(500)

modules/luau_profile/stop

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.

luau_profile.stop()

typed/builtin//modules/api/engine/luau_profile/luau_profile/begin

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.

Parameters

• name string — Region name; aggregated across opens.

Returns number — Region id.

local id = luau_profile.begin("walk"); ...; luau_profile.end_region(id)

typed/builtin//modules/api/engine/luau_profile/luau_profile/dump

luau_profile.dump(path: string) -> DumpResult

Write the folded-stack dump to path on the HOST filesystem, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged. A path naming the engine filesystem (/zero/..., or a bare root such as /source/...) is refused, and says so: luau_profile.folded() with vfs.write puts the dump there.

Parameters

• path string — Absolute host filesystem path to write.

Returns DumpResult — { ok, path, samples, stacks, bytes }.

local r = luau_profile.dump("/tmp/profile.folded")

typed/builtin//modules/api/engine/luau_profile/luau_profile/dump_regions

luau_profile.dump_regions(path: string) -> DumpRegionsResult

Write per-region stats to path as JSON, on the HOST filesystem. A path naming the engine filesystem is refused, the same way dump refuses one.

Parameters

• path string — Absolute host filesystem path to write.

Returns DumpRegionsResult — { ok, path, regions, bytes }.

luau_profile.dump_regions("/tmp/regions.json")

typed/builtin//modules/api/engine/luau_profile/luau_profile/end_region

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).

Parameters

• id number — Region id returned by begin().

luau_profile.end_region(id)

typed/builtin//modules/api/engine/luau_profile/luau_profile/folded

luau_profile.folded() -> string

The folded-stack dump as a string, one line per stack as <ticks> <stack_csv> — the format upstream Luau emits and tools/perfgraph.py consumes unchanged. The same bytes dump writes, handed back instead of written, so the profile can go wherever the caller keeps it: vfs.write puts it in the engine filesystem, where bash and vfs.read reach it.

Returns string — Folded-stack text; empty when nothing was sampled.

vfs.write("/source/tmp/sample.folded", luau_profile.folded())

typed/builtin//modules/api/engine/luau_profile/luau_profile/is_running

luau_profile.is_running() -> boolean

True iff the background sampler is currently running.

Returns boolean — Sampler running state.

if luau_profile.is_running() then luau_profile.stop() end

typed/builtin//modules/api/engine/luau_profile/luau_profile/reset

luau_profile.reset()

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

luau_profile.reset()

typed/builtin//modules/api/engine/luau_profile/luau_profile/sampling_available

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.

Returns boolean — Whether start() would actually spawn a sampler.

if luau_profile.sampling_available() then luau_profile.start() end

typed/builtin//modules/api/engine/luau_profile/luau_profile/snapshot

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).

Parameters

• top_n number (optional) — Truncate stacks to this many entries; omit for all.

Returns Snapshot — Profile snapshot.

local snap = luau_profile.snapshot(10)

typed/builtin//modules/api/engine/luau_profile/luau_profile/start

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.

Parameters

• hz number (optional) — Sampling rate in Hz.

Returns StartResult — Effective sampler state.

luau_profile.start(500)

typed/builtin//modules/api/engine/luau_profile/luau_profile/stop

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.

luau_profile.stop()