📊 Metrics Collector¶

Comprehensive Architecture Quality Metrics Collection & Analysis

Part of the AudioLab Hierarchy Framework (05_01_08).

🎯 Overview¶

The Metrics Collector provides comprehensive tools for measuring, tracking, and analyzing architecture quality over time. It collects dependency metrics, complexity metrics, quality metrics, and generates actionable reports.

Key Features: - 📊 Multi-dimensional metrics collection - 📈 Trend analysis and history tracking - 🎯 Threshold-based quality gates - 📄 Multiple export formats (JSON, CSV, HTML) - 🔍 Detailed reporting and visualization

🏗️ Architecture¶

MetricsCollector
├── DependencyMetrics    → Module counts, violations, health
├── ComplexityMetrics    → Depth, coupling, cohesion
├── QualityMetrics       → Patterns, anti-patterns, health
├── LevelMetrics         → Per-level aggregations
└── OverallHealthScore   → Weighted composite (0-100)

📚 Quick Start¶

Basic Collection¶

#include <audiolab/hierarchy/metrics.hpp>

using namespace audiolab::hierarchy;

// Create module metadata map
std::map<std::string, ModuleMetadata> modules = /* ... */;

// Collect metrics
MetricsCollector collector;
MetricsSnapshot snapshot = collector.collect(modules);

// Display report
std::cout << snapshot.to_report();

Trend Tracking¶

MetricsHistory history;

// Collect snapshots over time
for (int iteration = 0; iteration < 10; ++iteration) {
    auto snapshot = collector.collect(modules);
    history.add_snapshot(snapshot);
}

// Check if improving
if (history.is_improving(5)) {
    std::cout << "Architecture quality is improving!\n";
}

// Generate trend report
std::cout << history.generate_trend_report();

Threshold Checking¶

MetricsThresholds thresholds;
thresholds.min_overall_health = 70.0;
thresholds.max_critical_violations = 0;
thresholds.max_god_objects = 3;

auto snapshot = collector.collect(modules);

if (!thresholds.check(snapshot)) {
    auto violations = thresholds.get_violations(snapshot);
    for (const auto& v : violations) {
        std::cerr << "❌ " << v << "\n";
    }
    return 1;  // Fail build
}

📊 Metrics Categories¶

1. Dependency Metrics¶

Metric	Description	Target
`total_modules`	Total module count	-
`total_dependencies`	Sum of all dependencies	Low
`avg_dependencies_per_module`	Average fanout	< 5
`upward_dependencies`	L0→L1 violations	0
`horizontal_dependencies`	Same-level violations	0
`circular_dependencies`	Cycle count	0
`dependency_health_score`	0-100 composite	100

2. Complexity Metrics¶

Metric	Description	Target
`max_depth`	Longest dependency chain	< 10
`avg_depth`	Average chain length	< 5
`coupling_factor`	0-1 coupling ratio	< 0.5
`cohesion_factor`	0-1 cohesion ratio	> 0.7
`god_objects_count`	Modules with too many deps	0
`complexity_score`	0-100 composite	100

3. Quality Metrics¶

Metric	Description	Target
`anti_pattern_count`	Total anti-patterns	0
`critical_violations`	CRITICAL severity	0
`good_pattern_count`	Detected good patterns	High
`excellent_patterns`	EXCELLENT quality	High
`architecture_health`	0-100 pattern score	100
`pattern_coverage`	% modules in patterns	> 0.5
`quality_score`	0-100 composite	100

4. Overall Health Score¶

Weighted average of all metrics:

overall_health = dependency_health * 0.3 +
                 complexity_score * 0.3 +
                 quality_score * 0.4

📈 Reporting¶

Summary Report¶

std::string summary = MetricsReporter::generate_summary(snapshot);
// Output:
// Architecture Health: 92.5/100 🟢 EXCELLENT
// Modules: 25 | Dependencies: 48 | Violations: 0
// Anti-Patterns: 0 (0 critical) | Good Patterns: 7

Detailed Report¶

std::string report = MetricsReporter::generate_detailed_report(snapshot);
// Full metrics breakdown with per-level statistics

Comparison Report¶

std::string comparison = MetricsReporter::generate_comparison(current, previous);
// Shows deltas between two snapshots

HTML Dashboard¶

std::string html = MetricsReporter::generate_html_dashboard(snapshot, &history);
std::ofstream("dashboard.html") << html;
// Interactive HTML with charts and metrics cards

Badge Markdown¶

std::string badges = MetricsReporter::generate_badge_markdown(snapshot);
// ![Architecture Health](https://img.shields.io/badge/...)

💾 Export Formats¶

