profile-dart-code

--- 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.

## 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.