Vega Studio Performance CLI
Open Beta Documentation Amazon offers this technical
documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback
and iterates on the features. For the most current feature information, see the Release
Notes.
To analyze app performance, you can use either the command palette in Vega Studio extension or the Performance command-line interface (CLI).
The following sections explain the command structure, the CLI command to use for each analysis tool, and options you can add to the command structure.
Before you begin
Performance CLI is installed as part of the Vega Developer Tools (VDT). To verify if the Performance CLI is installed in your development environment, run:
kepler exec perf --help
Performance CLI command structure
The Performance CLI commands follow this structure:
kepler exec perf [command] [options] [parameters]
where:
kepler exec perf- the base call to the Performance CLI tool[command]- the action you want to perform[options]- the description of the options for your command[parameters]- all parameters for your command
Commands
The following table lists the command for Vega Studio performance tools.
| Command | Description |
|---|---|
record |
Starts the Event Recording tool. See instructions on how start and stop a recording session. |
activity-monitor |
Starts the Activity Monitor tool to measure your app performance. See instructions on how to start and stop a recording session. |
memory-monitor |
Starts the Memory Monitor tool to measure your app memory. See instructions on how to start and stop a recording session. |
kpi-visualizer |
Starts the KPI Visualizer tool to measure your app KPIs. |
Tip: Pressing
Ctrl or control + c won't terminate the running process properly. Please press q to quit instead.Start and stop a recording session
- Press
sto start recording. - Press
sagain to stop the recording.
If pressing s doesn't work, press S and Return.
- Press
sto start recording. - Press
sagain to stop the recording.
If pressing s doesn't work, press S and Enter.
Press q and Return, or q and Enter, to quit recording.
Note: By default, the recording session times out at 120s.
Options
You can add the following options to your command.
| Option | Description | Required |
|---|---|---|
—-activity-monitor |
Displays the Activity Monitor data. | No |
—-app-name APP_NAME |
Indicates the app's main interactive component name from manifest.toml. Example: perf activity-monitor —app-name=com.amazondeveloper.keplervideoapp.main for Vega Video Sample App. |
Yes |
—-device-serial-number DEVICE_SERIAL_NUMBER |
Sets the device serial number. This is useful when you have multiple devices. Use kepler exec vda devices to find the device serial number. |
No |
--enable-cpu-sched |
Enables CPU scheduler event recording during tracing. (Disabled by default) | No |
--keplerscript-app |
Specifies the app is a React Native-based app for Vega. | No |
—-output-dir DIRECTORY |
Specifies the output directory path. | No |
--overridden-video-fps |
Overrides the frames per second that the app under test sets in its code. Use it only with the kpi-visualizer tool when calculating video fluidity percentage during video playback. |
No |
—-recording-timeout TIMEOUT_IN_SECONDS |
Specifies the recording duration in seconds. (Default: 120 s) | Yes |
—-record-cpu-profiling |
Enables the JavaScript CPU Profiler during recording. | No |
--relative-gc-count |
Shows Garbage Collection (GC) count as the delta between the current and previous GC count. Without this option, the raw GC count is reported. This option is only available with React Native-based app for Vega using memory monitor. | No |
--sdk-path KEPLER_SDK_PATH |
Specifies the installed Vega SDK path. | Yes, if you're passing —-record-cpu-profiling argument. |
—-sourcemap-file-path |
Specifies the JavaScript source map path for your app. | Yes, if you're passing —-record-cpu-profiling argument. |
--trace-categories TRACE_CATEGORIES |
Specifies platform trace categories to enable during tracing. Use --help for supported categories. Default categories: app, graphics, ui, lifecycle, input, video, and webview. App traces appear in the ui category. |
No |
Related topics
- Vega SDK CLI Reference
- Vega Studio Commands
- 💬 Community: Inspect JS traces from Vega Apps
- 💬 Community: Using React DevTools to profile component rendering
Last updated: Sep 30, 2025
