wehub-resource-sync
cb15c5e0d8
Release / Check for new version (push) Has been cancelled
Release / Build macOS ARM64 (push) Has been cancelled
Release / Build macOS x64 (push) Has been cancelled
Release / Build Linux ARM64 (push) Has been cancelled
Release / Build Linux musl ARM64 (push) Has been cancelled
Release / Build Linux musl x64 (push) Has been cancelled
Release / Build Linux x64 (push) Has been cancelled
Release / Build Windows x64 (push) Has been cancelled
Release / Publish to npm (push) Has been cancelled
Release / Publish sandbox package to npm (push) Has been cancelled
Release / Create GitHub Release (push) Has been cancelled
CI / Rust (windows-latest - x86_64-pc-windows-msvc) (push) Has been cancelled
CI / Native E2E Tests (push) Has been cancelled
CI / Windows Integration Test (push) Has been cancelled
CI / Global Install (macos-latest) (push) Has been cancelled
CI / Global Install (ubuntu-latest) (push) Has been cancelled
CI / Version Sync Check (push) Has been cancelled
CI / Rust (push) Has been cancelled
CI / Dashboard (push) Has been cancelled
CI / Sandbox Package (push) Has been cancelled
CI / Rust (macos-latest - aarch64-apple-darwin) (push) Has been cancelled
CI / Rust (macos-latest - x86_64-apple-darwin) (push) Has been cancelled
CI / Global Install (windows-latest) (push) Has been cancelled
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.
|