thread_pool_diagnostics.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
 
 // end of diagnostics
 
#include "thread_info.h"
#include "job_info.h"
#include "bottleneck_report.h"
#include "health_status.h"
#include "execution_event.h"
 
#include <atomic>
#include <chrono>
#include <cstddef>
#include <deque>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
 
namespace kcenon::thread
{
    // Forward declarations
    class thread_pool;
    class thread_worker;
 
namespace diagnostics
{
    struct diagnostics_config
    {
        std::size_t recent_jobs_capacity{1000};
 
        std::size_t event_history_size{1000};
 
        bool enable_tracing{false};
 
        double queue_saturation_high{0.8};
 
        double utilization_high_threshold{0.9};
 
        double wait_time_threshold_ms{100.0};
 
        health_thresholds health_thresholds_config{};
 
        std::uint32_t event_sample_rate{1};
    };
 
    class thread_pool_diagnostics
    {
    public:
        explicit thread_pool_diagnostics(thread_pool& pool,
                                        const diagnostics_config& config = {});
 
        ~thread_pool_diagnostics();
 
        // Non-copyable, non-movable
        thread_pool_diagnostics(const thread_pool_diagnostics&) = delete;
        thread_pool_diagnostics& operator=(const thread_pool_diagnostics&) = delete;
        thread_pool_diagnostics(thread_pool_diagnostics&&) = delete;
        thread_pool_diagnostics& operator=(thread_pool_diagnostics&&) = delete;
 
        // =========================================================================
        // Thread Dump
        // =========================================================================
 
        [[nodiscard]] auto dump_thread_states() const -> std::vector<thread_info>;
 
        [[nodiscard]] auto format_thread_dump() const -> std::string;
 
        // =========================================================================
        // Job Inspection
        // =========================================================================
 
        [[nodiscard]] auto get_active_jobs() const -> std::vector<job_info>;
 
        [[nodiscard]] auto get_pending_jobs(std::size_t limit = 100) const
            -> std::vector<job_info>;
 
        [[nodiscard]] auto get_recent_jobs(std::size_t limit = 100) const
            -> std::vector<job_info>;
 
        void record_job_completion(const job_info& info);
 
        // =========================================================================
        // Bottleneck Detection
        // =========================================================================
 
        [[nodiscard]] auto detect_bottlenecks() const -> bottleneck_report;
 
        // =========================================================================
        // Health Checks
        // =========================================================================
 
        [[nodiscard]] auto health_check() const -> health_status;
 
        [[nodiscard]] auto is_healthy() const -> bool;
 
        // =========================================================================
        // Event Tracing
        // =========================================================================
 
        void enable_tracing(bool enable, std::size_t history_size = 1000);
 
        [[nodiscard]] auto is_tracing_enabled() const -> bool;
 
        void add_event_listener(std::shared_ptr<execution_event_listener> listener);
 
        void remove_event_listener(std::shared_ptr<execution_event_listener> listener);
 
        void record_event(const job_execution_event& event);
 
        [[nodiscard]] auto get_recent_events(std::size_t limit = 100) const
            -> std::vector<job_execution_event>;
 
        // =========================================================================
        // Export
        // =========================================================================
 
        [[nodiscard]] auto to_json() const -> std::string;
 
        [[nodiscard]] auto to_string() const -> std::string;
 
        [[nodiscard]] auto to_prometheus() const -> std::string;
 
        // =========================================================================
        // Configuration
        // =========================================================================
 
        [[nodiscard]] auto get_config() const -> diagnostics_config;
 
        void set_config(const diagnostics_config& config);
 
    private:
        thread_pool& pool_;
 
        diagnostics_config config_;
 
        std::atomic<bool> tracing_enabled_{false};
 
        mutable std::mutex events_mutex_;
 
        std::deque<job_execution_event> event_history_;
 
        mutable std::mutex jobs_mutex_;
 
        std::deque<job_info> recent_jobs_;
 
        mutable std::mutex listeners_mutex_;
 
        std::vector<std::shared_ptr<execution_event_listener>> listeners_;
 
        std::atomic<std::uint64_t> next_event_id_{0};
 
        std::chrono::steady_clock::time_point start_time_;
 
        // =========================================================================
        // Internal Helpers
        // =========================================================================
 
        [[nodiscard]] auto get_worker_info(const thread_worker& worker,
                                           std::size_t index) const -> thread_info;
 
        void notify_listeners(const job_execution_event& event);
 
        void generate_recommendations(bottleneck_report& report) const;
 
        [[nodiscard]] auto check_worker_health() const -> component_health;
 
        [[nodiscard]] auto check_queue_health() const -> component_health;
 
        [[nodiscard]] auto check_metrics_health(double avg_latency_ms,
                                                double success_rate) const -> component_health;
    };
 
} // namespace diagnostics
} // namespace kcenon::thread