health_status.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include <chrono>
#include <cstdint>
#include <iomanip>
#include <map>
#include <sstream>
#include <string>
#include <vector>
 
namespace kcenon::thread::diagnostics
{
    struct health_thresholds
    {
        double min_success_rate{0.95};
 
        double unhealthy_success_rate{0.8};
 
        double max_healthy_latency_ms{100.0};
 
        double degraded_latency_ms{500.0};
 
        double queue_saturation_warning{0.8};
 
        double queue_saturation_critical{0.95};
 
        double worker_utilization_warning{0.9};
 
        std::size_t min_idle_workers{0};
    };
 
    enum class health_state
    {
        healthy,    
        degraded,   
        unhealthy,  
        unknown     
    };
 
    [[nodiscard]] inline auto health_state_to_string(health_state state) -> std::string
    {
        switch (state)
        {
            case health_state::healthy: return "healthy";
            case health_state::degraded: return "degraded";
            case health_state::unhealthy: return "unhealthy";
            case health_state::unknown: return "unknown";
            default: return "unknown";
        }
    }
 
    [[nodiscard]] inline auto health_state_to_http_code(health_state state) -> int
    {
        switch (state)
        {
            case health_state::healthy: return 200;
            case health_state::degraded: return 200;  // Still operational
            case health_state::unhealthy: return 503;
            case health_state::unknown: return 503;
            default: return 503;
        }
    }
 
    struct component_health
    {
        std::string name;
 
        health_state state{health_state::unknown};
 
        std::string message;
 
        std::map<std::string, std::string> details;
 
        [[nodiscard]] auto is_operational() const -> bool
        {
            return state == health_state::healthy ||
                   state == health_state::degraded;
        }
    };
 
    struct health_status
    {
        health_state overall_status{health_state::unknown};
 
        std::string status_message;
 
        std::chrono::steady_clock::time_point check_time;
 
        std::vector<component_health> components;
 
        // =========================================================================
        // Summary Metrics
        // =========================================================================
 
        double uptime_seconds{0.0};
 
        std::uint64_t total_jobs_processed{0};
 
        double success_rate{1.0};
 
        double avg_latency_ms{0.0};
 
        std::size_t active_workers{0};
 
        std::size_t total_workers{0};
 
        std::size_t queue_depth{0};
 
        std::size_t queue_capacity{0};
 
        // =========================================================================
        // Computed Properties
        // =========================================================================
 
        [[nodiscard]] auto is_operational() const -> bool
        {
            return overall_status == health_state::healthy ||
                   overall_status == health_state::degraded;
        }
 
        [[nodiscard]] auto is_healthy() const -> bool
        {
            return overall_status == health_state::healthy;
        }
 
        [[nodiscard]] auto http_status_code() const -> int
        {
            return health_state_to_http_code(overall_status);
        }
 
        [[nodiscard]] auto find_component(const std::string& name) const
            -> const component_health*
        {
            for (const auto& comp : components)
            {
                if (comp.name == name)
                {
                    return &comp;
                }
            }
            return nullptr;
        }
 
        auto calculate_overall_status() -> void
        {
            if (components.empty())
            {
                overall_status = health_state::unknown;
                status_message = "No components registered";
                return;
            }
 
            bool has_unhealthy = false;
            bool has_degraded = false;
            bool has_unknown = false;
 
            for (const auto& comp : components)
            {
                switch (comp.state)
                {
                    case health_state::unhealthy:
                        has_unhealthy = true;
                        break;
                    case health_state::degraded:
                        has_degraded = true;
                        break;
                    case health_state::unknown:
                        has_unknown = true;
                        break;
                    default:
                        break;
                }
            }
 
            if (has_unhealthy)
            {
                overall_status = health_state::unhealthy;
                status_message = "One or more components are unhealthy";
            }
            else if (has_degraded)
            {
                overall_status = health_state::degraded;
                status_message = "One or more components are degraded";
            }
            else if (has_unknown)
            {
                overall_status = health_state::degraded;
                status_message = "One or more components have unknown status";
            }
            else
            {
                overall_status = health_state::healthy;
                status_message = "All components are healthy";
            }
        }
 
        // =========================================================================
        // Serialization
        // =========================================================================
 
