🔧 Quality Metrics - Integration Guide

Guide for integrating Quality Metrics into your AudioLab modules.

---

Quick Start

Step 1: Include Headers

#include <audiolab/metrics/metrics_core.hpp>
#include <audiolab/metrics/metric_collector.hpp>

Step 2: Register Your Metrics

using namespace audiolab::metrics;

// In your module initialization
void MyModule::init() {
    // CPU usage gauge
    cpu_metric_ = REGISTER_GAUGE(
        "mymodule.cpu_percent",
        "CPU usage for MyModule",
        "%",
        MetricDirection::LOWER_BETTER
    );

    // Processing latency histogram
    latency_metric_ = REGISTER_HISTOGRAM(
        "mymodule.latency_ms",
        "Processing latency",
        "ms",
        MetricDirection::LOWER_BETTER
    );

    // Samples processed counter
    samples_counter_ = REGISTER_COUNTER(
        "mymodule.samples_processed",
        "Total samples processed",
        "samples"
    );
}

Step 3: Record Values

void MyModule::process(float* buffer, size_t length) {
    auto start = std::chrono::high_resolution_clock::now();

    // Your processing
    processAudio(buffer, length);

    auto end = std::chrono::high_resolution_clock::now();
    auto duration_ms = std::chrono::duration<double, std::milli>(end - start).count();

    // Record metrics
    latency_metric_->record(duration_ms);
    samples_counter_->record(length);
}

---

Audio Quality Integration

Measure THD

#include <audiolab/metrics/audio/thd_analyzer.hpp>

using namespace audiolab::metrics::audio;

void MyModule::measureQuality(const float* output, size_t length) {
    THDAnalyzer analyzer;
    auto result = analyzer.analyze(output, length, 1000.0f);  // 1kHz

    if (result.valid) {
        thd_metric_->record(result.thd_percent);

        if (!meetsProfessionalTHDStandard(result.thd_percent)) {
            LOG_WARNING("THD exceeds professional standard!");
        }
    }
}

---

Automatic Collection

Setup Periodic Collection

void MyModule::setupMetrics() {
    // Create collector config
    CollectorConfig config(
        "mymodule_cpu_collector",
        CollectionStrategy::PERIODIC,
        std::chrono::milliseconds(100)  // Collect every 100ms
    );

    // Create collector
    auto collector = CollectorManager::getInstance().createCollector(
        config, cpu_metric_
    );

    // Add source
    auto cpu_source = std::make_shared<FunctionSource>(
        "cpu_sensor",
        [this]() { return this->getCurrentCPUUsage(); }
    );

    collector->addSource(cpu_source);
    // Collector starts automatically if config.auto_start = true
}

---

CI/CD Integration

GitHub Actions Example

name: Quality Gates

on: [pull_request]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Build
        run: |
          mkdir build && cd build
          cmake .. -DCMAKE_BUILD_TYPE=Release
          cmake --build .

      - name: Run Benchmarks
        run: ./build/benchmarks/performance_suite

      - name: Check Regression
        run: |
          python quality_gates/scripts/gate_executor.py \
            --gate=pull_request \
            --baseline=main \
            --current=HEAD

---

Best Practices

1. Naming Convention: module_name.metric_name_unit
2. Sample Judiciously: Don't measure every buffer (1/100 is often enough)
3. Use Appropriate Type: Gauge for levels, Counter for totals, Histogram for distributions
4. Set Realistic Targets: Based on your module's requirements
5. Monitor in Development: Catch regressions early

---

For more details, see README.md and ARCHITECTURE.md