Vega Studio Performance CLI

Performance CLI is installed as part of the Vega Developer Tools (VDT). To analyze app performance, you can use either the command palette in the Vega Studio extension or the Performance command-line interface (CLI).

Prerequisites

1. Install the Vega SDK.

2. Verify if the Performance CLI is installed in your development environment:

   Copy code Copied to clipboard.

   kepler exec perf --help
   

Help option

To explore options for all Performance CLI commands:

kepler exec perf --help

To get information about a specific command:

kepler exec perf [command] --help

To see all options for the record command:

kepler exec perf record --help

Commonly used commands

kepler exec perf record

Use the record command to start the Event Recording tool. This captures performance events for analysis. The command takes the following arguments:

• --app-name - Specifies the app's main interactive component name from manifest.toml
• --recording-timeout - Sets the recording duration in seconds (default: 120s)
• --device-serial-number - Sets the device serial number when you have multiple devices
• --output-dir - Specifies the output directory path
• --trace-categories - Specifies platform trace categories to enable during tracing. Default categories: app, graphics, ui, lifecycle, input, video, and webview
• --enable-cpu-sched - Enables CPU scheduler event recording during tracing (disabled by default)

To record performance events for your app:

kepler exec perf record --app-name com.<COMPANY NAME>.<APPNAME>.main

To record with a specific timeout:

kepler exec perf record --app-name com.<COMPANY NAME>.<APPNAME>.main --recording-timeout 60

To record with custom trace categories:

kepler exec perf record --app-name com.<COMPANY NAME>.<APPNAME>.main --trace-categories app,graphics,ui,video

To record with CPU scheduler events enabled:

kepler exec perf record --app-name com.<COMPANY NAME>.<APPNAME>.main --enable-cpu-sched

kepler exec perf activity-monitor

Use the activity-monitor command to start the Activity Monitor tool. The command takes the following arguments:

• --app-name - Specifies the app's main interactive component name from manifest.toml
• --record-cpu-profiling - Enables the JavaScript CPU Profiler during recording
• --sdk-path - Specifies the installed Vega SDK path (required when using --record-cpu-profiling)
• --sourcemap-file-path - Specifies the JavaScript source map path (required when using --record-cpu-profiling)

To monitor app activity:

kepler exec perf activity-monitor --app-name com.<COMPANY NAME>.<APPNAME>.main

To monitor with CPU profiling enabled:

kepler exec perf activity-monitor --app-name com.<COMPANY NAME>.<APPNAME>.main --record-cpu-profiling --sdk-path /path/to/vega/sdk --sourcemap-file-path /path/to/sourcemap

kepler exec perf memory-monitor

Use the memory-monitor command to start the Memory Monitor tool. The command takes the following arguments:

• --app-name - Specifies the app's main interactive component name from manifest.toml
• --keplerscript-app - Specifies the app is a React Native-based app for Vega
• --relative-gc-count - Shows Garbage Collection (GC) count as delta between current and previous GC count (available only with React Native-based apps)

To monitor app memory:

kepler exec perf memory-monitor --app-name com.<COMPANY NAME>.<APPNAME>.main

To monitor with relative garbage collection count for React Native apps:

kepler exec perf memory-monitor --app-name com.<COMPANY NAME>.<APPNAME>.main --keplerscript-app --relative-gc-count

To start and stop recording sessions:

For Mac:

1. Press s to start recording.
2. Press s again to stop the recording.

If pressing s doesn't work, press S and Return.

For Linux:

1. Press s to start recording.
2. Press s again 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.

kepler exec perf kpi-visualizer

Use the kpi-visualizer command to measure your app KPIs. The command takes the following arguments:

• --app-name - Specifies the app's main interactive component name from manifest.toml
• --overridden-video-fps - Overrides the frames per second for video fluidity calculations during video playback

To measure app KPIs:

kepler exec perf kpi-visualizer --app-name com.<COMPANY NAME>.<APPNAME>.main

To override video FPS for video fluidity calculations:

kepler exec perf kpi-visualizer --app-name com.<COMPANY NAME>.<APPNAME>.main --overridden-video-fps 30

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: Oct 08, 2025