JSON Export¶

std::string json = snapshot.to_json();

{
  "timestamp": "2025-10-10T14:30:00",
  "overall_health_score": 92.5,
  "dependency": {
    "total_modules": 25,
    "total_dependencies": 48,
    "violations": 0
  },
  "quality": {
    "architecture_health": 95,
    "anti_pattern_count": 0
  }
}

CSV Export¶

std::string csv = history.export_to_csv();

timestamp,overall_health,dep_health,complexity,quality,total_modules,...
2025-10-10T14:30:00,92.5,100.0,85.0,90.0,25,48,0,0,7,0.12,0.85,4,0

🎯 Use Cases¶

1. CI/CD Quality Gate¶

#!/bin/bash
./metrics_collector --check-thresholds
if [ $? -ne 0 ]; then
    echo "❌ Metrics threshold violated - build failed"
    exit 1
fi

2. Pre-Commit Hook¶

#!/bin/bash
metrics_diff=$(./metrics_collector --compare HEAD~1 HEAD)
if echo "$metrics_diff" | grep -q "degrading"; then
    echo "⚠️  Architecture quality degrading"
fi

3. Nightly Trend Report¶

#!/bin/bash
./metrics_collector --collect >> metrics_history.csv
./metrics_collector --trend-report > report.txt
mail -s "Architecture Metrics" team@audiolab.com < report.txt

4. README Badge¶

# My Project

![Architecture Health](https://img.shields.io/badge/architecture-92%25%20excellent-brightgreen)

🔧 Configuration¶

Custom Thresholds¶

MetricsThresholds custom;
custom.min_overall_health = 80.0;       // Stricter
custom.max_critical_violations = 0;
custom.max_god_objects = 2;             // Stricter
custom.max_coupling_factor = 0.5;       // Stricter
custom.min_pattern_coverage = 0.6;      // Stricter

History Persistence¶

MetricsHistory history;

// Load from file
if (history.load_from_file("metrics_history.json")) {
    std::cout << "Loaded " << history.get_snapshots().size() << " snapshots\n";
}

// Add new snapshot
history.add_snapshot(current_snapshot);

// Save back to file
history.save_to_file("metrics_history.json");

📋 API Reference¶

Core Classes¶

`MetricsCollector`¶

class MetricsCollector {
    MetricsSnapshot collect(const std::map<std::string, ModuleMetadata>&);
    DependencyMetrics collect_dependency_metrics(...);
    ComplexityMetrics collect_complexity_metrics(...);
    QualityMetrics collect_quality_metrics(...);
};

`MetricsHistory`¶

class MetricsHistory {
    void add_snapshot(const MetricsSnapshot&);
    std::optional<MetricsSnapshot> get_latest() const;
    double calculate_trend(int last_n = 5) const;
    bool is_improving(int last_n = 5) const;
    std::string export_to_csv() const;
};

`MetricsReporter`¶

class MetricsReporter {
    static std::string generate_summary(const MetricsSnapshot&);
    static std::string generate_detailed_report(const MetricsSnapshot&);
    static std::string generate_comparison(current, previous);
    static std::string generate_html_dashboard(snapshot, history);
    static std::string generate_badge_markdown(snapshot);
};

`MetricsThresholds`¶

struct MetricsThresholds {
    double min_overall_health = 60.0;
    size_t max_critical_violations = 0;
    size_t max_god_objects = 5;
    double max_coupling_factor = 0.7;
    double min_pattern_coverage = 0.5;

    bool check(const MetricsSnapshot&) const;
    std::vector<std::string> get_violations(const MetricsSnapshot&) const;
};

🧪 Testing¶

# Run tests
cd build
ctest --output-on-failure -R test_metrics

# Run with coverage
cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON ..
make test_metrics
./tests/test_metrics

Coverage Target: > 85%

🎮 Examples¶

Run the interactive demo:

./build/examples/metrics_demo

Demo Scenarios: 1. Basic metrics collection on clean architecture 2. Architecture comparison (clean vs violations) 3. Trend tracking over 7 iterations 4. Threshold checking with violations 5. Export formats (JSON, CSV, HTML, badges) 6. Summary reports for multiple architectures

🔗 Dependencies¶

level_definitions - Module level enums
validation_engine - Dependency graph analysis
pattern_library - Good pattern detection
anti_patterns - Anti-pattern detection

📖 See Also¶

Pattern Library - Good pattern detection
Anti-Patterns - Anti-pattern detection
Validation Engine - Dependency validation

📜 License¶

Part of the AudioLab project.

Last Updated: 2025-10-10 Maintainer: AudioLab Core Team Status: ✅ Production Ready