Roku Resource Monitor session file specification

Developers can follow this specification to build a custom resource monitoring tool that analyzes the memory, CPU, and SceneGraph node usage metrics collected with the Roku Resource Monitor. This specification describes the data types and structure of a monitoring session file (.JSON) that has been exported from the Roku Resource Monitor.

This specification has been updated to support Roku Resource Monitor 4.0.

The v1 version of this spec and the session files generated by the previous versions of the Roku Resource Monitor (v1.0 and v1.1) have been deprecated.

File name

The name of an exported Roku Resource Monitor file has the following syntax: <channel-name>_<device-name>_<unix-timestamp>.json.

Data types

The fields in the monitoring file may be one of the following data types:

Data type Definition
string Includes alphanumeric and special characters
number Includes integer and fractional numbers.
bool A true/false value.

File structure

A monitoring session file contains the following objects (listed in order):

Object Description
device The name, model, serial number, and OS version of the test device.
channel The ID, name, and version of the test app.
metadata The unique ID, timestamp, and version of the monitoring file.
session A stream of multiple entries of the following types:
  • static. The background and foreground DRAM usage limits (for supported devices only; this field is set to "null" on unsupported devices).
  • live. The resource usage statistics. This contains arrays of objects for the following metrics: channel_system_memory_usage, channel_cpu_usage, channel_graphics_memory_usage, channel_graph_metrics, graphics_rendering_frame_rate, sgrendezvous and fw_beacons.

Device information

The device object contains the following fields that provide information about the test device used for the monitoring session:

Name Type Description Example
device_name string The device-friendly name. "Roku Express"
model_number string The device model number. "3930X"
serial_number string The device serial number. "X00400CS3EMP"
software_version string The software version installed on the device. "23.0.0"
software_build number The software version build installed on the device. 991

Channel information

The channel object contains the following fields that provide information about the test app used for the monitoring session:

Name Type Description Example
id string The unique identifier of the app "581251" or "dev"
version string The app version "1.1.2"
name string The app name "Roku Developers"

File metadata

The metadata object contains the following fields that provide information about the JSON file generated for the monitoring session:

Name Type Description Example
uuid string A randomly-generated Version 4 unique user ID (UUID). cd7cbbeb-c4a7-46dc-ab9f-fdeb90523481
created_at number A unix timestamp in milliseconds (13-digit) when the file was created. 1657721930416
started_at number A unix timestamp in milliseconds (13-digit) when the monitoring session was started. 1657721930416
version number The file version. 4

Session information

The session object contains the static memory usage limits of the test app and the live resource usage statistics generated during the monitoring session.

Static object

The static object contains the following persistent data:

Name Type Unit Description
foreground_limit number/null Bytes The maximum amount of DRAM that may be used by the app when browsing and selecting content in the app UI and during playback. If an app exceeds the limit displayed in the app system memory usage pane while running in the foreground, the Roku OS terminates the app. The foreground limit varies by device, and it is subject to change.

On devices that do not support per-app memory limits, the Roku Resource Monitor displays "N/A". The Roku OS, however, does terminate apps running in the foreground when specific system memory levels are reached on those devices.

The foreground limit may be decreased in the near future; therefore, apps should consume only 75% of the displayed limit. The reduced limit will be enforced by the Roku OS in the near future.
background_limit number/null Bytes The maximum amount of DRAM that may be used by the app while running in the background (this limit is also applicable for apps that have integrated Instant Resume). If an app exceeds the limit displayed in the app system memory usage pane while running in the background, the Roku OS terminates the app. The Roku OS also terminates apps running in the background when specific system memory levels are reached.

On devices that do not support per-app memory limits, the Roku Resource Monitor displays "N/A". The Roku OS, however, does terminate apps running in the background when specific system memory levels are reached on those devices.

The background limit may be decreased in the near future; therefore, apps should consume a maximum of 100 MB of DRAM while running in the background. The reduced limit will be enforced by the Roku OS in the near future. See Data management and Memory management for best practices on allocating resources.

Live

The live object contains the following objects for the resource usage statistics generated during the monitoring session:

Name Type Description
bs_objects array Array of points that include BrightScripted objects sorted by groups:
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained
groups array N/A Array of objects that includes:

