bottleneck_report.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 <cstddef>
#include <iomanip>
#include <sstream>
#include <string>
#include <vector>
 
namespace kcenon::thread::diagnostics
{
    enum class bottleneck_type
    {
        none,                  
        queue_full,            
        slow_consumer,         
        worker_starvation,     
        lock_contention,       
        uneven_distribution,   
        memory_pressure        
    };
 
    [[nodiscard]] inline auto bottleneck_type_to_string(bottleneck_type type) -> std::string
    {
        switch (type)
        {
            case bottleneck_type::none: return "none";
            case bottleneck_type::queue_full: return "queue_full";
            case bottleneck_type::slow_consumer: return "slow_consumer";
            case bottleneck_type::worker_starvation: return "worker_starvation";
            case bottleneck_type::lock_contention: return "lock_contention";
            case bottleneck_type::uneven_distribution: return "uneven_distribution";
            case bottleneck_type::memory_pressure: return "memory_pressure";
            default: return "unknown";
        }
    }
 
    struct bottleneck_report
    {
        bool has_bottleneck{false};
 
        std::string description;
 
        bottleneck_type type{bottleneck_type::none};
 
        // =========================================================================
        // Supporting Metrics
        // =========================================================================
 
        double queue_saturation{0.0};
 
        double avg_wait_time_ms{0.0};
 
        double worker_utilization{0.0};
 
        std::size_t estimated_backlog_time_ms{0};
 
        double utilization_variance{0.0};
 
        std::uint64_t jobs_rejected{0};
 
        std::size_t queue_depth{0};
 
        std::size_t idle_workers{0};
 
        std::size_t total_workers{0};
 
        // =========================================================================
        // Recommendations
        // =========================================================================
 
        std::vector<std::string> recommendations;
 
        // =========================================================================
        // Computed Properties
        // =========================================================================
 
        [[nodiscard]] auto severity() const -> int
        {
            if (!has_bottleneck)
            {
                return 0;
            }
 
            // Critical: queue full or severe worker starvation
            if (queue_saturation > 0.95 || worker_utilization > 0.98)
            {
                return 3;
            }
 
            // High: approaching capacity
            if (queue_saturation > 0.8 || worker_utilization > 0.9)
            {
                return 2;
            }
 
            // Medium: noticeable but not urgent
            return 1;
        }
 
        [[nodiscard]] auto severity_string() const -> std::string
        {
            switch (severity())
            {
                case 0: return "none";
                case 1: return "low";
                case 2: return "medium";
                case 3: return "critical";
                default: return "unknown";
            }
        }
 
        [[nodiscard]] auto requires_immediate_action() const -> bool
        {
            return severity() >= 3;
        }
 
        [[nodiscard]] auto to_json() const -> std::string
        {
            std::ostringstream oss;
            oss << "{\n";
            oss << "  \"has_bottleneck\": " << (has_bottleneck ? "true" : "false") << ",\n";
            oss << "  \"type\": \"" << bottleneck_type_to_string(type) << "\",\n";
            oss << "  \"severity\": \"" << severity_string() << "\",\n";
            oss << "  \"description\": \"" << description << "\",\n";
 
            // Metrics
            oss << "  \"metrics\": {\n";
            oss << std::fixed << std::setprecision(4);
            oss << "    \"queue_saturation\": " << queue_saturation << ",\n";
            oss << std::setprecision(3);
            oss << "    \"avg_wait_time_ms\": " << avg_wait_time_ms << ",\n";
            oss << std::setprecision(4);
            oss << "    \"worker_utilization\": " << worker_utilization << ",\n";
            oss << "    \"utilization_variance\": " << utilization_variance << ",\n";
            oss << "    \"estimated_backlog_time_ms\": " << estimated_backlog_time_ms << ",\n";
            oss << "    \"queue_depth\": " << queue_depth << ",\n";
            oss << "    \"idle_workers\": " << idle_workers << ",\n";
            oss << "    \"total_workers\": " << total_workers << ",\n";
            oss << "    \"jobs_rejected\": " << jobs_rejected << "\n";
            oss << "  },\n";
 
            // Recommendations
            oss << "  \"recommendations\": [";
            for (std::size_t i = 0; i < recommendations.size(); ++i)
            {
                oss << "\n    \"" << recommendations[i] << "\"";
                if (i < recommendations.size() - 1)
                {
                    oss << ",";
                }
            }
            if (!recommendations.empty())
            {
                oss << "\n  ";
            }
            oss << "]\n";
 
            oss << "}";
            return oss.str();
        }
 
        [[nodiscard]] auto to_string() const -> std::string
        {
            std::ostringstream oss;
 
            oss << "=== Bottleneck Report ===\n";
            if (has_bottleneck)
            {
                oss << "Status: DETECTED (" << severity_string() << " severity)\n";
                oss << "Type: " << bottleneck_type_to_string(type) << "\n";
                oss << "Description: " << description << "\n\n";
            }
            else
            {
                oss << "Status: No bottleneck detected\n\n";
            }
 
            // Metrics
            oss << "Metrics:\n";
            oss << std::fixed;
            oss << "  Queue: " << queue_depth << " items ("
                << std::setprecision(1) << (queue_saturation * 100.0) << "% saturated)\n";
            oss << "  Workers: " << (total_workers - idle_workers) << "/" << total_workers
                << " active (" << idle_workers << " idle)\n";
            oss << "  Utilization: " << std::setprecision(1) << (worker_utilization * 100.0)
                << "% (variance: " << std::setprecision(4) << utilization_variance << ")\n";
            oss << "  Wait time: " << std::setprecision(3) << avg_wait_time_ms << "ms avg\n";
            oss << "  Backlog: ~" << estimated_backlog_time_ms << "ms to clear\n";
 
            if (jobs_rejected > 0)
            {
                oss << "  Jobs rejected: " << jobs_rejected << "\n";
            }
 
            // Recommendations
            if (!recommendations.empty())
            {
                oss << "\nRecommendations:\n";
                for (const auto& rec : recommendations)
                {
                    oss << "  - " << rec << "\n";
                }
            }
 
            return oss.str();
        }
    };
 
} // namespace kcenon::thread::diagnostics