Skip to main content

Metrics API

Device performance metrics (CPU / memory) sampled in the background during a session, exposed under the device.metrics Lua namespace.

Backed by Sidecar.Device.PerformanceMetrics; all functions read the latest sample without hitting the device.

devicemetrics.performance​

Signatures​

performance(lua)

Description​

Returns the latest device performance sample: a normalized, cross-platform summary plus a raw table of the platform's native fields.

local m = device.metrics.performance()
if m.available then
  print(m.cpu_percent, m.memory_used_bytes, m.pts)  -- normalized (all platforms)
  print(m.raw.plugin_id)                              -- platform-specific
else
  print("metrics unavailable: " .. m.message)
end

Normalized fields: cpu_percent (0-100), memory_used_bytes, memory_total_bytes, and pts (the current video frame's presentation timestamp, for lining a reading up against the recording). Any can be nil when the platform reported a sample without that number.

When unavailable, available is false and the table carries a reason to branch on plus a human-readable message.

devicemetrics.sample_cpu​

Signatures​

sample_cpu(lua)

Description​

Returns just the latest CPU reading: cpu_percent, pts, and a raw table of the CPU-specific native fields.

local c = device.metrics.sample_cpu()
if c.available then
  print(c.cpu_percent, c.pts, c.raw.cpu_total_pct)
end

cpu_percent can be nil. When unavailable, available is false with a reason and message.

devicemetrics.sample_memory​

Signatures​

sample_memory(lua)

Description​

Returns just the latest memory reading: memory_used_bytes, memory_total_bytes, pts, and a raw table of the memory-specific native fields.

local m = device.metrics.sample_memory()
if m.available then
  print(m.memory_used_bytes, m.memory_total_bytes, m.pts)
end

memory_used_bytes and memory_total_bytes can be nil. When unavailable, available is false with a reason and message.