Add Performance Profiling Heatmap Visualization to Atmos CLI #1576
Conversation
aknysh
added
minor
|
Warning This PR exceeds the recommended limit of 1,000 lines.Large PRs are difficult to review and may be rejected due to their size. Please verify that this PR does not address multiple issues. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
website/docs/troubleshoot/profiling.mdx (5)
96-99: Bold: Make top‑N limits explicit in bar/sparkline sectionsCall out the top‑25 cap to set expectations.
Apply this diff:
- Best for identifying relative performance differences - Color-coded gradient highlights hot functions - Easy visual comparison + - Shows top 25 functions by total time @@ - Compact view of many functions - Shows execution time distribution - Quick pattern recognition + - Shows top 25 functions by total timeAlso applies to: 108-111
188-196: Bold: Safer baseline/optimized captureExamples use 2> which assumes the summary is on stderr. Prefer capturing both streams for portability.
Apply this diff:
-# Baseline measurement -atmos describe stacks --heatmap 2>baseline.txt - -# After optimization -atmos describe stacks --heatmap 2>optimized.txt +# Baseline measurement +atmos describe stacks --heatmap 2>&1 | tee baseline.txt >/dev/null + +# After optimization +atmos describe stacks --heatmap 2>&1 | tee optimized.txt >/dev/nullIf the summary is guaranteed on stdout, switch to simple redirection (>) instead.
516-520: Bold: “Zero overhead” phrasingWith defer perf.Track() in many functions, disabled mode still incurs minimal call/defer overhead. Soften the claim.
Apply this diff:
-- **Enable only when needed**: Zero overhead when not using `--heatmap` flag +- **Enable only when needed**: Negligible overhead when `--heatmap` is not used (tracking is disabled)
283-285: Bold: Cross‑platform browser openingopen is macOS‑specific. Consider adding xdg-open example for Linux.
Suggested addition after the block:
Linux: xdg-open http://localhost:6060/debug/pprof/ Windows: start http://localhost:6060/debug/pprof/
617-623: Bold: Remove bc dependency in CI examplebc may not be available in minimal runners. Use awk for numeric compare.
Example:
elapsed_ms=$(grep -m1 "Elapsed:" perf-output.txt | awk '{print $2}' | sed 's/ms//') awk -v e="$elapsed_ms" 'BEGIN{exit !(e > 500)}' || { echo "Performance regression: ${elapsed_ms} > 500ms" atmos validate stacks --profile-file=cpu.prof --profile-type=cpu exit 1 }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
website/docs/troubleshoot/profiling.mdx(10 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases
Files:
website/docs/troubleshoot/profiling.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Build (ubuntu-latest, linux)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: Run pre-commit hooks
- GitHub Check: website-deploy-preview
- GitHub Check: Summary
🔇 Additional comments (2)
website/docs/troubleshoot/profiling.mdx (2)
1-6: Bold: Path/name consistency with PR descriptionPR summary references docs at /docs/troubleshoot/performance-heatmap, but this file is profiling.mdx. Please ensure nav, links, and any references are consistent (redirect or align paths).
560-563: Bold: Align non‑TTY fallback message with actual implementationVerify the exact message text emitted by the CLI and mirror it verbatim to avoid confusion.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
website/docs/troubleshoot/profiling.mdx(9 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in website/ when adding features
Ensure consistency between CLI help text and website documentation
Follow the website's documentation structure and style
Keep website code in website/ and follow its architecture/style; test changes locally
Keep CLI and website documentation in sync; document new features with examples and use cases
Files:
website/docs/troubleshoot/profiling.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: Build (ubuntu-latest, linux)
- GitHub Check: Build (macos-latest, macos)
- GitHub Check: Build (windows-latest, windows)
- GitHub Check: website-deploy-preview
- GitHub Check: Analyze (go)
- GitHub Check: Lint (golangci)
- GitHub Check: Run pre-commit hooks
- GitHub Check: Summary
aknysh
added
no-release
|
These changes were released in v1.193.0-rc.0. |
what
why
Performance Heatmap Feature
Atmos now includes built-in performance tracking that shows you exactly which operations are taking the longest time. This feature provides real-time visibility into function execution times with interactive visualization modes.
Quick Start
Run any Atmos command with the
--heatmapflag:Real Performance Analysis Example
Here's actual output from
atmos describe stacks --heatmap:Bar Chart View (Press
1in interactive mode):Performance Output
Visualization Modes
The interactive TUI supports three visualization modes:
1: Bar Chart - Color gradient from red (slow) to green (fast) showing relative execution times2: Sparklines - Visual trend lines for each function3: Table View - Detailed metrics with Count/Total/Avg/Max/P95 (top 50 functions by total time)Navigation & Controls
↑/↓ork/j: Navigate through rows (wraparound enabled)1-3: Switch visualization modesq/esc: Exit and return to terminalCLI Flags
All flag descriptions now match
atmos --helpoutput exactly:--heatmap: Show performance heatmap visualization after command execution (includes P95 latency) (default: false)--heatmap-mode: Heatmap visualization mode: bar, sparkline, table (press 1-3 to switch in TUI) (default: bar)Comparison with Traditional Profiling
Implementation Details
defer perf.Track()instrumentation to 150+ functions across critical paths/docs/troubleshoot/profiling.mdxTesting
✅ All tests passing with coverage >80%
✅ Comprehensive test suite for heatmap TUI (17 test functions)
✅ GitHub utils tests (11 test functions)
✅ Enhanced pro.go tests (11 additional test functions)
✅ Linter checks passing (0 issues)
✅ Website builds successfully with no broken links
✅ Performance tracking verified with real Atmos workflows
Documentation
/docs/troubleshoot/profiling.mdxCLAUDE.mdwith mandatory performance tracking patternsKey Documentation Updates
performance-heatmap.mdxinto unifiedprofiling.mdxatmos --helpoutput/troubleshoot/loggingto/troubleshoot/debuggingSummary by CodeRabbit
New Features
Telemetry
Documentation
Chores
Tests