        [[nodiscard]] auto to_json() const -> std::string
        {
            std::ostringstream oss;
            oss << std::fixed;
 
            oss << "{\n";
            oss << "  \"status\": \"" << health_state_to_string(overall_status) << "\",\n";
            oss << "  \"message\": \"" << status_message << "\",\n";
            oss << "  \"http_code\": " << http_status_code() << ",\n";
 
            // Metrics
            oss << "  \"metrics\": {\n";
            oss << "    \"uptime_seconds\": " << std::setprecision(2) << uptime_seconds << ",\n";
            oss << "    \"total_jobs_processed\": " << total_jobs_processed << ",\n";
            oss << "    \"success_rate\": " << std::setprecision(4) << success_rate << ",\n";
            oss << "    \"avg_latency_ms\": " << std::setprecision(3) << avg_latency_ms << "\n";
            oss << "  },\n";
 
            // Workers
            oss << "  \"workers\": {\n";
            oss << "    \"total\": " << total_workers << ",\n";
            oss << "    \"active\": " << active_workers << ",\n";
            oss << "    \"idle\": " << (total_workers - active_workers) << "\n";
            oss << "  },\n";
 
            // Queue
            oss << "  \"queue\": {\n";
            oss << "    \"depth\": " << queue_depth << ",\n";
            oss << "    \"capacity\": " << queue_capacity << "\n";
            oss << "  },\n";
 
            // Components
            oss << "  \"components\": [\n";
            for (std::size_t i = 0; i < components.size(); ++i)
            {
                const auto& comp = components[i];
                oss << "    {\n";
                oss << "      \"name\": \"" << comp.name << "\",\n";
                oss << "      \"status\": \"" << health_state_to_string(comp.state) << "\",\n";
                oss << "      \"message\": \"" << comp.message << "\"";
 
                if (!comp.details.empty())
                {
                    oss << ",\n      \"details\": {\n";
                    std::size_t detail_idx = 0;
                    for (const auto& [key, value] : comp.details)
                    {
                        oss << "        \"" << key << "\": \"" << value << "\"";
                        if (++detail_idx < comp.details.size())
                        {
                            oss << ",";
                        }
                        oss << "\n";
                    }
                    oss << "      }\n";
                }
                else
                {
                    oss << "\n";
                }
 
                oss << "    }";
                if (i < components.size() - 1)
                {
                    oss << ",";
                }
                oss << "\n";
            }
            oss << "  ]\n";
            oss << "}";
 
            return oss.str();
        }
 
        [[nodiscard]] auto to_string() const -> std::string
        {
            std::ostringstream oss;
            oss << std::fixed;
 
            oss << "=== Health Status: " << health_state_to_string(overall_status)
                << " (HTTP " << http_status_code() << ") ===\n";
            oss << "Message: " << status_message << "\n\n";
 
            oss << "Metrics:\n";
            oss << "  Uptime: " << std::setprecision(1) << uptime_seconds << " seconds\n";
            oss << "  Jobs processed: " << total_jobs_processed << "\n";
            oss << "  Success rate: " << std::setprecision(1) << (success_rate * 100.0) << "%\n";
            oss << "  Avg latency: " << std::setprecision(2) << avg_latency_ms << " ms\n\n";
 
            oss << "Workers: " << active_workers << "/" << total_workers << " active";
            if (total_workers > 0)
            {
                oss << " (" << (total_workers - active_workers) << " idle)";
            }
            oss << "\n";
 
            oss << "Queue: " << queue_depth;
            if (queue_capacity > 0)
            {
                double saturation = static_cast<double>(queue_depth) /
                                    static_cast<double>(queue_capacity) * 100.0;
                oss << "/" << queue_capacity << " (" << std::setprecision(1)
                    << saturation << "% full)";
            }
            oss << "\n\n";
 
            oss << "Components:\n";
            for (const auto& comp : components)
            {
                oss << "  [" << health_state_to_string(comp.state) << "] "
                    << comp.name << ": " << comp.message << "\n";
            }
 
            return oss.str();
        }
 
