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:

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:

Channel information

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

File metadata

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

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.