rk perfetto

The rk perfetto command records and manages Perfetto performance traces on a connected Roku device.

You enable tracing for a sideloaded app, deploy the app, and then start a recording. The command saves the trace as a .perfetto-trace file that you can open in Perfetto UI or in VS Code.

Understanding the execution model

The rk perfetto command runs in one of two modes: through a live server or locally. The following points describe how the command chooses a mode:

The command runs through the server first when it discovers a live rk server for the current workspace.
You can use --local to force local CLI execution and skip the server fast path.
The server and local modes behave the same way: they use the same command options, stop metadata, and user-facing output format.

Commands

The rk perfetto command has the enable and start subcommands.

rk perfetto enable [--channel-id ]

The enable subcommand enables Perfetto tracing for a sideloaded app on the device:

rk perfetto enable                    # enables tracing for "dev" (default)
rk perfetto enable --channel-id 12345 # enables tracing for app 12345

rk perfetto start [--open] [--output ]

The start subcommand starts recording a Perfetto trace. To stop recording and save the trace file, press Ctrl+C.

The start subcommand refuses to run until you enable tracing for the target device and app. In that case, the subcommand prints the following message:

Perfetto tracing has not been enabled for channel "dev" on device 192.0.2.212. Run
'rk perfetto enable' first, then redeploy the app ('rk dev') so the channel starts
with tracing on. Pass --skip-enable-check to record anyway.

The device firmware does not provide any way to query whether tracing is on; therefore, rk remembers which device and app pairs rk perfetto enable has succeeded for. If that record is stale (for example, the device rebooted, or you enabled tracing from a different machine), you can use --skip-enable-check to record without the check. See Enable state for more information.

When the session starts, the CLI prints the resolved destination path:

Connected. Recording to /abs/path/to/trace....perfetto-trace... (Ctrl+C to stop)

In server fast-path mode, recording also stops automatically when the underlying session ends (for example, the app exits), and the CLI prints the same final save message.

The following examples show common ways to run the start subcommand:

rk perfetto start                          # record until Ctrl+C, save to the mode-specific base directory
rk perfetto start --open                   # record, then open trace in VS Code after stopping
rk perfetto start --output traces/my.perfetto-trace  # save relative to the mode-specific base directory

By default, the command saves the trace as trace.<esn>.<timestamp>.perfetto-trace in the current directory of the CLI in local mode (--local), or in the project root of the server in server mode. You can use --output to specify a custom output path. Relative paths use the same mode-specific base directory. In both modes, output paths (relative or absolute) must stay within that base directory.

The server allows only one active session for each device. If you start a second session for the same device, the command returns 409 SESSION_ALREADY_ACTIVE.

Options

See rk perfetto for more information about every option and default. The --open, --output, and --skip-enable-check options apply to the start subcommand only. The --password option is accepted but unused. See Environment for more information.

Environment

The default app ID is dev. Device resolution uses the same device store as the other rk commands; therefore, you must add a device with rk device add <ip> first.

When you register a device and set it active (rk device set-active <device>), you do not need any flags. The rk perfetto enable and rk perfetto start commands both target the active device.

The endpoints that rk perfetto uses do not require authentication; therefore, you do not need a developer password, and a device without a stored password works. The --password option is still accepted so that scripts can pass the same flags that they pass to other rk commands.

Enable state

The rk perfetto enable command records each successful call in ~/.roku/perfetto-enabled.json. The record lets the start subcommand fail immediately instead of writing an empty trace. You can set ROKU_PERFETTO_STATE_PATH to relocate the file.

Records use the device serial as the key (esn:<serial>::<channelId>); therefore, a record follows the device when its Dynamic Host Configuration Protocol (DHCP) lease changes, and the next device that takes the old address does not inherit the record. If the command cannot read the serial from /query/device-info, the record uses the IP address as the key (ip:<deviceIp>::<channelId>).

The record says only that enable succeeded from this machine at some point. The record cannot show that the device has rebooted since or that tracing was enabled from somewhere else. In either case, you can use --skip-enable-check.

Recording a trace

The following commands show the workflow from adding a device to viewing the trace:

# 1. Add your device (one-time)
rk device add 192.0.2.212

# 2. Enable tracing for your sideloaded app
rk perfetto enable

# 3. Deploy your app
rk dev

# 4. Record a trace while interacting with the app
rk perfetto start --open

# 5. Press Ctrl+C when done; the trace opens in VS Code with the Perfetto plugin

See Perfetto profiling for more information about threads, firmware slices, transaction blocking rules, frame-budget analysis, and build-time auto-instrumentation.

Output

Trace files use the .perfetto-trace extension. The following applications recognize this extension:

Perfetto UI (drag and drop)
VS Code with the Perfetto community plugin

Technical details

The command uses the following endpoints:

Enable: POST http://<device-ip>:8060/perfetto/enable/<channelId>
Recording: WebSocket connection to ws://<device-ip>:8060/perfetto-session
ESN lookup: GET http://<device-ip>:8060/query/device-info

The server stop metadata has the following shape:

{
	"sessionId": "<id>",
	"filePath": "/abs/path/to/trace.perfetto-trace",
	"bytes": 18389,
	"durationMs": 1456
}