Build Analytics

Overview

CCGO provides build analytics to track and analyze build performance over time. This helps identify bottlenecks, track improvements, and optimize build configurations.

Benefits

• 📊 Performance Tracking - Monitor build times and identify trends
• 🎯 Bottleneck Identification - Find which phases take longest
• 📈 Cache Effectiveness - Track compiler cache hit/miss rates
• 🔍 Build History - Review past builds and compare performance
• 📉 Optimization Insights - Data-driven build optimization decisions

Quick Start

Build analytics are automatically collected during builds and stored locally in ~/.ccgo/analytics/.

View Analytics

# Show recent builds (default: 10)
ccgo analytics show

# Show more builds
ccgo analytics show -n 20

# Show summary statistics
ccgo analytics summary

# List all projects with analytics
ccgo analytics list

Commands

ccgo analytics show

Display recent build history with key metrics:

$ ccgo analytics show

================================================================================
Build Analytics for myproject
================================================================================

Build #1 - linux (2026-01-21T15:30:00+08:00)
  Duration:    45.30s
  Jobs:        8
  Success:     ✓
  Cache Tool:  sccache
  Cache Rate:  78.5%

Build #2 - linux (2026-01-21T16:00:00+08:00)
  Duration:    12.50s
  Jobs:        8
  Success:     ✓
  Cache Tool:  sccache
  Cache Rate:  95.2%

Build #3 - macos (2026-01-21T16:15:00+08:00)
  Duration:    38.70s
  Jobs:        8
  Success:     ✓
  Cache Tool:  ccache
  Cache Rate:  82.3%

Options: - -n, --count <NUM> - Number of builds to show (default: 10)

ccgo analytics summary

Show aggregate statistics across all builds:

$ ccgo analytics summary

================================================================================
Build Analytics Summary for myproject
================================================================================

Total Builds:      25
Successful:        24 (96.0%)

Build Duration:
  Average:         32.45s
  Fastest:         11.20s
  Slowest:         58.90s

Cache Statistics:
  Builds with cache: 23
  Avg Hit Rate:      85.3%

Platform Breakdown:
  linux............... 15
  macos............... 8
  ios................. 2

================================================================================

ccgo analytics clear

Clear analytics history for the current project:

$ ccgo analytics clear

This will delete 25 build analytics entries for 'myproject'
Continue? [y/N] y
✓ Cleared analytics for 'myproject'

Options: - -y, --yes - Skip confirmation prompt

ccgo analytics export

Export analytics data to JSON file:

$ ccgo analytics export -o builds.json

✓ Exported 25 build analytics to builds.json

Options: - -o, --output <FILE> - Output file path

ccgo analytics list

List all projects with analytics data:

$ ccgo analytics list

================================================================================
Projects with Analytics
================================================================================

  myproject.................................... 25 builds
  another-lib.................................. 12 builds
  experimental................................. 5 builds

Use 'ccgo analytics show' from a project directory to view details.
================================================================================

Collected Metrics

Build Overview

• Project Name - Project being built
• Platform - Target platform (linux, macos, windows, etc.)
• Timestamp - When build started (ISO 8601)
• Total Duration - Complete build time in seconds
• Parallel Jobs - Number of parallel compilation jobs
• Success Status - Whether build succeeded
• Errors/Warnings - Count of compilation diagnostics

Phase Breakdown

Build is divided into phases with timing for each:

1. Dependency Resolution - Installing and resolving dependencies
2. CMake Configuration - CMake configure step
3. Compilation - C/C++ source compilation
4. Linking - Linking libraries
5. Archiving - Creating ZIP archives
6. Post-Processing - Additional packaging steps

Each phase tracks: - Duration in seconds - Percentage of total build time

Cache Statistics

For builds using ccache/sccache:

• Cache Tool - Which tool is being used (ccache, sccache)
• Cache Hits - Compilation artifacts reused from cache
• Cache Misses - New compilation results added to cache
• Hit Rate - Percentage of cache hits (0-100%)

File Statistics

• Source Files - Number of .c/.cc/.cpp files
• Header Files - Number of .h/.hpp files
• Total Lines - Combined lines of code
• Artifact Size - Final output size in bytes

Data Storage

Analytics data is stored locally in:

~/.ccgo/analytics/
├── myproject.json      # Analytics for myproject
├── another-lib.json    # Analytics for another-lib
└── ...

