24860ec3f1
Update SKILL.md to match the latest upstream skill from vercel-labs/agent-browser, adding substantial new capabilities: - Authentication (auth vault, profiles, session persistence, state files) - Command chaining, annotated screenshots, diffing - Security features (content boundaries, domain allowlist, action policy) - iOS Simulator support, Lightpanda engine, downloads, clipboard - JS eval improvements (--stdin, -b for shell safety) - Timeout guidance, config files, session cleanup Add 7 reference docs (commands, authentication, snapshot-refs, session-management, video-recording, profiling, proxy-support) and 3 ready-to-use shell templates. Kept our YAML frontmatter, setup check section, and Playwright MCP comparison table which are unique to our plugin context.
121 lines
3.3 KiB
Markdown
121 lines
3.3 KiB
Markdown
# Profiling
|
|
|
|
Capture Chrome DevTools performance profiles during browser automation for performance analysis.
|
|
|
|
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
|
|
|
|
## Contents
|
|
|
|
- [Basic Profiling](#basic-profiling)
|
|
- [Profiler Commands](#profiler-commands)
|
|
- [Categories](#categories)
|
|
- [Use Cases](#use-cases)
|
|
- [Output Format](#output-format)
|
|
- [Viewing Profiles](#viewing-profiles)
|
|
- [Limitations](#limitations)
|
|
|
|
## Basic Profiling
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
#!/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:
|
|
|
|
```json
|
|
{
|
|
"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.
|