---
title: "luau_profile"
description: "The luau_profile namespace — the engine's Luau API reference for luau_profile."
section: "API Reference"
slug: "api-luau-profile"
canonical: "https://origozero.ai/docs/api-luau-profile"
updated: "2026-09-05T23:13:46.713875684+00:00"
tags: ["api", "reference"]
---

# luau_profile

The `luau_profile` namespace — 35 functions.

## globals/luau_profile/begin {#globals-luau-profile-begin}

```lua
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.

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

## globals/luau_profile/dump {#globals-luau-profile-dump}

```lua
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 }`.

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

## globals/luau_profile/dump_regions {#globals-luau-profile-dump-regions}

```lua
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 }`.

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

## globals/luau_profile/end_region {#globals-luau-profile-end-region}

```lua
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()`.

```lua
luau_profile.end_region(id)
```

## globals/luau_profile/folded {#globals-luau-profile-folded}

```lua
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.

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

## globals/luau_profile/is_running {#globals-luau-profile-is-running}

```lua
luau_profile.is_running() -> boolean
```

True iff the background sampler is currently running.

**Returns** `boolean` — Sampler running state.

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

## globals/luau_profile/reset {#globals-luau-profile-reset}

```lua
luau_profile.reset()
```

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

```lua
luau_profile.reset()
```

## globals/luau_profile/sampling_available {#globals-luau-profile-sampling-available}

```lua
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.

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

## globals/luau_profile/snapshot {#globals-luau-profile-snapshot}

```lua
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.

```lua
local snap = luau_profile.snapshot(10)
```

## globals/luau_profile/start {#globals-luau-profile-start}

```lua
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.

```lua
luau_profile.start(500)
```

## globals/luau_profile/stop {#globals-luau-profile-stop}

```lua
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.

```lua
luau_profile.stop()
```

## modules/luau_profile/README {#modules-luau-profile-readme}

```lua
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 {#modules-luau-profile-begin}

```lua
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.

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

## modules/luau_profile/dump {#modules-luau-profile-dump}

```lua
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.

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

## modules/luau_profile/dump_regions {#modules-luau-profile-dump-regions}

```lua
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.

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

## modules/luau_profile/end_region {#modules-luau-profile-end-region}

```lua
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()`.

```lua
luau_profile.end_region(id)
```

## modules/luau_profile/folded {#modules-luau-profile-folded}

```lua
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.

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

## modules/luau_profile/is_running {#modules-luau-profile-is-running}

```lua
is_running(): boolean
```

True iff the background sampler is currently running.

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

## modules/luau_profile/reset {#modules-luau-profile-reset}

```lua
reset()
```

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

```lua
luau_profile.reset()
```

## modules/luau_profile/sampling_available {#modules-luau-profile-sampling-available}

```lua
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.

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

## modules/luau_profile/snapshot {#modules-luau-profile-snapshot}

```lua
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.

```lua
local snap = luau_profile.snapshot(10)
```

## modules/luau_profile/span<T...> {#}

```lua
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.

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

## modules/luau_profile/start {#modules-luau-profile-start}

```lua
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.

```lua
luau_profile.start(500)
```

## modules/luau_profile/stop {#modules-luau-profile-stop}

```lua
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.

```lua
luau_profile.stop()
```

## typed/builtin//modules/api/engine/luau_profile/luau_profile/begin {#typed-builtin-modules-api-engine-luau-profile-luau-profile-begin}

```lua
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.

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

## typed/builtin//modules/api/engine/luau_profile/luau_profile/dump {#typed-builtin-modules-api-engine-luau-profile-luau-profile-dump}

```lua
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 }`.

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

## typed/builtin//modules/api/engine/luau_profile/luau_profile/dump_regions {#typed-builtin-modules-api-engine-luau-profile-luau-profile-dump-regions}

```lua
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 }`.

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

## typed/builtin//modules/api/engine/luau_profile/luau_profile/end_region {#typed-builtin-modules-api-engine-luau-profile-luau-profile-end-region}

```lua
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()`.

```lua
luau_profile.end_region(id)
```

## typed/builtin//modules/api/engine/luau_profile/luau_profile/folded {#typed-builtin-modules-api-engine-luau-profile-luau-profile-folded}

```lua
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.

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

## typed/builtin//modules/api/engine/luau_profile/luau_profile/is_running {#typed-builtin-modules-api-engine-luau-profile-luau-profile-is-running}

```lua
luau_profile.is_running() -> boolean
```

True iff the background sampler is currently running.

**Returns** `boolean` — Sampler running state.

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

## typed/builtin//modules/api/engine/luau_profile/luau_profile/reset {#typed-builtin-modules-api-engine-luau-profile-luau-profile-reset}

```lua
luau_profile.reset()
```

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

```lua
luau_profile.reset()
```

## typed/builtin//modules/api/engine/luau_profile/luau_profile/sampling_available {#typed-builtin-modules-api-engine-luau-profile-luau-profile-sampling-available}

```lua
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.

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

## typed/builtin//modules/api/engine/luau_profile/luau_profile/snapshot {#typed-builtin-modules-api-engine-luau-profile-luau-profile-snapshot}

```lua
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.

```lua
local snap = luau_profile.snapshot(10)
```

## typed/builtin//modules/api/engine/luau_profile/luau_profile/start {#typed-builtin-modules-api-engine-luau-profile-luau-profile-start}

```lua
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.

```lua
luau_profile.start(500)
```

## typed/builtin//modules/api/engine/luau_profile/luau_profile/stop {#typed-builtin-modules-api-engine-luau-profile-luau-profile-stop}

```lua
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.

```lua
luau_profile.stop()
```