Each project file contains: - Last 100 builds (older builds are automatically pruned) - JSON format for easy parsing and export - No personally identifiable information

Analytics API (Rust)

For programmatic access within CCGO:

use ccgo::build::analytics::{BuildAnalytics, AnalyticsCollector, BuildPhase};

// Create collector
let mut collector = AnalyticsCollector::new(
    "myproject".to_string(),
    "linux".to_string(),
    8, // parallel jobs
);

// Time phases
collector.start_phase(BuildPhase::Compilation);
// ... compilation work ...
collector.end_phase(BuildPhase::Compilation);

// Record diagnostics
collector.add_diagnostics(2, 15); // 2 errors, 15 warnings

// Set success status
collector.set_success(true);

// Finalize and save
let analytics = collector.finalize(cache_stats, file_stats);
analytics.save()?;

// Load history
let history = BuildAnalytics::load_history("myproject")?;

// Get average build time
let avg = BuildAnalytics::average_build_time("myproject")?;

Use Cases

Performance Regression Detection

# After making changes
ccgo build linux

# Check if build got slower
ccgo analytics summary

# Expected: Average duration should not increase significantly

Cache Effectiveness

# First build (cold cache)
ccgo build linux --cache sccache
# Note the duration

# Second build (warm cache)
ccgo build linux --cache sccache
# Should be 50-80% faster

# Check cache hit rate
ccgo analytics show -n 1
# Expected: High cache hit rate (>80%)

CI/CD Monitoring

# .github/workflows/build.yml
- name: Build
  run: ccgo build linux

- name: Show Analytics
  run: ccgo analytics show -n 1

- name: Export Analytics
  run: ccgo analytics export -o build-stats.json

- name: Upload Analytics
  uses: actions/upload-artifact@v3
  with:
    name: build-analytics
    path: build-stats.json

Comparing Platforms

# Build multiple platforms
ccgo build linux
ccgo build macos
ccgo build windows

# View summary
ccgo analytics summary

# Platform Breakdown shows relative performance

Best Practices

DO

✅ Review regularly - Check analytics after significant changes ✅ Track trends - Monitor if builds are getting slower over time ✅ Optimize hot paths - Focus on phases with highest percentage ✅ Use caching - Compiler cache dramatically improves metrics ✅ Export for reports - Use JSON export for trend analysis

DON'T

❌ Don't commit analytics - Data is local to your machine ❌ Don't manually edit - Analytics files are auto-generated ❌ Don't rely on first build - Cold cache builds are always slower ❌ Don't compare different machines - Hardware affects timing

Troubleshooting

No Analytics Data

Symptom: ccgo analytics show says "No build analytics available"

Solution: Analytics collection is automatic but requires:

# Run a build first
ccgo build linux

# Then check analytics
ccgo analytics show

Analytics Not Updating

Symptom: New builds don't appear in analytics

Solution: Check that builds are completing successfully:

# Verify build succeeds
ccgo build linux

# Check recent analytics
ccgo analytics show -n 1

Wrong Project Analytics

Symptom: Seeing analytics from different project

Solution: Analytics are tied to project name in CCGO.toml:

# Check current project
grep "name =" CCGO.toml

# Make sure you're in correct directory
pwd

Storage Location

Analytics are stored in: - Linux: ~/.ccgo/analytics/ - macOS: ~/.ccgo/analytics/ - Windows: %USERPROFILE%\.ccgo\analytics\

Future Enhancements

Planned features for future releases:

• Real-time build progress visualization
• Memory usage tracking
• Dependency compilation breakdown
• Historical trend graphs
• Export to CSV/Excel
• Integration with build dashboards
• Comparative analysis across teams
• Automatic regression alerts

See Also

• Build Caching - Improve build times with caching
• Build System - General build system overview
• Incremental Builds - Faster rebuild strategies

Changelog

v3.0.11 (2026-01-21)

• ✅ Implemented build analytics system
• ✅ Added ccgo analytics command with show/summary/clear/export/list subcommands
• ✅ Automatic collection of build metrics
• ✅ Phase timing breakdown
• ✅ Cache statistics integration
• ✅ File and error/warning tracking
• ✅ Local storage in ~/.ccgo/analytics/
• ✅ Last 100 builds per project (auto-pruning)

---

Build analytics help you make data-driven decisions about build optimization and configuration.