Name Type Unit Description
Name string Bytes Name of group.
Id string Bytes ID of the group.
Objects count number Bytes Count of object in the group.
Objects array - Array of objects that includes the count, name, and memory of each object.
Objects memory number Bytes Memory size of objects in the group.
channel_system_memory_usage array Array of points for the following system memory usage metrics generated over time:
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained
used number Bytes Number/null. Amount of used memory (sum of resident and swap) by the app
resident number Bytes Number/null. Amount of resident memory in use by the app (sum of shared, anonymous and file-backed memory)
swap number Bytes Number/null. Amount of swap memory in use by the app
anon number Bytes Number/null. Amount of anonymous memory in use by the app
file number Bytes Number/null. Amount of file-backed memory in use by the app
shared number Bytes Number/null. Amount of shared memory in use by the app
channel_cpu_usage array Array of points for the following CPU usage metrics generated over time:
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained
total number Percent Number/null. The total CPU usage percentage (sum of user and kernel) by the app
user number Percent Number/null. User space CPU usage percentage by the app
sys number Percent Number/null. Kernel space CPU usage percentage by the app
channel_graphics_memory_usage array Array of points for the following graphics memory usage metrics generated over time:
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained
texture number Bytes Number/null. Amount of texture memory in use by the app
system number Bytes Number/null. Amount of system memory in use by the app
bitmaps array N/A Array of objects that includes the following bitmap data:
Name Type Unit Description
bpp number Bytes The bits per pixel (bpp) of the bitmap.
height number Bytes The height of the bitmap in pixels.
width number Bytes The width of the bitmap in pixels.
size number Bytes The size of the bitmap in bytes.
name string Bytes The URL path of the bitmap.
channel_graph_metrics array Array of points for the following SceneGraph metrics generated over time (foreground and background):
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained
total_nodes number Bytes Number/null. Total number of nodes in the channel
total_memory number Bytes Number/null.
Nodes array - Array of objects that includes the following fields:
Name Type Unit Description
Name string Bytes Name of the node
Count number Bytes Count of the node
Memory number Bytes Memory size of the node
graphics_rendering_frame_rate array Array of points for the following graphics rendering frame rate data generated over time (foreground and background):
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained
fps number Count Recent number of rendered graphics frames per seconds
sgrendezvous array Array of points for the following rendezvous event data generated over time (foreground and background):
Name Type Unit Description
timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained.
total_time number Bytes The total time spent in rendezvous events during each sampling interval.
drop_ count number Bytes The number of rendezvous events that were dropped because the event queue was full.
count number Bytes The number of rendezvous events during each sampling interval
items array N/A Array of objects that includes the following rendezvous event information:
Name Type Unit Description
Id number Bytes The unique ID of the rendezvous event.
start number Bytes Number/null. The number of milliseconds that elapsed during the rendezvous event.
end number Bytes Number/null. The number of milliseconds that elapsed during the rendezvous event.
line_number number Bytes Number/null. The line number of the rendezvous event.
name string Bytes The source of the rendezvous event.
fw_beacons array Array of app and media events (signal beacons) that have occurred on the app. Each event has a Unix timestamp in milliseconds (13-digit) marking when the event occurred. The timestamp has a number type provided in bytes. See Measuring app performance for detailed descriptions of these events.

Channel events:
  • app_compile_initiate / app_compile_complete
  • app_load_initiate / app_load_complete
  • app_splash_initiate / app_splash_complete
  • app_resume_initiate / app_resume_complete
  • app_suspend_initiate / app_suspend_complete
  • app_exit_initiate / app_exit_complete


Media events:
  • vod_start_initiate / vod_start_complete
  • epg_launch_initiate / epg_launch_complete
  • live_channel_change_initiate / live_channel_change_complete
registry_usage array Array of points for the channel registry entries.
Name Type Unit Description
Timestamp number Bytes Unix timestamp in milliseconds (13-digit) when data was obtained.
Used number Bytes Number/null. The amount of storage currently used on the device.
Sections array - Array of objects that includes:
Name Type Unit Description
Name string Bytes Name of section
Items array - Items in the section. Each item includes the key (string) for that section.

Monitoring file example

Click here to download a sample RRM 4.1 monitoring file.

Change log

  • v4.1 (June 16, 2025):

    • Updated bs_objects and channel_graph_metrics objects.

  • v4.0 (March 12, 2025):

    • Updated bs_objects field.
    • Updated sample file.

  • v3.1 (September 24, 2024):

    • Added fields for tracking BrightScript memory allocation..

  • v3.0 (April 11, 2024):

    • Added objects for tracking BrightScript memory allocation.

  • v2.0 (March 28, 2023):

    • Added objects for tracking rendezvous events, device registry usage, and graphics frame rendering rate.
    • Added objects for tracking app and media events.

  • v1.0 (September 11, 2022):

    • Initial release.
    • Includes objects for tracking system memory, graphics memory, CPU, and SceneGraph node usage.