README
ΒΆ
gobench
A powerful CLI tool for running and comparing Go benchmark tests. gobench makes it easy to track performance over time by saving benchmark results, providing detailed comparisons, statistical analysis, and CI/CD integration.
Features
- Interactive Web Dashboard: Real-time visualization with charts, trends, and performance insights
- Run Benchmarks: Execute Go benchmarks with custom filters and package paths
- Save Results: Automatically save benchmark results with metadata (timestamp, Go version, duration)
- CPU/Memory Profiling: Generate and analyze CPU and memory profiles with flame graphs
- Profile Analysis: Automatic detection of hot functions, memory leaks, and optimization opportunities
- Flame Graph Visualization: Interactive web UI for viewing CPU and memory profiles
- Optimization Suggestions: AI-powered recommendations based on profile analysis
- Compare Results: Compare two benchmark runs to see performance improvements or degradations
- Export Reports: Export comparisons to HTML, CSV, or Markdown formats
- Statistical Analysis: Analyze multiple runs with mean, median, standard deviation, and stability metrics
- Trend Analysis: Track performance trends over time with linear regression
- CI/CD Integration: Automated threshold checking for continuous integration pipelines
- Track History: List all saved benchmark results with timestamps
- Easy Management: Delete old benchmark results to keep your workspace clean
Installation
Quick Install (Recommended)
macOS & Linux - One-line install without Go:
curl -sSL https://raw.githubusercontent.com/alenon/gobench/main/install.sh | bash
macOS with Homebrew:
brew install alenon/tap/gobench
Manual Installation (Pre-built Binaries)
Download pre-built binaries from GitHub Releases:
macOS (Apple Silicon M1/M2/M3):
curl -L https://github.com/alenon/gobench/releases/latest/download/gobench-darwin-arm64.tar.gz | tar xz
sudo mv gobench-darwin-arm64 /usr/local/bin/gobench
macOS (Intel):
curl -L https://github.com/alenon/gobench/releases/latest/download/gobench-darwin-amd64.tar.gz | tar xz
sudo mv gobench-darwin-amd64 /usr/local/bin/gobench
Linux (x86_64):
curl -L https://github.com/alenon/gobench/releases/latest/download/gobench-linux-amd64.tar.gz | tar xz
sudo mv gobench-linux-amd64 /usr/local/bin/gobench
Linux (ARM64):
curl -L https://github.com/alenon/gobench/releases/latest/download/gobench-linux-arm64.tar.gz | tar xz
sudo mv gobench-linux-arm64 /usr/local/bin/gobench
Windows:
Download gobench-windows-amd64.exe.zip from the releases page, extract, and add to PATH.
Install with Go
If you have Go installed:
go install github.com/alenon/gobench/cmd/gobench@latest
Build from Source
git clone https://github.com/alenon/gobench.git
cd gobench
make build
# Binary will be in ./bin/gobench
GitHub Action
The easiest way to integrate gobench into your CI/CD pipeline is to use the official GitHub Action:
- name: Run benchmarks
uses: alenon/gobench@v1
with:
packages: './...'
threshold-percent: 10
enable-profiling: 'cpu,mem'
trend-analysis-runs: 10
export-format: 'html'
Features:
- Zero configuration - Works out of the box
- Automatic comparison - Compares against baseline
- Beautiful HTML reports - Interactive charts and graphs with Chart.js
- CPU/Memory profiling - Identify performance bottlenecks
- Trend analysis - Track performance over time
- Statistical analysis - Stability metrics across runs
- PR integration - Posts results as PR comments
- Multiple formats - Export to HTML, CSV, Markdown
- Artifact uploads - Automatically uploads reports and profiles
For detailed documentation, examples, and advanced usage, see ACTION.md.
Example workflows are available in examples/workflows/.
Quick Start
# Run benchmarks
gobench run -pkg=./...
# Start interactive web dashboard
gobench serve
# Run benchmarks with CPU and memory profiling
gobench run --profile=cpu,mem
# View flame graphs in browser
gobench flamegraph --latest
# Compare last two runs
gobench compare --latest
# Export to HTML
gobench export --latest -format=html
# Check threshold (for CI/CD)
gobench check --latest -threshold=10
Usage
Running Benchmarks
Run all benchmarks in the current package:
gobench run
Run benchmarks with a specific filter:
gobench run -bench=BenchmarkStringBuilder
Run benchmarks in a specific package or all packages:
gobench run -pkg=./examples
gobench run -pkg=./...
Custom storage directory:
gobench run -storage=./my-results
CPU and Memory Profiling
gobench includes powerful profiling capabilities that go beyond basic benchmarking. Generate CPU and memory profiles to identify performance bottlenecks, memory leaks, and optimization opportunities.
Running Benchmarks with Profiling
Enable CPU profiling:
gobench run --profile=cpu
Enable memory profiling:
gobench run --profile=mem
Enable both CPU and memory profiling:
gobench run --profile=cpu,mem
When profiling is enabled, gobench will:
- Generate pprof profile files during benchmark execution
- Automatically analyze the profiles
- Identify hot functions and memory allocation patterns
- Detect potential memory leaks
- Provide actionable optimization suggestions
Viewing Flame Graphs
After running benchmarks with profiling enabled, you can view interactive visualizations:
# View profiles for a specific run
gobench flamegraph run-123
# View profiles for the latest run
gobench flamegraph --latest
This starts a web server (default port 8080) that provides:
- CPU Flame Graphs: Visualize where your code spends time
- Memory Flame Graphs: See memory allocation patterns
- Side-by-side Comparison: Compare CPU and memory profiles
- Download Options: Download raw profile files for use with
go tool pprof
Access the visualization at http://localhost:8080
Profile Analysis Output
When you run benchmarks with profiling enabled, you'll see detailed analysis:
PROFILE ANALYSIS
================================================================================
π₯ CPU Hot Functions (Total samples: 12543)
--------------------------------------------------------------------------------
Function Flat% Cum%
runtime.mallocgc 15.2% 45.8%
mypackage.processData 12.7% 32.1%
encoding/json.Marshal 8.3% 18.9%
πΎ Memory Hot Functions (Total: 245.3 MB)
--------------------------------------------------------------------------------
Function Flat% Bytes
mypackage.allocateBuffer 28.5% 69.9 MB
strings.Builder.Grow 15.2% 37.3 MB
π― Hot Execution Paths
--------------------------------------------------------------------------------
1. 32.5% of execution time (4078 samples)
Critical path consuming 32.5% of execution time
Path: main.main β processRequests β handleRequest β parseJSON
β οΈ Potential Memory Issues
--------------------------------------------------------------------------------
π΄ mypackage.cacheData (high)
Allocations: 15234 (125.6 MB)
Allocated 125.6 MB but much less in use - potential leak
π‘ Optimization Suggestions
================================================================================
1. π΄ [CPU] mypackage.processData
Issue: Function consumes 12.7% of CPU time
Suggestion: Consider optimizing this hot function - profile it in isolation
Potential Impact: Could improve overall performance by up to 8.9%
2. π΄ [MEMORY] mypackage.allocateBuffer
Issue: Function allocates 28.5% of total memory
Suggestion: Consider using sync.Pool or pre-allocate with appropriate capacity
Potential Impact: Could significantly reduce allocation pressure and GC overhead
Profile Features
CPU Profile Analysis:
- Top CPU-consuming functions (by flat and cumulative time)
- Hot execution paths (critical call chains)
- CPU time distribution
Memory Profile Analysis:
- Top memory-allocating functions
- Total memory allocated
- Potential memory leak detection
Optimization Suggestions:
- High-severity issues requiring immediate attention
- Medium-severity improvements
- Low-severity optimizations
- Expected impact of each optimization
Flame Graph Visualization:
- Interactive web-based viewer
- CPU and memory flame graphs
- Side-by-side comparison view
- Download raw profiles for advanced analysis
Advanced Profiling Workflow
For comprehensive performance analysis:
# 1. Run benchmarks with profiling
gobench run --profile=cpu,mem
# 2. View the profile summary in terminal (automatic)
# The analysis is displayed immediately after benchmarks complete
# 3. Open flame graphs in browser
gobench flamegraph --latest
# 4. For advanced analysis, download profiles and use go tool pprof
# The profile paths are shown in the output
go tool pprof -http=:8080 .gobench/profiles/run-123/cpu.prof
Integration with go tool pprof
All profiles are stored in .gobench/profiles/<run-id>/ and are compatible with standard Go profiling tools:
# Interactive terminal UI
go tool pprof .gobench/profiles/run-123/cpu.prof
# Generate flame graph
go tool pprof -http=:8080 .gobench/profiles/run-123/cpu.prof
# Generate call graph
go tool pprof -pdf .gobench/profiles/run-123/cpu.prof > callgraph.pdf
# Top functions
go tool pprof -top .gobench/profiles/run-123/cpu.prof
AI-Powered Analysis
gobench includes an AI analyzer that provides intelligent insights and optimization suggestions for your benchmark results. The AI analyzer uses free AI services to understand your profiling data and comparison results, offering actionable recommendations.
Quick Start
Enable AI analysis with a single environment variable:
# Enable AI analysis
export GOBENCH_AI_ENABLED=true
# Run benchmarks with profiling
gobench run --profile=cpu,mem
# Compare runs with AI insights
gobench compare --latest
Supported AI Providers
Ollama (Recommended for local use)
- Completely free, no API keys required
- Private - your data stays on your machine
- Install: https://ollama.ai/
# Setup Ollama
ollama pull llama3.2
ollama serve &
# Enable in gobench
export GOBENCH_AI_ENABLED=true
export GOBENCH_AI_PROVIDER=ollama
OpenAI (GPT-4o, GPT-4-turbo)
- State-of-the-art performance
- Requires API key from https://platform.openai.com/api-keys
export GOBENCH_AI_ENABLED=true
export GOBENCH_AI_PROVIDER=openai
export GOBENCH_AI_API_KEY=sk-your-openai-key
export GOBENCH_AI_MODEL=gpt-4o
Anthropic Claude (Sonnet 4.5, Haiku 4.5)
- Excellent reasoning and analysis
- Requires API key from https://console.anthropic.com
export GOBENCH_AI_ENABLED=true
export GOBENCH_AI_PROVIDER=anthropic
export GOBENCH_AI_API_KEY=sk-ant-your-key
export GOBENCH_AI_MODEL=claude-sonnet-4-5-20250929
Google Gemini (Gemini 2.5 Flash, 2.0 Flash)
- Very affordable and fast
- Free tier available through Google AI Studio
- Requires API key from https://aistudio.google.com/apikey
export GOBENCH_AI_ENABLED=true
export GOBENCH_AI_PROVIDER=gemini
export GOBENCH_AI_API_KEY=your-google-api-key
export GOBENCH_AI_MODEL=gemini-2.5-flash
Groq (Fast cloud inference)
- Very fast inference with free tier
- Requires API key from https://console.groq.com
export GOBENCH_AI_ENABLED=true
export GOBENCH_AI_PROVIDER=groq
export GOBENCH_AI_API_KEY=your-api-key
OpenAI-Compatible (LM Studio, LocalAI, Cursor, etc.)
- Works with any OpenAI-compatible API
- Supports local and custom deployments
export GOBENCH_AI_ENABLED=true
export GOBENCH_AI_PROVIDER=openai-compatible
export GOBENCH_AI_BASE_URL=http://localhost:1234/v1
export GOBENCH_AI_MODEL=local-model
What the AI Analyzer Does
- Enhanced Profile Analysis: AI examines CPU hotspots, memory allocations, and hot paths to provide deeper insights than rule-based analysis
- Intelligent Suggestions: Get specific, actionable optimization recommendations with context about why they matter
- Comparison Insights: Understand performance changes between runs with explanations of likely causes
- Pattern Recognition: AI identifies common performance anti-patterns and suggests proven solutions
For detailed configuration and usage, see AI_ANALYZER.md.
Interactive Web Dashboard
The interactive web dashboard provides a comprehensive, real-time visualization interface for all your benchmark data. It's the easiest way to analyze trends, compare runs, and share results with your team.
Starting the Dashboard
Start the dashboard server:
# Start on default port (8080)
gobench serve
# Start on custom port
gobench serve -port=9000
# Allow remote access
gobench serve -addr=0.0.0.0
Then open your browser to http://localhost:8080
Dashboard Features
Overview Tab:
- Real-time statistics (total runs, tests, benchmarks)
- Recent performance trends chart
- Quick access to recent benchmark runs
Trends Tab:
- Historical performance graphs with Chart.js
- Multi-line charts showing performance over time
- Statistical analysis (mean, median, std dev, CV)
- Automatic trend detection (improving/degrading/stable)
- Filter by specific benchmarks
- Customizable time range (10, 25, 50, or 100 runs)
History Tab:
- Complete benchmark run history
- Sortable and filterable table
- Search by package name or run ID
- Click any run to view details
Compare Tab:
- Side-by-side comparison of any two runs
- Performance deltas with color-coded indicators
- Percentage improvements and degradations
Additional Features:
- π Dark mode with persistent theme preference
- π Global search across all runs and benchmarks
- π Shareable URLs for specific runs
- π± Responsive design for mobile and tablet
- π¨ Beautiful, modern UI with smooth animations
Embed Mode
Embed the dashboard in your documentation:
<iframe
src="http://localhost:8080?embed=true&tab=trends"
width="100%"
height="600px">
</iframe>
For detailed documentation, see docs/DASHBOARD.md.
Listing Results
List all saved benchmark results:
gobench list
Output example:
ID Timestamp Benchmarks Duration Package
-- --------- ---------- -------- -------
run-1699123456 2024-11-04 15:30:56 10 2.5s ./examples
run-1699123123 2024-11-04 15:25:23 10 2.3s ./examples
Comparing Results
Compare two specific benchmark runs:
gobench compare run-1699123123 run-1699123456
Compare the last two runs:
gobench compare --latest
Output example:
Comparing: run-1699123123 (2024-11-04 15:25:23) vs run-1699123456 (2024-11-04 15:30:56)
β StringBuilder 12345.67 ns/op β 11234.56 ns/op (-9.00%)
β StringConcatenation 98765.43 ns/op β 102345.67 ns/op (+3.63%)
~ StringJoin 45678.90 ns/op β 45912.34 ns/op (+0.51%)
Summary: 1 improved, 1 degraded, 1 unchanged
Status indicators:
βImproved performance (lower is better)βDegraded performance~No significant change (within 5% threshold)
Exporting Results
Export comparisons to various formats:
HTML Report (with beautiful styling):
gobench export --latest -format=html -output=report.html
CSV (for spreadsheet analysis):
gobench export --latest -format=csv -output=results.csv
Markdown (for documentation):
gobench export --latest -format=markdown -output=comparison.md
Compare specific runs:
gobench export run-123 run-456 -format=html
Statistical Analysis
Analyze multiple benchmark runs to understand stability and variation:
# Analyze all runs
gobench stats
# Analyze last 5 runs
gobench stats -last=5
# Custom stability threshold
gobench stats -last=10 -cv-threshold=15
Output example:
Statistical Analysis (5 runs)
Runs: 2024-11-04 10:00:00 to 2024-11-04 15:30:00
Benchmark Statistics:
----------------------------------------------------------------------------------------------------
StringBuilder Count: 5 | Mean: 362.45 ns/op | Median: 363.20 ns/op | StdDev: 4.12 (Β±1.1%) | Range: [358.30 - 367.50] β Stable
StringConcatenation Count: 5 | Mean: 5234.67 ns/op | Median: 5198.40 ns/op | StdDev: 234.89 (Β±4.5%) | Range: [4986.20 - 5543.10] β Stable
Metrics:
- Count: Number of benchmark runs analyzed
- Mean: Average performance across runs
- Median: Middle value (less affected by outliers)
- StdDev: Standard deviation (variation measure)
- CV: Coefficient of variation (% - lower is more stable)
- Range: Min and max values observed
Trend Analysis
Track performance trends over time:
# Analyze last 10 runs
gobench trend -last=10
# Analyze specific benchmark
gobench trend -benchmark=BenchmarkStringBuilder -last=20
Output example:
Performance Trend Analysis (10 runs)
Period: 2024-11-01 10:00:00 to 2024-11-04 15:30:00
Benchmark: StringBuilder
π’ Trend: improving β (slope: -2.34 ns/op per run)
Confidence: 87.3% (RΒ²)
Data points: 370.25 β 365.12 (-1.4%) β 362.45 (-0.7%) β 359.87 (-0.7%) ...
Benchmark: StringConcatenation
π΄ Trend: degrading β (slope: +12.45 ns/op per run)
Confidence: 92.1% (RΒ²)
Data points: 5123.45 β 5198.23 (+1.5%) β 5267.89 (+1.3%) β 5334.12 (+1.3%) ...
Benchmark: StringJoin
βͺ Trend: stable β (slope: -0.34 ns/op per run)
Confidence: 45.2% (RΒ²)
Data points: 879.12 β 881.34 (+0.3%) β 878.56 (-0.3%) β 880.23 (+0.2%) ...
Indicators:
- π’ improving: Performance getting better over time
- π΄ degrading: Performance getting worse over time
- βͺ stable: No significant trend
- Confidence: RΒ² value (higher = more reliable trend)
Threshold Checking (CI/CD)
Check if performance degraded beyond acceptable limits:
# Check with 10% threshold
gobench check --latest -threshold=10
# Check specific runs
gobench check run-123 run-456 -threshold=5
# Strict threshold for critical code
gobench check --latest -threshold=2
Output example:
Threshold Check (max degradation: 10.0%)
Comparing: run-123 vs run-456
β 2/10 benchmarks failed the threshold check:
β’ StringConcatenation: Performance degraded by 15.30% (threshold: 10.00%)
β’ MapIteration: Performance degraded by 12.45% (threshold: 10.00%)
Exit codes:
0: All benchmarks passed threshold1: One or more benchmarks failed threshold (useful for CI/CD)
Deleting Results
Delete a specific benchmark run:
gobench delete run-1699123456
Example Benchmarks
The repository includes example benchmarks in the examples/ directory that demonstrate common Go performance patterns:
String Operations (examples/string_test.go):
- String concatenation methods comparison
- String formatting benchmarks
Slice and Map Operations (examples/slice_test.go):
- Slice append with and without pre-allocation
- Slice copying
- Map access and iteration
Run the example benchmarks:
gobench run -pkg=./examples
CI/CD Integration
gobench is designed for seamless CI/CD integration.
GitHub Actions (Recommended)
Use the official GitHub Action for the easiest setup:
name: Benchmarks
on:
pull_request:
branches: [main]
push:
branches: [main]
jobs:
benchmark:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Run benchmarks
uses: alenon/gobench@v1
with:
packages: './...'
threshold-percent: 10
export-format: 'html,markdown'
See ACTION.md for complete documentation and examples/workflows/ for ready-to-use workflow examples.
Manual GitHub Actions Setup
If you prefer to use the CLI directly:
name: Benchmark Check
on:
pull_request:
branches: [ main ]
jobs:
benchmark:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
with:
go-version: '1.21'
- name: Install gobench
run: go install github.com/alenon/gobench/cmd/gobench@latest
- name: Run benchmarks
run: gobench run -pkg=./...
- name: Check threshold
run: gobench check --latest -threshold=10
- name: Export HTML report
if: always()
run: gobench export --latest -format=html -output=report.html
- name: Upload report
if: always()
uses: actions/upload-artifact@v5
with:
name: benchmark-report
path: report.html
See .github/workflows/benchmark.yml for a complete example with baseline comparison.
Supported CI Platforms
- GitHub Actions
- GitLab CI
- Jenkins
- CircleCI
- Any CI platform with Go support
Storage
By default, benchmark results are stored in the .gobench directory in JSON format. Each run is saved with a unique ID based on the timestamp.
You can specify a custom storage directory using the -storage flag with any command:
gobench run -storage=./benchmark-results
gobench list -storage=./benchmark-results
gobench compare --latest -storage=./benchmark-results
Benchmark Result Structure
Each saved benchmark run includes:
- ID: Unique identifier (e.g.,
run-1699123456) - Timestamp: When the benchmark was run
- Go Version: Version of Go used to run the benchmark
- Duration: Total time taken to run all benchmarks
- Command: The exact command used to run the benchmarks
- Results: Array of individual benchmark results containing:
- Name
- Iterations
- Nanoseconds per operation (ns/op)
- Bytes per operation (B/op)
- Allocations per operation (allocs/op)
- MB/s (if applicable)
Use Cases
Performance Regression Testing
Run benchmarks before and after code changes to ensure performance doesn't degrade:
# Before changes
gobench run
# Make your code changes...
# After changes
gobench run
# Compare
gobench compare --latest
# Check if degradation is acceptable
gobench check --latest -threshold=5
Tracking Performance Over Time
Build a history of benchmark results to track performance trends:
# Run benchmarks regularly (e.g., daily or per commit)
gobench run
# Review statistics
gobench stats -last=30
# Analyze trends
gobench trend -last=30
# Review all results
gobench list
A/B Testing Optimizations
Compare different optimization approaches:
# Test approach A
gobench run
# Note the run ID (e.g., run-123)
# Change to approach B
# Modify code...
gobench run
# Note the run ID (e.g., run-456)
# Compare
gobench compare run-123 run-456
# Export detailed report
gobench export run-123 run-456 -format=html
Continuous Integration
Automatically fail builds if performance degrades:
# In CI pipeline
gobench run -pkg=./...
# Fail if degradation > 10%
gobench check --latest -threshold=10 || exit 1
# Export report for artifacts
gobench export --latest -format=html -output=ci-report.html
Advanced Features
Multiple Run Analysis
For more reliable results, run benchmarks multiple times and analyze:
# Run benchmarks 5 times
for i in {1..5}; do
gobench run -pkg=./...
sleep 10 # Cool down period
done
# Analyze stability
gobench stats -last=5
# Check trends
gobench trend -last=5
Export to Multiple Formats
Generate reports in different formats for different audiences:
# For management (HTML with visualizations)
gobench export --latest -format=html -output=report.html
# For analysis (CSV for Excel/Google Sheets)
gobench export --latest -format=csv -output=data.csv
# For documentation (Markdown for GitHub)
gobench export --latest -format=markdown -output=BENCHMARKS.md
Benchmark-Specific Analysis
Focus on specific benchmarks:
# Run specific benchmark
gobench run -bench=BenchmarkCriticalPath
# Analyze trend for specific benchmark
gobench trend -benchmark=BenchmarkCriticalPath -last=20
Tips
- Consistent Environment: Run benchmarks in consistent environments (same hardware, similar system load) for accurate comparisons
- Multiple Runs: Consider running benchmarks multiple times and comparing averages for more reliable results
- Baseline: Keep a baseline benchmark run to compare all future optimizations against
- CI Integration: Integrate gobench into your CI pipeline to catch performance regressions early
- Thresholds: Set appropriate thresholds based on your application's performance requirements
- Cool Down: When running multiple benchmarks in sequence, add cool-down periods to prevent thermal throttling
- Statistics: Use
gobench statsto understand benchmark stability before making optimization decisions
Troubleshooting
No benchmarks found:
- Ensure your test files are named
*_test.go - Ensure benchmark functions start with
Benchmark - Check that you're in the correct directory or using the right
-pkgflag
High variation in results:
- Use
gobench statsto check coefficient of variation - Increase benchmark time:
go test -bench=. -benchtime=10s - Ensure system is not under heavy load
- Close unnecessary applications
Permission denied:
- The tool needs write access to the storage directory (default:
.gobench) - Use a different storage directory with
-storageflag if needed
Comparison shows no results:
- The benchmark names must match exactly between runs
- Ensure both run IDs exist (use
gobench listto verify)
Threshold check always fails:
- Check if your threshold is too strict for your benchmark variability
- Use
gobench statsto understand typical variation - Consider running benchmarks multiple times and using median values
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
License
See LICENSE file for details.
Documentation
- GitHub Action Documentation - Complete guide for the GitHub Action
- Example Workflows - Ready-to-use workflow examples
- CI/CD Integration Guide - Detailed CI/CD setup instructions
- GitHub Actions Example - Complete workflow example
- Homebrew Setup Guide - How to set up and maintain the Homebrew tap
- Release Process - Complete guide for creating releases
Roadmap
Future enhancements being considered:
- β Export to HTML, CSV, Markdown
- β Statistical analysis
- β Trend analysis
- β CI/CD integration
- β CPU/Memory profiling integration
- β Flame graph visualization
- β Memory leak detection
- β Hot path identification
- β Profile-guided optimization suggestions
- π Benchmark comparison graphs
- π Profile comparison between runs
- π Slack/Discord notifications for regressions
- π Integration with benchstat
- π Enhanced web UI for result visualization
Have a feature request? Open an issue!