profile-dart-code · diff
git:20260711.2c9d0bd to git:20260912.57dc63f
14 added, 0 removed. Audit B to B.
---
name: profile-dart-code
description: |-
Profile Dart command-line applications using the VM Service protocol to
capture CPU samples and identify performance bottlenecks. Helps agents
automate CPU profiling, generate function call breakdown summaries, and
export JSON profiles without a browser or DevTools.
key_features:
- Automated VM Service WebSocket connection
- CPU sampling and top-function call summary
- JSON trace export for further analysis
---
# Dart CPU Profiling
Guidelines and automated tools for capturing CPU profiles and identifying
bottlenecks in Dart command-line applications.
## When to use this skill
- When asked to profile, optimize, or benchmark CPU execution of a Dart script
or CLI tool.
- When investigating hot loops, heavy function calls, or unexpected execution
overhead.
+ ### When NOT to use (Abstention Guardrails)
+
+ Do NOT profile using this skill when:
+ - **Pure I/O-Bound Bottlenecks**: The performance bottleneck is network
+ latency, database queries, or disk I/O wait rather than CPU execution.
+ - **Flutter UI Applications**: The target is a Flutter application requiring
+ frame profiling, raster thread inspection, or widget rebuild tracking (use
+ Flutter DevTools or `widget_inspector`).
+ - **Short-Lived Micro-Benchmarks**: Micro-benchmarks running for only a few
+ milliseconds where VM warmup and sampling overhead skew results (use
+ `package:benchmark_harness` or `package:bench_press` instead).
+ - **Target Does Not Run Cleanly**: If the target script fails to compile or
+ crashes on startup, fix functional bugs before attempting CPU profiling.
+
## Workflow
1. **Ensure clean compilation**: Make sure the target Dart script runs cleanly
(`dart run <script.dart>`).
2. **Run Profiler Script**: Use the automated profiling helper script inside
this skill directory to launch the target app with VM Service observability
enabled, capture CPU samples, and output top-consuming functions.
3. **Analyze & Optimize**: Review the self and total sample percentages
reported by the tool to pinpoint bottlenecks (e.g., excessive object
allocation, costly hashing, virtual dispatch overhead).
## Running the Profiler Helper Script
This repository includes a zero-dependency (using only official `vm_service`)
profiling script that launches any Dart file, connects to the VM Service, waits
for execution to complete (`--pause-isolates-on-exit`), retrieves CPU samples,
and prints a clean summary while exporting the full JSON profile.
Run it from any working directory:
```bash
dart run <dash_skills_repo>/skills/profile-dart-code/scripts/bin/profile.dart --out=cpu_profile.json -- <path_to_target.dart> [target_arguments...]
```
### Script Arguments
- `-o, --out=<file>`: Output file path to save the raw JSON CPU profile
(default: `cpu_profile.json`).
- `-p, --period=<micros>`: Sampling interval in microseconds (default: `1000`µs
= 1ms). Minimum `50`µs.
- `-- <target.dart> [args...]`: The Dart script to profile, followed by any
arguments passed to `main()`.
> [!WARNING]
> **Potential Hangs**: When profiling or debugging Dart targets using VM services,
> target exceptions or connection issues can cause the process to hang
> indefinitely. Ensure your target script handles timeouts, and monitor the
> process output.
### Example Output
```
Connecting to VM service at ws://127.0.0.1:8181/ws...
Target execution paused at exit. Retrieving CPU profile samples...
=== Top CPU Functions (Self Samples) ===
1. _PuzzleSmart._shiftSlice (self: 34.2%, total: 41.0%)
2. _countInversions (self: 18.5%, total: 18.5%)
3. shortestPaths (self: 12.1%, total: 98.4%)
Saved complete JSON profile to: cpu_profile.json
```
## Best Practices for Interpreting Profiles
1. **Focus on Self % vs. Total %**: High `self %` indicates where CPU time is
spent directly inside a function's own body (math, loop branching, array
indexing). High `total %` with low `self %` indicates a dispatcher or outer
orchestration loop.
2. **Look for Hidden Overhead**: Watch out for implicit object allocations
(`_copyData`, iterator wrappers, closure creation) inside tight loops.
3. **Verify Optimizations Empirically**: Always record baseline sample counts
and execution duration (`time -v`) before and after applying optimizations.