query · developer.performance

Performance log summary

Returns min, average, and max values for the current or most recent bounded log.

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

Stable ID: developer.performance.log
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 while a logging session is active or after it stops. Read min, average, and max FPS, frame time, process CPU, and resident-memory values without retaining native handles.

Parameters

cursor: must remain zero for the single summary record.
page_size: positive record limit capped by the host; one record is returned.
filters: no filters are accepted.

Returns

One detached summary for the active or most recent log, including state, session identity, sample count, capacity, frame bounds, and metric ranges.

Cost

Reads a constant-time rolling summary maintained while recording and consumes one query, one result record, and one owner visit.

Fields

ID	Type	Units	Required	Description
`average_cpu_ms`	`number`	milliseconds	yes	Average process CPU time.
`average_cpu_percent`	`number`	percent-of-one-core	yes	Average process CPU load.
`average_fps`	`number`	frames-per-second	yes	Average instantaneous frame rate.
`average_frame_ms`	`number`	milliseconds	yes	Average frame duration.
`average_memory_bytes`	`unsigned-integer`	bytes	yes	Average resident memory.
`latest_memory_bytes`	`unsigned-integer`	bytes	yes	Latest resident memory.
`maximum_cpu_ms`	`number`	milliseconds	yes	Maximum process CPU time.
`maximum_cpu_percent`	`number`	percent-of-one-core	yes	Maximum process CPU load.
`maximum_fps`	`number`	frames-per-second	yes	Maximum instantaneous frame rate.
`maximum_frame_ms`	`number`	milliseconds	yes	Maximum frame duration.
`maximum_memory_bytes`	`unsigned-integer`	bytes	yes	Maximum resident memory.
`maximum_samples`	`unsigned-integer`	none	yes	Configured sample capacity.
`memory_sample_count`	`unsigned-integer`	none	yes	Samples with available resident memory.
`minimum_cpu_ms`	`number`	milliseconds	yes	Minimum process CPU time.
`minimum_cpu_percent`	`number`	percent-of-one-core	yes	Minimum process CPU load.
`minimum_fps`	`number`	frames-per-second	yes	Minimum instantaneous frame rate.
`minimum_frame_ms`	`number`	milliseconds	yes	Minimum frame duration.
`minimum_memory_bytes`	`unsigned-integer`	bytes	yes	Minimum resident memory.
`sample_count`	`unsigned-integer`	none	yes	Recorded sample count.
`session_id`	`unsigned-integer`	none	yes	Logging session identity.
`started_frame`	`unsigned-integer`	none	yes	First eligible frame index.
`state`	`enumeration`	none	yes	Logging state.
`stopped_frame`	`unsigned-integer`	none	yes	Last recorded frame or zero while active.

Errors

Examples

local result = world.query("developer.performance.log", {page_size = 1})
if result.status == "completed" then
    local log = result.records[1]
    ui.row("Minimum FPS", string.format("%.1f", log.minimum_fps))
    ui.row("Maximum memory", tostring(log.maximum_memory_bytes))
end

API history

1.0.0: Bounded performance-log summaries added during Phase 15 closure.