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

Normalized fields: cpu_percent (0-100), memory_used_bytes, memory_total_bytes (nil when the platform doesn't report it), and pts (the current video frame's presentation timestamp, for lining a reading up against the recording). available is false (with a reason string) when no sample is available — the platform has no sampler, nothing has been sampled yet, or (on Roku) no developer channel is running.

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

available is false (with a reason string) when no sample is available.

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_total_bytes is nil when the platform doesn't report it. available is false (with a reason string) when no sample is available.