Andrew ImmandChris Tate
59fa36b6e2
* feat: Enable capture of profiling data Adding a new set of commands: ``` agent-browser profiler start agent-browser profiler stop trace.json ``` With this, agents can start a profiling trace, perform a set of actions, and then extract the profiling data for analysis. **Note:** I was originally going to call it `agent-browser profile` but I realized that might cause confusion with the `--profile` flag CDP supports a couple commands for starting/stopping a trace. When a trace is running, it emits events that need to be picked up. We store these locally in the daemon until the trace is completed. When the final event is received, we dump all of them into an output file. That file can be loaded directly into chrome devtools or another analysis tool to visualize what happened during the agentic run. Added some basic rust tests for parsing the commands (since they have some optional / required args) TS daemon adds ~6 tests to make sure the profiling lifecycle (including saving the output file) works as intended * add docs * fixes * fixes --------- Co-authored-by: Chris Tate <chris@ctate.dev>
3.3 KiB
3.3 KiB
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 tracesv8.execute-- time spent running JavaScriptblink-- renderer eventsblink.user_timing--performance.mark()/performance.measure()callslatencyInfo-- input-to-latency trackingrenderer.scheduler-- task scheduling and executiontoplevel-- 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://tracingin 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.