monitoring_interface.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include <algorithm>
#include <array>
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <string_view>
#include <unordered_map>
#include <utility>
#include <vector>
#include "../patterns/result.h"
#include "../utils/enum_serialization.h"
 
namespace kcenon::common {
namespace interfaces {
 
enum class metric_type {
    gauge,      // Instant value that can go up or down
    counter,    // Monotonic increasing value
    histogram,  // Distribution of values across buckets
    summary     // Statistical summary (min, max, mean, percentiles)
};
 
}  // namespace interfaces
 
template<>
struct enum_traits<interfaces::metric_type> {
    static constexpr auto values = std::array{
        std::pair{interfaces::metric_type::gauge, std::string_view{"GAUGE"}},
        std::pair{interfaces::metric_type::counter, std::string_view{"COUNTER"}},
        std::pair{interfaces::metric_type::histogram, std::string_view{"HISTOGRAM"}},
        std::pair{interfaces::metric_type::summary, std::string_view{"SUMMARY"}},
    };
    static constexpr std::string_view module_name = "monitoring_interface";
};
 
namespace interfaces {
 
inline std::string to_string(metric_type type) {
    return enum_to_string(type);
}
 
inline Result<metric_type> metric_type_from_string(const std::string& str) {
    return enum_from_string<metric_type>(str);
}
 
struct metric_value {
    std::string name;
    double value;
    metric_type type = metric_type::gauge;
    std::chrono::system_clock::time_point timestamp;
    std::unordered_map<std::string, std::string> tags;
 
    metric_value(const std::string& n = "", double v = 0.0, metric_type t = metric_type::gauge)
        : name(n)
        , value(v)
        , type(t)
        , timestamp(std::chrono::system_clock::now()) {}
};
 
struct metrics_snapshot {
    std::vector<metric_value> metrics;
    std::chrono::system_clock::time_point capture_time;
    std::string source_id;
 
    metrics_snapshot()
        : capture_time(std::chrono::system_clock::now()) {}
 
    void add_metric(const std::string& name, double value) {
        metrics.emplace_back(name, value);
    }
};
 
struct thread_pool_metrics {
    metric_value jobs_completed{"jobs_completed", 0, metric_type::counter};
    metric_value jobs_pending{"jobs_pending", 0, metric_type::gauge};
    metric_value worker_threads{"worker_threads", 0, metric_type::gauge};
    metric_value idle_threads{"idle_threads", 0, metric_type::gauge};
    metric_value average_latency_ns{"average_latency_ns", 0, metric_type::gauge};
    metric_value total_execution_time_ns{"total_execution_time_ns", 0, metric_type::counter};
 
    std::chrono::system_clock::time_point timestamp = std::chrono::system_clock::now();
 
    // Pool identification for multi-pool scenarios
    std::string pool_name;
    std::uint32_t pool_instance_id{0};
 
    thread_pool_metrics() = default;
 
    explicit thread_pool_metrics(const std::string& name, std::uint32_t instance_id = 0)
        : pool_name(name), pool_instance_id(instance_id) {}
 
    std::vector<metric_value> to_metrics() const {
        return {
            jobs_completed,
            jobs_pending,
            worker_threads,
            idle_threads,
            average_latency_ns,
            total_execution_time_ns
        };
    }
};
 
struct worker_metrics {
    metric_value jobs_processed{"jobs_processed", 0, metric_type::counter};
    metric_value total_processing_time_ns{"total_processing_time_ns", 0, metric_type::counter};
    metric_value idle_time_ns{"idle_time_ns", 0, metric_type::counter};
    metric_value context_switches{"context_switches", 0, metric_type::counter};
 
    std::chrono::system_clock::time_point timestamp = std::chrono::system_clock::now();
    std::size_t worker_id{0};
 
    worker_metrics() = default;
 
    explicit worker_metrics(std::size_t id) : worker_id(id) {}
 
    std::vector<metric_value> to_metrics() const {
        return {
            jobs_processed,
            total_processing_time_ns,
            idle_time_ns,
            context_switches
        };
    }
};
 
struct system_metrics {
    metric_value cpu_usage_percent{"cpu_usage_percent", 0, metric_type::gauge};
    metric_value memory_usage_bytes{"memory_usage_bytes", 0, metric_type::gauge};
    metric_value active_threads{"active_threads", 0, metric_type::gauge};
    metric_value total_allocations{"total_allocations", 0, metric_type::counter};
 
    std::chrono::system_clock::time_point timestamp = std::chrono::system_clock::now();
 
    std::vector<metric_value> to_metrics() const {
        return {
            cpu_usage_percent,
            memory_usage_bytes,
            active_threads,
            total_allocations
        };
    }
};
 
enum class health_status {
    healthy = 0,
    degraded = 1,
    unhealthy = 2,
    unknown = 3
};
 
}  // namespace interfaces
 
template<>
struct enum_traits<interfaces::health_status> {
    static constexpr auto values = std::array{
        std::pair{interfaces::health_status::healthy, std::string_view{"HEALTHY"}},
        std::pair{interfaces::health_status::degraded, std::string_view{"DEGRADED"}},
        std::pair{interfaces::health_status::unhealthy, std::string_view{"UNHEALTHY"}},
        std::pair{interfaces::health_status::unknown, std::string_view{"UNKNOWN"}},
    };
    static constexpr std::string_view module_name = "monitoring_interface";
};
 
namespace interfaces {
 
struct health_check_result {
    health_status status = health_status::unknown;
    std::string message;
    std::chrono::system_clock::time_point timestamp;
    std::chrono::milliseconds check_duration{0};
    std::unordered_map<std::string, std::string> metadata;
 
    health_check_result()
        : timestamp(std::chrono::system_clock::now()) {}
 
    bool is_healthy() const {
        return status == health_status::healthy;
    }
 
    bool is_operational() const {
        return status == health_status::healthy ||
               status == health_status::degraded;
    }
};
 
class IMonitor {
public:
    virtual ~IMonitor() = default;
 
    virtual VoidResult record_metric(const std::string& name, double value) = 0;
 
    virtual VoidResult record_metric(
        const std::string& name,
        double value,
        const std::unordered_map<std::string, std::string>& tags) = 0;
 
    virtual Result<metrics_snapshot> get_metrics() = 0;
 
    virtual Result<health_check_result> check_health() = 0;
 
    virtual VoidResult reset() = 0;
};
 
class IMonitorable {
public:
    virtual ~IMonitorable() = default;
 
    virtual Result<metrics_snapshot> get_monitoring_data() = 0;
 
    virtual Result<health_check_result> health_check() = 0;
 
    virtual std::string get_component_name() const = 0;
};
 
using MonitorFactory = std::function<std::shared_ptr<IMonitor>()>;
 
class IMonitorProvider {
public:
    virtual ~IMonitorProvider() = default;
 
    virtual std::shared_ptr<IMonitor> get_monitor() = 0;
 
    virtual std::shared_ptr<IMonitor> create_monitor(const std::string& name) = 0;
};
 
inline std::string to_string(health_status status) {
    return enum_to_string(status);
}
 
}  // namespace interfaces
}  // namespace kcenon::common