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.

To start using torq follow these steps:

• Go to torq's directory and build it:

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:

torq -d 7000

torq has support for two build systems: Bazel and Android's Soong.

To build and use torq using Bazel, run:

bazel build //:torq
./bazel-bin/torq --help

To build with Android's Soong, run:

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

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.

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.

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:

torq vm traced-relay enable vsock://3:30001

To enable the relay producer port in traced, you could run:

torq vm relay-producer enable

These are the arguments for the torq vm CLI subcommand.

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:

torq --trigger-names trigger1

To add a trigger to your config that traces for 10 seconds after the trigger is received, you could run:

torq --trigger-names trigger1 --trigger-stop-delay-ms 10000

To trigger a trace collection, you could run:

torq trigger <trigger-name>

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

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.

These are the arguments torq trigger subcommand.

To run torq's test, do:

./tools/torq_test

This will use Bazel as the default build system. If you want to use Soong, you can do:

./tools/torq_test --android

Before starting development in torq's codebase, run:

./tools/build_deps

Also, before submitting code remember to format the code. Run:

./tools/format_sources