# torq

**Repository Path**: mirrors_google/torq

## Basic Information

- **Project Name**: torq
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-12
- **Last Updated**: 2025-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# torq: AAOS Performance CLI

**torq** is a command-line tool designed to streamline and standardize OS
performance profiling across Android Automotive devices. By providing a flexible
and easy-to-use interface, **torq** enables engineers and OEMs to capture and
analyze performance data for critical system events such as boot, user switch,
app startup, or any of their own interactions with their device. This tool helps
ensure consistent results amongst different users and helps reduce the time and
effort required for performance analysis, ensuring that developers can focus on
optimizing their systems and bug detection rather than navigating fragmented
tooling solutions.


## Getting Started

To start using **torq** follow these steps:

- Go to *torq*'s directory and build it:

```bash
bazel build //:torq
export PATH="$(pwd)/bazel-bin:$PATH"
```

- Connect to an Android device or start an emulator.
- Ensure the connected device appears in `adb devices`.
- Capture a perfetto trace using *torq*:

```bash
torq -d 7000
```

## Building Torq

**torq** has support for two build systems: [Bazel](https://bazel.build)
and *Android's Soong*.

To build and use torq using [Bazel](https://bazel.build/), run:
```bash
bazel build //:torq
./bazel-bin/torq --help
```

To build with *Android's Soong*, run:
```bash
cd $ANDROID_ROOT
source build/envsetup.sh
lunch <target-name> (e.g., lunch sdk_gcar_x86_64-next-userdebug)
cd $ANDROID_ROOT/system/extras/torq
m torq
```

## Quick one-line commands

**torq**'s main goal is to allow developers to quickly trace and profile Android
in the least amount of steps while being flexible enough to cover many different
use cases. This list of commands demonstrates just that.

| Command | Description  |
|----------|-------------|
| `torq -d 7000` | Run a custom event for 7 seconds. |
| `torq -e user-switch --from-user 10 --to-user 11` | Run a user-switch event, switching from user 10 to user 11. |
| `torq -e boot --perfetto-config ./config` | Run a boot event, using the user's local Perfetto config specified in the ./config file path. |
| `torq -e boot -r 5 --between-dur-ms 3000` | Run a boot event 5 times, waiting 3 seconds between each boot run. |
| `torq -e app-startup -a android.google.kitchensink` | Run an app-startup event, starting the android.google.kitchensink package. |
| `torq -e user-switch --to-user 9 --serial emulator-5554` | Run a user-switch event, switching to user 9 on the connected device with serial, emulator-5554. |
| `torq -p simpleperf -d 10000` | Run a custom event using the Simpleperf profiler for 10 seconds. |
| `torq -p simpleperf -s cpu-cycles -s instructions` | Run a custom event using the Simpleperf profiler, in which the stats, cpu-cycles and instructions, are collected. |
| `torq -d 10000 --perfetto-config lightweight` | Run a custom event for 10 seconds using the "lightweight" predefined Perfetto config. |
| `torq config show memory` | Print the contents of the memory predefined Perfetto config to the terminal. |
| `torq open trace.perfetto-trace` | Open a trace in the perfetto UI. |
| `torq -d 10000 --exclude-ftrace-event power/cpu_idle` | Run a custom event for 10 seconds, using the "default" predefined Perfetto config, in which the ftrace event, power/cpu_idle, is not collected. |

## Profiling with Torq

This is the command-line interface for *torq*'s profiler subcommand. This is
the default subcommand in the case where no subcommand is provided. The same
data outlined in the table can viewed via the `torq profiler --help` command.

| Argument | Description | Currently Supported Arguments | Default |
|----------|-------------|-------------------------------|---------|
| `-e, --event` | The event to trace/profile. | `boot`, `user-switch`,`app-startup`, `custom` | `custom` |
| `-p, --profiler` | The performance data profiler. | `perfetto`, (`simpleperf` coming soon) | `perfetto` |
| `-o, --out-dir` | The path to the output directory. | Any local path | Current directory: `.` |
| `-d, --dur-ms` | The duration (ms) of the event. Determines when to stop collecting performance data. | Float >= `3000` | Indefinite until CTRL+C |
| `-a, --app` | The package name of the app to start.<br/>(Requires use of `-e app-startup`) | Any package on connected device ||
| `-r, --runs` | The amount of times to run the event and capture the performance data. | Integer >= `1` | `1` |
| `-s, --simpleperf-event` | Simpleperf supported events that should be collected. Can be defined multiple times in a command. (Requires use of `-p simpleperf`). | Any supported simpleperf event<br/>(e.g., `cpu-cycles`, `instructions`) | `cpu-clock` |
| `--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.) |||
| `--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` |
| `--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` |
| `--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` |
| `--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 |
| `--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 |
| `--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 |
| `--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 ||
| `--symbols` | The device symbols library. (Requires use of `-p simpleperf`). | Path to a device symbols library ||
| `--trigger-names <name<sub>1</sub>> ... <name<sub>n</sub>>` | Adds multiple trigger names. Must be used with Perfetto. |||
| `--trigger-stop-delay-ms <delay<sub>1</sub>> ... <delay<sub>n</sub>>` | Amount of time in milliseconds to continue tracing after a trigger is received. Must be used with Perfetto and --trigger-names. || 1000 |
| `--trigger-timeout-ms <timeout>` | Amount of time in milliseconds Perfetto will wait for a trigger before timing out. Must be used with Perfetto and --trigger-names. || 604800000 |
| `--trigger-mode <mode>` | Sets trigger tracing mode. `stop`/`STOP_TRACING` waits for a trigger and ends tracing `stop-delay-ms` amount of time after a trigger is received, returning all data in the buffer. `start`/`START_TRACING` waits for a trigger and begins tracing when one is received, ending tracing after `stop-delay-ms` amount of time. `clone`/`CLONE_SNAPSHOT` traces until `timeout-ms`, returning a trace with all data in the buffer every time a trigger is received. Must be used with Perfetto and --trigger-names. | `stop`, `start`, `clone`, `STOP_TRACING`, `START_TRACING`, `CLONE_SNAPSHOT` | `STOP_TRACING` |
| `config list` | Subcommand to list the predefined Perfetto configs (`default`, `lightweight`, `memory`). |||
| `config show <config-name>` | Subcommand to print the contents of a predefined Perfetto config to the terminal. | `default`, `lightweight`, `memory` ||
| `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` |
| `open <file-path> [--use_trace_processor]` | Subcommand to open a Perfetto or Simpleperf trace in the Perfetto UI. --use_trace_processor specifies that the trace should be opened with the trace_processor binary regardless of its size. | Any local path to a Perfetto or Simpleperf trace file | [--use_trace_processor]: false |

## Configure perfetto in virtualized Android

Working on a multi-VM environments has its challenges. In order to obtain a unified trace
containing the trace data from multiple VMs you could leverage Perfetto's *traced* and *traced_relay*
binaries. Torq provides commands to greatly simplify the configuration process.

For example, to switch a VM from using `traced` to `traced_relay`, you could run:
```console
torq vm traced-relay enable vsock://3:30001
```
To enable the relay producer port in `traced`, you could run:
```console
torq vm relay-producer enable
```

### CLI Arguments

These are the arguments for the `torq vm` CLI subcommand.

| Argument | Description | Currently Supported Arguments | Default |
|----------|-------------|-------------------------------|---------|
| `traced-relay enable <socket-address>` | Enables traced_relay and uses the *<socket-address>* as the relay socket to communicate with the central traced VM. |    |    |
| `traced-relay disable` | Disables traced_relay and switches to traced. |    |    |
| `relay-producer enable [--address <relay_producer_socket>]` | Enables traced's relay producer support. The `--address` specifies the relay producer socket to use. |    | --address: `vsock://-1:30001`  |
| `relay-producer disable` | Disables traced's relay producer support. |    |    |

## Configure trigger configs for perfetto

When you want to get traces in response to specific code paths, Perfetto's
trigger configs can collect traces when specific triggers are received via the
trigger_perfetto binary. Torq provides commands to add Perfetto triggers to your
trace configs as well as to call the trigger_perfetto binary.

To add a trigger to your config, you could run:
```console
torq --trigger-names trigger1
```

To add a trigger to your config that traces for 10 seconds after the trigger is
received, you could run:
```console
torq --trigger-names trigger1 --trigger-stop-delay-ms 10000
```

To trigger a trace collection, you could run:
```console
torq trigger <trigger-name>
```

### CLI Arguments

These are the arguments that work with the `torq trigger` subcommand. For the
trigger options that work with Perfetto, see 'Profiling with Torq'.

| Argument | Description | Currently Supported Arguments | Default |
|----------|-------------|-------------------------------|---------|
| `trigger <name>` | Subcommand that sends a trigger to Perfetto using the trigger_perfetto binary. |    |    |

## Activate Perfetto triggers

When you want to get traces in response to specific code paths, Perfetto's
trigger configs can collect traces when specific triggers are received via the
trigger_perfetto binary. Torq provides a subcommand to trigger trace collection
for a trigger included in a Perfetto config.

### CLI Arguments

These are the arguments `torq trigger` subcommand.

| Argument         | Description                                                                    | Currently Supported Arguments | Default       |
|------------------|--------------------------------------------------------------------------------|-|---------------|
| `trigger <name>` | Subcommand that sends a trigger to Perfetto using the trigger_perfetto binary. | | |

## Testing Torq

To run **torq**'s test, do:
```bash
./tools/torq_test
```

This will use Bazel as the default build system. If you want to use *Soong*,
you can do:
```bash
./tools/torq_test --android
```

## Contributing to Torq

Before starting development in **torq**'s codebase, run:
```bash
./tools/build_deps
```

Also, before submitting code remember to format the code. Run:
```bash
./tools/format_sources
```