kcenon::thread::diagnostics::bottleneck_report Struct Reference

Analysis report of bottlenecks in the thread pool. More...

#include <bottleneck_report.h>

Collaboration diagram for kcenon::thread::diagnostics::bottleneck_report:

Public Member Functions
auto	severity () const -> int
	Gets the severity level of the bottleneck.
auto	severity_string () const -> std::string
	Gets severity as a string.
auto	requires_immediate_action () const -> bool
	Checks if immediate action is required.
auto	to_json () const -> std::string
	Converts the bottleneck report to a JSON string.
auto	to_string () const -> std::string
	Converts the bottleneck report to a human-readable string.

Public Attributes
bool	has_bottleneck {false}
	Whether a bottleneck was detected.
std::string	description
	Human-readable description of the bottleneck.
bottleneck_type	type {bottleneck_type::none}
	Type of bottleneck detected.
double	queue_saturation {0.0}
	Queue saturation level.
double	avg_wait_time_ms {0.0}
	Average wait time in milliseconds.
double	worker_utilization {0.0}
	Average worker utilization.
std::size_t	estimated_backlog_time_ms {0}
	Estimated time to process the current backlog.
double	utilization_variance {0.0}
	Variance in worker utilization.
std::uint64_t	jobs_rejected {0}
	Jobs rejected due to queue full.
std::size_t	queue_depth {0}
	Current queue depth.
std::size_t	idle_workers {0}
	Number of idle workers.
std::size_t	total_workers {0}
	Total number of workers.
std::vector< std::string >	recommendations
	Actionable recommendations to resolve the bottleneck.

Detailed Description

Analysis report of bottlenecks in the thread pool.

Contains the results of bottleneck analysis including the type of bottleneck detected, supporting metrics, and actionable recommendations.

Diagnosis Logic

queue_saturation > 0.9  → queue_full
avg_wait_time > threshold && worker_utilization > 0.9  → slow_consumer
worker_utilization > 0.95 && queue_saturation > 0.5   → worker_starvation
utilization variance high  → uneven_distribution

Usage Example

auto report = pool->diagnostics().detect_bottlenecks();
if (report.has_bottleneck) {
    LOG_WARN("Bottleneck: {} - {}", bottleneck_type_to_string(report.type),
             report.description);
    for (const auto& rec : report.recommendations) {
        LOG_INFO("  Recommendation: {}", rec);
    }
}

Definition at line 91 of file bottleneck_report.h.

Member Function Documentation

requires_immediate_action()

auto kcenon::thread::diagnostics::bottleneck_report::requires_immediate_action ( ) const -> bool

inlinenodiscard

Checks if immediate action is required.

Returns

true if severity is critical (3).

Definition at line 234 of file bottleneck_report.h.

        {
            return severity() >= 3;
        }

References severity().

Here is the call graph for this function:

severity()

auto kcenon::thread::diagnostics::bottleneck_report::severity ( ) const -> int

inlinenodiscard

Gets the severity level of the bottleneck.

Returns

Severity from 0 (none) to 3 (critical).

Definition at line 191 of file bottleneck_report.h.

        {
            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;
        }

References has_bottleneck, queue_saturation, and worker_utilization.

Referenced by requires_immediate_action(), and severity_string().

Here is the caller graph for this function:

severity_string()

auto kcenon::thread::diagnostics::bottleneck_report::severity_string ( ) const -> std::string

inlinenodiscard

Gets severity as a string.

Returns

Severity level string.

Definition at line 218 of file bottleneck_report.h.

        {
            switch (severity())
            {
                case 0: return "none";
                case 1: return "low";
                case 2: return "medium";
                case 3: return "critical";
                default: return "unknown";
            }
        }

References severity().

Referenced by to_json(), and to_string().

Here is the call graph for this function:

Here is the caller graph for this function:

to_json()

auto kcenon::thread::diagnostics::bottleneck_report::to_json ( ) const -> std::string

inlinenodiscard

Converts the bottleneck report to a JSON string.

Returns

JSON representation of the bottleneck report.

Output format:

{
  "has_bottleneck": true,
  "type": "slow_consumer",
  "severity": "medium",
  "description": "Workers cannot keep up with job submission rate",
  "metrics": {
    "queue_saturation": 0.75,
    "avg_wait_time_ms": 150.5,
    "worker_utilization": 0.92,
    "utilization_variance": 0.05,
    "estimated_backlog_time_ms": 5000,
    "queue_depth": 100,
    "idle_workers": 1,
    "total_workers": 8,
    "jobs_rejected": 0
  },
  "recommendations": [...]
}

Definition at line 265 of file bottleneck_report.h.

        {
            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();
        }

References avg_wait_time_ms, kcenon::thread::diagnostics::bottleneck_type_to_string(), description, estimated_backlog_time_ms, has_bottleneck, idle_workers, jobs_rejected, queue_depth, queue_saturation, recommendations, severity_string(), total_workers, type, utilization_variance, and worker_utilization.

