Using Roku Resouce Monitor in Data Collection Mode

You can integrate a headless version of the Roku Resource Monitor into your CLI pipelines to automate data collection and performance monitoring—without having to use the RRM UI. The JSON file format generated by RRM in headless mode can be opened for inspection in the RRM UI, attached to bug tickets, and post-processed for resource utilization trends.

Data collection mode commands

To use RRM in Data Collection Mode, open a console application and enter the following:

Linux

./roku-resource-monitor-linux64.AppImage --help

MacOS

./roku-resource-monitor.app/Contents/MacOS/roku-resource-monitor --help

Windows

roku-resource-monitor.bat --help

Options

The following table lists the options you can enter:

Option	Description	Required/Optional
--help	Displays a help message and exit	Optional
--headless	Runs RRM in Data Collection Mode (CLI mode without user interface)	Requried
--device-ip	Enter the IP address of the test Roku device (for example, 192.168.0.0)	Required
--channel-id	Enter the channel ID of the app to be monitored.	Required
--output-file	Enter the file or directory to output the collected data (for example, /home/Downloads)	Optional
--panels	Enter a comma-separated list of the metrics to be collected: memory graphics_memory cpu scenegraph_nodes frame_rate registry_usage sgrendezvous object_byte_count	Optional
--polling-interval	Set how frequently data is collected (by default 1-second intervals are used).	Optional

MacOS Example (with options)

roku-resource-monitor --headless --device-ip=192.168.0.0 --channel-id=1 --output-file=/home/Downloads --panels=cpu,memory --polling-interval=1

Using the Docker CLI to run data collection mode

You can add RRM in a Docker image and run data collection mode.

Docker file

The following Dockerfile creates a containerized environment for running the Roku Resource Monitor (RRM).

Build Command:

docker build -t rrm:latest .

Run Command:

docker run --shm-size=2g -v [docker host output dir]:/output --env-file=[env file path] rrm:latest

# ==============================================================================
# Roku Resource Monitor Docker Image
# ==============================================================================
FROM ubuntu:24.04
# Prevent interactive prompts during package installation
ENV DEBIAN_FRONTEND=noninteractive
# Set XDG runtime directory for user session services
# This directory is used by various desktop applications and services (like D-Bus)
# to store temporary files and sockets during the user session
ENV XDG_RUNTIME_DIR=/tmp/runtime-dir
# Update package list and install required system dependencies
# This combines multiple package installations for better Docker layer caching
RUN apt update && apt install -y \
dbus-x11 \
libasound2t64 \
libatk-bridge2.0-0 \
libatk1.0-0 \
libcups2 \
libdbus-1-3 \
libgbm1 \
libglib2.0-0 \
libgtk-3-0 \
libnss3 \
wget \
xvfb \
# Clean up package cache to reduce image size
&& rm -rf /var/lib/apt/lists/*
# Create D-Bus runtime directory
# This directory is required for D-Bus system daemon to function properly
RUN mkdir -p /run/dbus
# Create and configure XDG runtime directory
# The 700 permissions ensure only the current user can access this directory
RUN mkdir -p "$XDG_RUNTIME_DIR" && chmod 700 "$XDG_RUNTIME_DIR"
# Copy the startup script from host to container
# This script handles downloading, extracting, and running the RRM application
COPY startup.sh /bin
# Make the startup script executable
# This allows the script to be run as a command
RUN chmod +x /bin/startup.sh
# Set the default command to run when container starts
# Uses sh to execute the startup script
CMD ["/bin/sh", "/bin/startup.sh"]

Startup

The following script handles the setup and execution of RRM. It downloads the latest RRM release, extracts it, configures the necessary services, and launches the application in headless mode.

#!/bin/sh
# ==============================================================================
# Roku Resource Monitor Startup Script
# ==============================================================================
#
# Expected Environment Variables:
# DEVICE_IP - IP address of the Roku device (REQUIRED).
# CHANNEL_ID - Channel to monitor (dev, or channel id).
# PANELS - Performance panels to monitor (please refer documentation for details).
# POLLING_INTERVAL - How often to collect metrics in seconds.
#
# ==============================================================================
echo "Downloading latest release of a Roku Resource Monitor..."
wget -O /rrm.tar.gz --progress=bar:force:noscroll \
https://devtools.web.roku.com/roku-resource-monitor/app/roku-resource-monitor-linux64.tar.gz
echo "Extracting Roku Resource Monitor..."
# Create RRM directory and extract archive contents
# --strip-components=1 removes the top-level directory from the archive
mkdir /RRM && tar -xf rrm.tar.gz --strip-components=1 -C /RRM
echo "Starting Roku Resource Monitor in headless mode..."
# Start D-Bus system daemon for inter-process communication
# --system runs as system daemon, --fork runs in background
dbus-daemon --system --fork
# Start D-Bus session daemon and export its address for applications to use
# This creates a session bus for the current user/session
export DBUS_SESSION_BUS_ADDRESS=$(dbus-daemon --session --fork --print-address)
# Disable X11 keyboard extension to prevent warnings in headless mode
export XKB_DISABLE=1
# Launch RRM using xvfb-run for virtual display with comprehensive flags
# xvfb-run -a automatically finds an available display number
xvfb-run -a \
/RRM/roku_resource_monitor \
--no-sandbox \
--headless \
--disable-gpu \
--device-ip=$DEVICE_IP \
--channel-id=$CHANNEL_ID \
--polling-interval=$POLLING_INTERVAL \
--panels=$PANELS \
--output-file=/output

Docker compose

The following Docker Compose file enables you to run the Roku Resource Monitor in a containerized environment:

# ==============================================================================
# Roku Resource Monitor Docker Compose Configuration
# ==============================================================================
#
# Usage:
# 1. Update the DEVICE_IP to match your Roku device's IP address
# 2. Configure other environment variables as needed
# 3. Run: docker-compose up --build
# 4. Check output files in the ./output directory
#
# Environment Variables:
# DEVICE_IP - IP address of the Roku device (REQUIRED).
# CHANNEL_ID - Channel to monitor (dev, or channel id).
# PANELS - Performance panels to monitor (please refer documentation for details).
# POLLING_INTERVAL - How often to collect metrics in seconds.
#
# ==============================================================================
services:
rrm-cli:
build:
context: .
platforms:
- "linux/amd64" # Specify a platform for consistent builds
dockerfile: Dockerfile
container_name: roku-resource-monitor
volumes:
# Mount output directory to persist monitoring data
- ./output:/output
# Shared memory size for Chromium/Electron (prevents crashes)
# This is important for headless Chromium applications
shm_size: 2g
# Environment variables
environment:
# REQUIRED: IP address of your Roku device
# Replace with your actual device IP
DEVICE_IP: "192.168.1.100"
# Channel to monitor (dev, or channel id.)
CHANNEL_ID: "dev"
# Performance panels to monitor
# Available options: please refer documentation for details
PANELS: "memory,cpu"
# How often to collect metrics (in seconds)
POLLING_INTERVAL: "5"

Run

Configure your environment variables and local output directory directly in the docker-compose.yml file. Alternatively, you can use an environment file (with matching variable names) when running the container using the docker run command.

Docker Compose usage

docker compose up --build

Docker usage

docker build -t roku-resource-monitor:latest . docker run --shm-size=2g -v [docker host output dir]:/output --env-file=[env file path] roku-resource-monitor

developer.roku.com