        [[nodiscard]] auto to_prometheus(const std::string& pool_name = "default") const
            -> std::string
        {
            std::ostringstream oss;
            oss << std::fixed;
 
            // Health status (1 = healthy, 0.5 = degraded, 0 = unhealthy/unknown)
            double health_value = 0.0;
            switch (overall_status)
            {
                case health_state::healthy: health_value = 1.0; break;
                case health_state::degraded: health_value = 0.5; break;
                default: health_value = 0.0; break;
            }
            oss << "# HELP thread_pool_health_status Health status (1=healthy, 0.5=degraded, 0=unhealthy)\n";
            oss << "# TYPE thread_pool_health_status gauge\n";
            oss << "thread_pool_health_status{pool=\"" << pool_name << "\"} "
                << std::setprecision(1) << health_value << "\n\n";
 
            // Uptime
            oss << "# HELP thread_pool_uptime_seconds Total uptime in seconds\n";
            oss << "# TYPE thread_pool_uptime_seconds counter\n";
            oss << "thread_pool_uptime_seconds{pool=\"" << pool_name << "\"} "
                << std::setprecision(2) << uptime_seconds << "\n\n";
 
            // Jobs processed
            oss << "# HELP thread_pool_jobs_total Total number of jobs processed\n";
            oss << "# TYPE thread_pool_jobs_total counter\n";
            oss << "thread_pool_jobs_total{pool=\"" << pool_name << "\"} "
                << total_jobs_processed << "\n\n";
 
            // Success rate
            oss << "# HELP thread_pool_success_rate Ratio of successful jobs (0.0 to 1.0)\n";
            oss << "# TYPE thread_pool_success_rate gauge\n";
            oss << "thread_pool_success_rate{pool=\"" << pool_name << "\"} "
                << std::setprecision(4) << success_rate << "\n\n";
 
            // Average latency
            oss << "# HELP thread_pool_latency_avg_ms Average job latency in milliseconds\n";
            oss << "# TYPE thread_pool_latency_avg_ms gauge\n";
            oss << "thread_pool_latency_avg_ms{pool=\"" << pool_name << "\"} "
                << std::setprecision(3) << avg_latency_ms << "\n\n";
 
            // Workers
            oss << "# HELP thread_pool_workers_total Total number of workers\n";
            oss << "# TYPE thread_pool_workers_total gauge\n";
            oss << "thread_pool_workers_total{pool=\"" << pool_name << "\"} "
                << total_workers << "\n\n";
 
            oss << "# HELP thread_pool_workers_active Number of active workers\n";
            oss << "# TYPE thread_pool_workers_active gauge\n";
            oss << "thread_pool_workers_active{pool=\"" << pool_name << "\"} "
                << active_workers << "\n\n";
 
            oss << "# HELP thread_pool_workers_idle Number of idle workers\n";
            oss << "# TYPE thread_pool_workers_idle gauge\n";
            oss << "thread_pool_workers_idle{pool=\"" << pool_name << "\"} "
                << (total_workers - active_workers) << "\n\n";
 
            // Queue
            oss << "# HELP thread_pool_queue_depth Current queue depth\n";
            oss << "# TYPE thread_pool_queue_depth gauge\n";
            oss << "thread_pool_queue_depth{pool=\"" << pool_name << "\"} "
                << queue_depth << "\n\n";
 
            if (queue_capacity > 0)
            {
                oss << "# HELP thread_pool_queue_capacity Maximum queue capacity\n";
                oss << "# TYPE thread_pool_queue_capacity gauge\n";
                oss << "thread_pool_queue_capacity{pool=\"" << pool_name << "\"} "
                    << queue_capacity << "\n\n";
 
                double saturation = static_cast<double>(queue_depth) /
                                    static_cast<double>(queue_capacity);
                oss << "# HELP thread_pool_queue_saturation Queue saturation ratio (0.0 to 1.0)\n";
                oss << "# TYPE thread_pool_queue_saturation gauge\n";
                oss << "thread_pool_queue_saturation{pool=\"" << pool_name << "\"} "
                    << std::setprecision(4) << saturation << "\n\n";
            }
 
            // Component health
            for (const auto& comp : components)
            {
                double comp_health = 0.0;
                switch (comp.state)
                {
                    case health_state::healthy: comp_health = 1.0; break;
                    case health_state::degraded: comp_health = 0.5; break;
                    default: comp_health = 0.0; break;
                }
                oss << "# HELP thread_pool_component_health Component health status\n";
                oss << "# TYPE thread_pool_component_health gauge\n";
                oss << "thread_pool_component_health{pool=\"" << pool_name
                    << "\",component=\"" << comp.name << "\"} "
                    << std::setprecision(1) << comp_health << "\n";
            }
 
            return oss.str();
        }
    };
 
} // namespace kcenon::thread::diagnostics