Skip to content

profiling.md

Latest commit

 

History

History
120 lines (88 loc) · 3.33 KB

profiling.md

File metadata and controls

120 lines (88 loc) · 3.33 KB

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

# 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 networkidle
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 networkidle
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.