query · developer.performance

Performance log samples

Returns one bounded page of frame, CPU, and process-memory samples from the current or most recent log.

developer.performance.log-samples(filters?, cursor?, page_size?) -> query-page

Stable ID: developer.performance.log-samples
Owner: app.runtime-performance-monitor
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.0.0

Usage

Call through world.query to page through the active or most recent bounded logging session. Consume detached samples during the callback and use next_cursor for continuation.

Parameters

cursor: optional continuation cursor returned by this query.
page_size: positive sample limit capped at 64 by the host.
filters: no filters are accepted.

Returns

A detached page of frame index, instantaneous FPS, frame time, process CPU time and load, and resident-memory samples.

Cost

Copies at most 64 samples per call and consumes matching query-record and owner-visit budgets.

Fields

ID	Type	Units	Required	Description
`cpu_ms`	`number`	milliseconds	yes	Process CPU time.
`cpu_percent`	`number`	percent-of-one-core	yes	Process CPU time relative to wall time.
`frame`	`unsigned-integer`	none	yes	Recorded frame index.
`frame_ms`	`number`	milliseconds	yes	Frame duration.
`frames_per_second`	`number`	frames-per-second	yes	Instantaneous frame rate.
`memory_available`	`boolean`	none	yes	Whether resident memory was available.
`resident_memory_bytes`	`unsigned-integer`	bytes	yes	Process resident memory.

Errors

Examples

local result = world.query("developer.performance.log-samples", {cursor = 0, page_size = 16})
for _, sample in ipairs(result.records) do
    ui.row("Frame " .. tostring(sample.frame), string.format("%.2f ms", sample.frame_ms))
end

API history

1.0.0: Paginated bounded performance-log samples added during Phase 15 closure.