automated-tracing

name	automated-tracing
description	Automated Tracing & Performance Telemetry in Chromium using Perfetto and Telemetry benchmarks. Use when you need to launch the browser binary, execute a specific scenario/story, and collect Perfetto traces. Don't use for trace analysis (use analyzing-sql-traces).

Automated Tracing & Performance Telemetry

This skill guides the agent through the process of automated tracing in Chromium to capture performance profiles on Desktop or Android Device/Emulator.

1. Prerequisites

For Desktop (Linux/Mac/Windows)

• A compiled Chrome executable (typically out/Default/chrome).
• A targeted Scenario/Story (e.g., omnibox:search inside the desktop_ui benchmark).

For Android (Device/Emulator)

• A compiled Chrome Android APK (typically out/emulator/apks/ChromePublic.apk).
• A pre-connected Android device or running emulator.
• A targeted Scenario/Story (e.g., system_health.common_mobile benchmark).

---

2. Safety & Sandbox Compliance (Zero-Grant Rule)

To prevent triggering user permission/access grant prompts during automated execution:

• ALWAYS redirect Telemetry output artifacts to the parent E2E session's unified capture directory inside the workspace: out/e2e_nla_run_{parent_session_id}/capture/ (where {parent_session_id} is passed by the Orchestrator).
• NEVER call command-line utilities like mkdir, ls, touch, or rm via shell commands.
• NEVER run terminal verification commands (such as python3 -c "import os; ..." or ls -lh or test -f) to check file existence or size.
• ALWAYS rely on standard python script APIs or built-in benchmark tool logic to create directories programmatically.
• ALWAYS let down-stream tools (like the trace analyzer script) perform validation internally. If the trace is invalid or empty, the analyzer will fail loudly and safely.
• NEVER let Telemetry write to the default tools/perf/artifacts/ workspace directory.

---

3. Execution & Capture Workflow

Step A: Identify Target Android Device (Android Only)

Before running the benchmark on Android, identify the connected device/emulator:

1. Run adb devices to list the attached devices.
2. Select the target device serial based on the following rules:
   • Zero devices found: Abort the execution and ask the user to connect a device or start an emulator.
   • One device found: Automatically select this device serial.
   • Multiple devices found:
     • If a specific device argument/serial is provided, match against it.
     • Otherwise, present the list of connected devices to the user and ask them to select one.

Step B: Execute Telemetry Benchmark

Select either Cold Run (default) or Warm Run based on the investigation requirements.

1. For Cold Runs (Default)

No pre-warmup is needed. Telemetry will automatically start with a clean profile.

For Desktop: Run the run_benchmark command directly using the xvfb.py virtual display wrapper:

./testing/xvfb.py vpython3 tools/perf/run_benchmark run desktop_ui \
  --story={story_name} \
  --browser=exact \
  --browser-executable={chrome_binary} \
  --extra-chrome-categories=omnibox,navigation,blink,cc,gpu,toplevel \
  --output-dir=out/e2e_nla_run_{parent_session_id}/capture/

For Android (Device/Emulator): Run the run_benchmark command with the --device argument set to the identified device serial:

vpython3 tools/perf/run_benchmark run {benchmark_name} \
  --story={story_name} \
  --browser=exact \
  --browser-executable=out/emulator/apks/ChromePublic.apk \
  --device={device_serial} \
  --extra-chrome-categories=omnibox,navigation,blink,cc,gpu,toplevel,net,Java \
  --output-dir=out/e2e_nla_run_{parent_session_id}/capture/

2. For Warm Runs (GPU & HTTP Caches Warmed)

To capture a warm run (bypassing GPU shader compilation and static network loading), you should use the automated wrapper script run_warm_benchmark.py.

The script automatically coordinates the warmup run, profile migration/cleanup, final warm run, and temporary directory deletion.

For Android:

vpython3 .agents/skills/automated-tracing/scripts/run_warm_benchmark.py \
  --benchmark={benchmark_name} \
  --story={story_name} \
  --browser-executable=out/emulator/apks/ChromePublic.apk \
  --device={device_serial} \
  --output-dir=out/e2e_nla_run_{parent_session_id}/capture/ \
  [--delete-state] \
  --extra-chrome-categories=omnibox,navigation,blink,cc,gpu,toplevel,net,Java \
  [extra_args...]

For Desktop:

vpython3 .agents/skills/automated-tracing/scripts/run_warm_benchmark.py \
  --benchmark=desktop_ui \
  --story={story_name} \
  --browser-executable=out/Default/chrome \
  --output-dir=out/e2e_nla_run_{parent_session_id}/capture/ \
  [--delete-state] \
  --extra-chrome-categories=omnibox,navigation,blink,cc,gpu,toplevel,net \
  [extra_args...]

(Note: The script automatically detects if a display is present on Linux and wraps the desktop Chrome execution with xvfb.py if needed. Any unrecognized extra arguments [extra_args...] are forwarded directly to the underlying run_benchmark commands.)

Step C: Locate the Captured Trace

Once the benchmark completes successfully, find the Perfetto trace file inside the redirected folder. The path structure is: out/e2e_nla_run_{parent_session_id}/capture/artifacts/run_{timestamp}/{story_sanitized}_1/trace/trace.pb

Verify the trace exists and is non-empty.

---

4. Output Contract

Report back to the caller with the absolute path of the captured trace:

{
  "status": "SUCCESS",
  "trace_file_path": "out/e2e_nla_run_{parent_session_id}/capture/artifacts/run_{timestamp}/{story_sanitized}_1/trace/trace.pb",
  "build_dir": "out/emulator/"
}