README.md
1# **torq: AAOS Performance CLI**
2
3**torq** is a command-line tool designed to streamline and standardize OS
4performance profiling across Android Automotive devices. By providing a flexible
5and easy-to-use interface, **torq** enables engineers and OEMs to capture and
6analyze performance data for critical system events such as boot, user switch,
7app startup, or any of their own interactions with their device. This tool helps
8ensure consistent results amongst different users and helps reduce the time and
9effort required for performance analysis, ensuring that developers can focus on
10optimizing their systems and bug detection rather than navigating fragmented
11tooling solutions.
12
13
14## Getting Started
15
16- **torq** is an open source Android tool. Run the following commands to get
17started:
18
19```
20cd $ANDROID_ROOT
21source build/envsetup.sh
22lunch <target-name> (e.g., lunch sdk_gcar_x86_64-next-userdebug)
23cd $ANDROID_ROOT/system/extras/torq
24m torq
25```
26
27- Connect to an Android Automotive device or start an emulator.
28- Ensure the connected device appears in `adb devices`.
29- You can now run `torq` anywhere, followed by any necessary arguments
30(e.g., `torq -d 7000`).
31
32
33## Example Usages
34
35### ./torq -d 7000
36- Run a custom event for 7 seconds.
37### ./torq -e user-switch --from-user 10 --to-user 11
38- Run a user-switch event, switching from user 10 to user 11.
39### ./torq -e boot --perfetto-config ./config
40- Run a boot event, using the user's local Perfetto config specified in the
41./config file path.
42### ./torq -e boot -r 5 --between-dur-ms 3000
43- Run a boot event 5 times, waiting 3 seconds between each boot run.
44### ./torq -e app-startup -a android.google.kitchensink
45- Run an app-startup event, starting the android.google.kitchensink package.
46### ./torq -e user-switch --to-user 9 --serial emulator-5554
47- Run a user-switch event, switching to user 9 on the connected device with
48serial, emulator-5554.
49### ./torq -p simpleperf -d 10000
50- Run a custom event using the Simpleperf profiler for 10 seconds.
51### ./torq -p simpleperf -s cpu-cycles -s instructions
52- Run a custom event using the Simpleperf profiler, in which the stats,
53cpu-cycles and instructions, are collected.
54### ./torq -d 10000 --perfetto-config lightweight
55- Run a custom event for 10 seconds using the "lightweight" predefined Perfetto
56config.
57### ./torq config show memory
58- Print the contents of the memory predefined Perfetto config to the terminal.
59### ./torq open trace.perfetto-trace
60- Open a trace in the perfetto UI.
61### ./torq -d 10000 --exclude-ftrace-event power/cpu_idle
62- Run a custom event for 10 seconds, using the "default" predefined Perfetto
63config, in which the ftrace event, power/cpu_idle, is not collected.
64
65
66## CLI Arguments
67
68| Argument | Description | Currently Supported Arguments | Default |
69|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|--------------------------------------|
70| `-e, --event` | The event to trace/profile. | `boot`, `user-switch`,`app-startup`, `custom` | `custom` |
71| `-p, --profiler` | The performance data profiler. | `perfetto`, (`simpleperf` coming soon) | `perfetto` |
72| `-o, --out-dir` | The path to the output directory. | Any local path | Current directory: `.` |
73| `-d, --dur-ms` | The duration (ms) of the event. Determines when to stop collecting performance data. | Float >= `3000` | `10000` |
74| `-a, --app` | The package name of the app to start.<br/>(Requires use of `-e app-startup`) | Any package on connected device | |
75| `-r, --runs` | The amount of times to run the event and capture the performance data. | Integer >= `1` | `1` |
76| `--serial` | The serial of the connected device that you want to use.<br/>(If not provided, the ANDROID_SERIAL environment variable is used. If ANDROID_SERIAL is also not set and there is only one device connected, the device is chosen.) | | |
77| `--perfetto-config` | The local file path of the user's Perfetto config or used to specify a predefined Perfetto configs. | `default`, any local perfetto config,<br/>(`lightweight`, `memory` coming soon) | `default` |
78| `--between-dur-ms` | The amount of time (ms) to wait between different runs.<br/>(Requires that `--r` is set to a value greater than 1) | Float >= `3000` | `10000` |
79| `--ui` | Specifies opening of UI visualization tool after profiling is complete.<br/>(Requires that `-r` is not set to a value greater than 1) | `--ui`, `--no-ui`, | `ui` if `runs` is `1` |
80| `--exclude-ftrace-event` | Excludes the ftrace event from the Perfetto config. Can be defined multiple times in a command.<br/>(Requires use of `-p perfetto`)<br/>(Currently only works with `--perfetto-config default`,<br/>support for local Perfetto configs, `lightweight`, and `memory` coming soon) | Any supported perfetto ftrace event<br/>(e.g., `power/cpu_idle`, `sched/sched_process_exit`) | Empty list |
81| `--include-ftrace-event` | Includes the ftrace event in the Perfetto config. Can be defined multiple times in a command.<br/>(Requires use of `-p perfetto`)<br/>(Currently only works with `--perfetto-config default`,<br/>support for any local Perfetto configs, `lightweight`, and `memory` coming soon) | Any supported perfetto ftrace event<br/>(e.g., `power/cpu_idle`, `sched/sched_process_exit`) | Empty list |
82| `--from-user` | The user ID from which to start the user switch. (Requires use of `-e user-switch`) | ID of any user on connected device | Current user on the device |
83| `--to-user` | The user ID of user that device is switching to. (Requires use of `-e user-switch`). | ID of any user on connected device | |
84| `config list` | Subcommand to list the predefined Perfetto configs (`default`, `lightweight`, `memory`). | | |
85| `config show <config-name>` | Subcommand to print the contents of a predefined Perfetto config to the terminal. | `default`, `lightweight`, `memory` | |
86| `config pull <config-name> [file-path]` | Subcommand to download a predefined Perfetto config to a specified local file path. | <config-name>: `default`, `lightweight`, `memory`<br/> [file-path]: Any local file path | [file-path]: `./<config-name>.pbtxt` |
87| `open <file-path>` | Subcommand to open a Perfetto or Simpleperf trace in the Perfetto UI. | Any local path to a Perfetto or Simpleperf trace file | |
88
89## Functionality Coming Soon
90
91| Argument | Description | Accepted Values | Default |
92|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|---------------------------------------|
93| `-s, --simpleperf-event` | Simpleperf supported events that should be collected. Can be defined multiple times in a command. | Any supported simpleperf event<br/>(e.g., `cpu-cycles`, `instructions`) | Empty list |
94