Profiling

Capture Chrome DevTools performance profiles during browser automation for performance analysis.

Related: commands.md for full command reference, SKILL.md for quick start.

Contents

• Basic Profiling
• Profiler Commands
• Categories
• Use Cases
• Output Format
• Viewing Profiles
• Limitations

Basic Profiling

# Start profiling
agent-browser profiler start

# Perform actions
agent-browser navigate https://example.com
agent-browser click "#button"
agent-browser wait 1000

# Stop and save
agent-browser profiler stop ./trace.json

Profiler Commands

# Start profiling with default categories
agent-browser profiler start

# Start with custom trace categories
agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"

# Stop profiling and save to file
agent-browser profiler stop ./trace.json

Categories

The --categories flag accepts a comma-separated list of Chrome trace categories. Default categories include:

• devtools.timeline -- standard DevTools performance traces
• v8.execute -- time spent running JavaScript
• blink -- renderer events
• blink.user_timing -- performance.mark() / performance.measure() calls
• latencyInfo -- input-to-latency tracking
• renderer.scheduler -- task scheduling and execution
• toplevel -- broad-spectrum basic events

Several disabled-by-default-* categories are also included for detailed timeline, call stack, and V8 CPU profiling data.

Use Cases

Diagnosing Slow Page Loads

agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load load
agent-browser profiler stop ./page-load-profile.json

Profiling User Interactions

agent-browser navigate https://app.example.com
agent-browser profiler start
agent-browser click "#submit"
agent-browser wait 2000
agent-browser profiler stop ./interaction-profile.json

CI Performance Regression Checks

#!/bin/bash
agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load load
agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"

Output Format

The output is a JSON file in Chrome Trace Event format:

{
  "traceEvents": [
    { "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
    ...
  ],
  "metadata": {
    "clock-domain": "LINUX_CLOCK_MONOTONIC"
  }
}

The metadata.clock-domain field is set based on the host platform (Linux or macOS). On Windows it is omitted.

Viewing Profiles

Load the output JSON file in any of these tools:

• Chrome DevTools: Performance panel > Load profile (Ctrl+Shift+I > Performance)
• Perfetto UI: https://ui.perfetto.dev/ -- drag and drop the JSON file
• Trace Viewer: chrome://tracing in any Chromium browser

Limitations

• Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
• Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
• Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.