Here is the call graph for this function:

to_string()

auto kcenon::thread::diagnostics::bottleneck_report::to_string ( ) const -> std::string

inlinenodiscard

Converts the bottleneck report to a human-readable string.

Returns

String representation of the bottleneck report.

Output format:

=== Bottleneck Report ===
Status: DETECTED (medium severity)
Type: slow_consumer
Description: Workers cannot keep up with job submission rate
 
Metrics:
  Queue: 100 items (75.0% saturated)
  Workers: 7/8 active (1 idle)
  Utilization: 92.0% (variance: 0.0500)
  Wait time: 150.500ms avg
  Backlog: ~5000ms to clear
 
Recommendations:
  - Add more worker threads
  - Optimize job execution time

Definition at line 333 of file bottleneck_report.h.

        {
            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();
        }

References avg_wait_time_ms, kcenon::thread::diagnostics::bottleneck_type_to_string(), description, estimated_backlog_time_ms, has_bottleneck, idle_workers, jobs_rejected, queue_depth, queue_saturation, recommendations, severity_string(), total_workers, type, utilization_variance, and worker_utilization.

Here is the call graph for this function:

Member Data Documentation

avg_wait_time_ms

double kcenon::thread::diagnostics::bottleneck_report::avg_wait_time_ms {0.0}

Average wait time in milliseconds.

Average time jobs spend waiting in the queue before execution.

Definition at line 127 of file bottleneck_report.h.

{0.0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

description

std::string kcenon::thread::diagnostics::bottleneck_report::description

Human-readable description of the bottleneck.

Empty if no bottleneck detected.

Definition at line 103 of file bottleneck_report.h.

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

estimated_backlog_time_ms

std::size_t kcenon::thread::diagnostics::bottleneck_report::estimated_backlog_time_ms {0}

Estimated time to process the current backlog.

Based on current processing rate and queue depth.

Definition at line 141 of file bottleneck_report.h.

{0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

has_bottleneck

bool kcenon::thread::diagnostics::bottleneck_report::has_bottleneck {false}

Whether a bottleneck was detected.

Definition at line 96 of file bottleneck_report.h.

{false};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), severity(), to_json(), and to_string().

idle_workers

std::size_t kcenon::thread::diagnostics::bottleneck_report::idle_workers {0}

Number of idle workers.

Definition at line 165 of file bottleneck_report.h.

{0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

jobs_rejected

std::uint64_t kcenon::thread::diagnostics::bottleneck_report::jobs_rejected {0}

Jobs rejected due to queue full.

Count of jobs rejected since last reset.

Definition at line 155 of file bottleneck_report.h.

{0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

queue_depth

std::size_t kcenon::thread::diagnostics::bottleneck_report::queue_depth {0}

Current queue depth.

Definition at line 160 of file bottleneck_report.h.

{0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

queue_saturation

double kcenon::thread::diagnostics::bottleneck_report::queue_saturation {0.0}

Queue saturation level.

Current queue depth as a ratio of maximum capacity (0.0 to 1.0+). Values above 1.0 indicate queue overflow attempts.

Definition at line 120 of file bottleneck_report.h.

{0.0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), severity(), to_json(), and to_string().

recommendations

std::vector<std::string> kcenon::thread::diagnostics::bottleneck_report::recommendations

Actionable recommendations to resolve the bottleneck.

List of suggestions based on the detected bottleneck type.

Definition at line 181 of file bottleneck_report.h.

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::generate_recommendations(), to_json(), and to_string().

total_workers

std::size_t kcenon::thread::diagnostics::bottleneck_report::total_workers {0}

Total number of workers.

Definition at line 170 of file bottleneck_report.h.

{0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

type

bottleneck_type kcenon::thread::diagnostics::bottleneck_report::type {bottleneck_type::none}

Type of bottleneck detected.

Definition at line 108 of file bottleneck_report.h.

{bottleneck_type::none};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), kcenon::thread::diagnostics::thread_pool_diagnostics::generate_recommendations(), to_json(), and to_string().

utilization_variance

double kcenon::thread::diagnostics::bottleneck_report::utilization_variance {0.0}

Variance in worker utilization.

High variance indicates uneven work distribution.

Definition at line 148 of file bottleneck_report.h.

{0.0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), to_json(), and to_string().

worker_utilization

double kcenon::thread::diagnostics::bottleneck_report::worker_utilization {0.0}

Average worker utilization.

Average ratio of busy time across all workers (0.0 to 1.0).

Definition at line 134 of file bottleneck_report.h.

{0.0};

Referenced by kcenon::thread::diagnostics::thread_pool_diagnostics::detect_bottlenecks(), severity(), to_json(), and to_string().

---

The documentation for this struct was generated from the following file:

• include/kcenon/thread/diagnostics/bottleneck_report.h