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.
Workflow
- Ensure clean compilation: Make sure the target Dart script runs cleanly
(
dart run <script.dart>).
- 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.
- 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:
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
- 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.
- Look for Hidden Overhead: Watch out for implicit object allocations
(
_copyData, iterator wrappers, closure creation) inside tight loops.
- Verify Optimizations Empirically: Always record baseline sample counts
and execution duration (
time -v) before and after applying optimizations.
1---2name: profile-dart-code3description: |-4 Profile Dart command-line applications using the VM Service protocol to5 capture CPU samples and identify performance bottlenecks. Helps agents6 automate CPU profiling, generate function call breakdown summaries, and7 export JSON profiles without a browser or DevTools.8key_features:9 - Automated VM Service WebSocket connection10 - CPU sampling and top-function call summary11 - JSON trace export for further analysis12metadata:13 source: https://skillmd.com/skills/kevmoo/profile-dart-code14---1516# Dart CPU Profiling1718Guidelines and automated tools for capturing CPU profiles and identifying19bottlenecks in Dart command-line applications.2021## When to use this skill22- When asked to profile, optimize, or benchmark CPU execution of a Dart script23 or CLI tool.24- When investigating hot loops, heavy function calls, or unexpected execution25 overhead.2627## Workflow281. **Ensure clean compilation**: Make sure the target Dart script runs cleanly29 (`dart run <script.dart>`).302. **Run Profiler Script**: Use the automated profiling helper script inside31 this skill directory to launch the target app with VM Service observability32 enabled, capture CPU samples, and output top-consuming functions.333. **Analyze & Optimize**: Review the self and total sample percentages34 reported by the tool to pinpoint bottlenecks (e.g., excessive object35 allocation, costly hashing, virtual dispatch overhead).3637## Running the Profiler Helper Script3839This repository includes a zero-dependency (using only official `vm_service`)40profiling script that launches any Dart file, connects to the VM Service, waits41for execution to complete (`--pause-isolates-on-exit`), retrieves CPU samples,42and prints a clean summary while exporting the full JSON profile.4344Run it from any working directory:45```bash46dart run <dash_skills_repo>/skills/profile-dart-code/scripts/bin/profile.dart --out=cpu_profile.json -- <path_to_target.dart> [target_arguments...]47```4849### Script Arguments50- `-o, --out=<file>`: Output file path to save the raw JSON CPU profile51 (default: `cpu_profile.json`).52- `-p, --period=<micros>`: Sampling interval in microseconds (default: `1000`µs53 = 1ms). Minimum `50`µs.54- `-- <target.dart> [args...]`: The Dart script to profile, followed by any55 arguments passed to `main()`.5657> [!WARNING]58> **Potential Hangs**: When profiling or debugging Dart targets using VM services,59> target exceptions or connection issues can cause the process to hang60> indefinitely. Ensure your target script handles timeouts, and monitor the61> process output.6263### Example Output64```65Connecting to VM service at ws://127.0.0.1:8181/ws...66Target execution paused at exit. Retrieving CPU profile samples...6768=== Top CPU Functions (Self Samples) ===69 1. _PuzzleSmart._shiftSlice (self: 34.2%, total: 41.0%)70 2. _countInversions (self: 18.5%, total: 18.5%)71 3. shortestPaths (self: 12.1%, total: 98.4%)7273Saved complete JSON profile to: cpu_profile.json74```7576## Best Practices for Interpreting Profiles771. **Focus on Self % vs. Total %**: High `self %` indicates where CPU time is78 spent directly inside a function's own body (math, loop branching, array79 indexing). High `total %` with low `self %` indicates a dispatcher or outer80 orchestration loop.812. **Look for Hidden Overhead**: Watch out for implicit object allocations82 (`_copyData`, iterator wrappers, closure creation) inside tight loops.833. **Verify Optimizations Empirically**: Always record baseline sample counts84 and execution duration (`time -v`) before and after applying optimizations.