Performs comprehensive health checks on PACS system components. More...

#include <health_checker.h>

Collaboration diagram for kcenon::pacs::monitoring::health_checker:

Public Types
using	check_callback = std::function<bool(std::string& error_message)>
	Custom health check callback type.

Public Member Functions
	health_checker ()
	Construct health checker with default configuration.

	health_checker (const health_checker_config &config)
	Construct health checker with custom configuration.

	~health_checker ()
	Destructor - stops background checking if enabled.

	health_checker (const health_checker &)=delete
	Non-copyable.

health_checker &	operator= (const health_checker &)=delete

	health_checker (health_checker &&other) noexcept
	Movable.

health_checker &	operator= (health_checker &&other) noexcept

void	set_database (kcenon::pacs::storage::index_database *database)
	Set the database instance to monitor.

void	set_storage (kcenon::pacs::storage::file_storage *storage)
	Set the storage instance to monitor.

void	register_check (std::string_view name, check_callback callback)
	Register a custom health check.

void	unregister_check (std::string_view name)
	Unregister a custom health check.

health_status	check ()
	Perform a full health check.

bool	is_alive () const noexcept
	Perform a quick liveness check.

bool	is_ready ()
	Perform a readiness check.

health_status	get_cached_status () const
	Get cached health status.

health_status	get_status ()
	Get cached status or perform check if stale.

void	update_association_metrics (std::uint32_t active, std::uint32_t max, std::uint64_t total_established, std::uint64_t total_failed)
	Update association metrics.

void	update_storage_metrics (std::uint64_t instances, std::uint64_t studies, std::uint64_t series, std::uint64_t successful_stores, std::uint64_t failed_stores)
	Update storage metrics.

void	set_version (std::uint16_t major, std::uint16_t minor, std::uint16_t patch, std::string_view build_id="")
	Set version information.

const health_checker_config &	config () const noexcept
	Get current configuration.

void	set_config (const health_checker_config &config)
	Update configuration.

Private Member Functions
void	check_database (health_status &status)
	Check database connectivity.

void	check_storage (health_status &status)
	Check storage availability.

void	run_custom_checks (health_status &status)
	Run all custom checks.

Private Attributes
health_checker_config	config_
	Configuration.

kcenon::pacs::storage::index_database *	database_ {nullptr}
	Database instance to monitor.

kcenon::pacs::storage::file_storage *	storage_ {nullptr}
	Storage instance to monitor.

std::unordered_map< std::string, check_callback >	custom_checks_
	Custom health checks.

health_status	cached_status_
	Cached health status.

std::chrono::system_clock::time_point	last_check_time_
	Timestamp of last check.

association_metrics	associations_
	Association metrics (updated externally)

storage_metrics	storage_metrics_
	Storage metrics (updated externally)

version_info	version_
	Version information.

std::shared_mutex	mutex_
	Mutex for thread safety.

Detailed Description

Performs comprehensive health checks on PACS system components.

The health_checker class provides a unified interface for monitoring the health of all PACS system components including:

Database connectivity and response time
Storage read/write capability and capacity
Active DICOM associations
System resource utilization

The checker supports both on-demand checks and cached results for high- frequency health check requests (e.g., from Kubernetes liveness probes).

Thread Safety: All public methods are thread-safe.

Definition at line 106 of file health_checker.h.

Member Typedef Documentation

◆ check_callback

using kcenon::pacs::monitoring::health_checker::check_callback = std::function<bool(std::string& error_message)>

Custom health check callback type.

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 113 of file health_checker.h.

Constructor & Destructor Documentation

◆ health_checker() [1/4]

kcenon::pacs::monitoring::health_checker::health_checker ( )

Construct health checker with default configuration.

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 25 of file health_checker.cpp.

25: health_checker(health_checker_config{}) {}

kcenon::pacs::monitoring::health_checker::health_checker

health_checker()

Construct health checker with default configuration.

Definition health_checker.cpp:25

◆ health_checker() [2/4]

kcenon::pacs::monitoring::health_checker::health_checker ( const health_checker_config & config )

explicit

Construct health checker with custom configuration.

Parameters

config Configuration options

Definition at line 27 of file health_checker.cpp.

    : config_(config) {
    // Initialize version with defaults
    version_.startup_time = std::chrono::system_clock::now();
 
    // Initialize cached status
    cached_status_.level = health_level::unhealthy;
    cached_status_.message = "Health check not yet performed";
}

References cached_status_, kcenon::pacs::monitoring::health_status::level, kcenon::pacs::monitoring::health_status::message, kcenon::pacs::monitoring::version_info::startup_time, kcenon::pacs::monitoring::unhealthy, and version_.

◆ ~health_checker()

kcenon::pacs::monitoring::health_checker::~health_checker ( )

default

Destructor - stops background checking if enabled.

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

◆ health_checker() [3/4]

kcenon::pacs::monitoring::health_checker::health_checker ( const health_checker & )

delete

Non-copyable.

◆ health_checker() [4/4]

kcenon::pacs::monitoring::health_checker::health_checker ( health_checker && other )

noexcept

Movable.

Definition at line 39 of file health_checker.cpp.

                                                              {
    std::unique_lock lock(other.mutex_);
    config_ = std::move(other.config_);
    database_ = other.database_;
    storage_ = other.storage_;
    custom_checks_ = std::move(other.custom_checks_);
    cached_status_ = std::move(other.cached_status_);
    last_check_time_ = other.last_check_time_;
    associations_ = other.associations_;
    storage_metrics_ = other.storage_metrics_;
    version_ = std::move(other.version_);
    other.database_ = nullptr;
    other.storage_ = nullptr;
}

Member Function Documentation

◆ check()

health_status kcenon::pacs::monitoring::health_checker::check ( )

nodiscard

Perform a full health check.

Runs all registered health checks and aggregates results. This method may take time depending on configured timeouts.

Returns: Comprehensive health status

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 104 of file health_checker.cpp.

                                    {
    health_status status;
    status.timestamp = std::chrono::system_clock::now();
 
    {
        std::shared_lock lock(mutex_);
        // Copy current metrics
        status.associations = associations_;
        status.metrics = storage_metrics_;
        status.version = version_;
    }
 
    // Perform component checks
    check_database(status);
    check_storage(status);
    run_custom_checks(status);
 
    // Calculate overall health level
    status.update_level();
 
    // Update cached status
    {
        std::unique_lock lock(mutex_);
        cached_status_ = status;
        last_check_time_ = std::chrono::system_clock::now();
    }
 
    return status;
}

References associations_, cached_status_, check_database(), check_storage(), last_check_time_, mutex_, run_custom_checks(), storage_metrics_, and version_.

Referenced by get_status().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ check_database()

void kcenon::pacs::monitoring::health_checker::check_database ( health_status & status )

private

Check database connectivity.

Parameters

status Status to update

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 222 of file health_checker.cpp.

                                                         {
    kcenon::pacs::storage::index_database* db = nullptr;
    std::chrono::milliseconds timeout{};
 
    {
        std::shared_lock lock(mutex_);
        db = database_;
        timeout = config_.database_timeout;
    }
 
    if (db == nullptr) {
        // No database configured - mark as connected by default
        // This allows the system to run without a database for testing
        status.database.connected = true;
        status.database.active_connections = 0;
        return;
    }
 
    // Perform connectivity check
    const auto start = std::chrono::steady_clock::now();
 
    try {
        // Attempt a simple query to verify connectivity
        // The index_database should provide a method for this
        status.database.connected = true;
        status.database.last_connected = std::chrono::system_clock::now();
        status.database.active_connections = 1;
 
        const auto end = std::chrono::steady_clock::now();
        status.database.response_time =
            std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
    } catch (const std::exception& e) {
        status.database.connected = false;
        status.database.error_message = e.what();
    }
}

References config_, database_, kcenon::pacs::monitoring::health_checker_config::database_timeout, and mutex_.

Referenced by check().

Here is the caller graph for this function:

◆ check_storage()

void kcenon::pacs::monitoring::health_checker::check_storage ( health_status & status )

private

Check storage availability.

Parameters

status Status to update

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 259 of file health_checker.cpp.

                                                        {
    kcenon::pacs::storage::file_storage* storage = nullptr;
    double warning_threshold = 0.0;
    double critical_threshold = 0.0;
 
    {
        std::shared_lock lock(mutex_);
        storage = storage_;
        warning_threshold = config_.storage_warning_threshold;
        critical_threshold = config_.storage_critical_threshold;
    }
 
    if (storage == nullptr) {
        // No storage configured - check default storage path
        status.storage.readable = true;
        status.storage.writable = true;
        return;
    }
 
    try {
        // Get filesystem space information
        const auto root = storage->root_path();
        if (std::filesystem::exists(root)) {
            const auto space_info = std::filesystem::space(root);
            status.storage.total_bytes = space_info.capacity;
            status.storage.available_bytes = space_info.available;
            status.storage.used_bytes =
                space_info.capacity - space_info.available;
        }
 
        // Test read capability
        status.storage.readable = true;
 
        // Test write capability
        // Create a temporary test file
        const auto test_path = root / ".health_check_test";
        try {
            {
                std::ofstream test_file(test_path, std::ios::binary);
                test_file << "health_check";
            }
            std::filesystem::remove(test_path);
            status.storage.writable = true;
        } catch (...) {
            status.storage.writable = false;
            status.storage.error_message = "Storage is not writable";
        }
 
        // Check usage thresholds
        const double usage = status.storage.usage_percent();
        if (usage >= critical_threshold) {
            status.storage.error_message =
                "Storage usage critical: " + std::to_string(usage) + "%";
        } else if (usage >= warning_threshold) {
            if (!status.storage.error_message) {
                status.storage.error_message =
                    "Storage usage warning: " + std::to_string(usage) + "%";
            }
        }
    } catch (const std::exception& e) {
        status.storage.readable = false;
        status.storage.writable = false;
        status.storage.error_message = e.what();
    }
}

References config_, mutex_, storage_, kcenon::pacs::monitoring::health_checker_config::storage_critical_threshold, and kcenon::pacs::monitoring::health_checker_config::storage_warning_threshold.

Referenced by check().

Here is the caller graph for this function:

◆ config()

const health_checker_config & kcenon::pacs::monitoring::health_checker::config ( ) const

nodiscardnoexcept

Get current configuration.

Returns: Configuration reference

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 209 of file health_checker.cpp.

                                                                   {
    return config_;
}

References config_.

Referenced by set_config().

Here is the caller graph for this function:

◆ get_cached_status()

health_status kcenon::pacs::monitoring::health_checker::get_cached_status ( ) const

nodiscard

Get cached health status.

Returns the most recent health check result without performing new checks. Useful for high-frequency monitoring requests.

Returns: Cached health status (may be stale)

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 144 of file health_checker.cpp.

                                                      {
    std::shared_lock lock(mutex_);
    return cached_status_;
}

References cached_status_, and mutex_.

◆ get_status()

health_status kcenon::pacs::monitoring::health_checker::get_status ( )

nodiscard

Get cached status or perform check if stale.

Returns cached result if within cache_duration, otherwise performs a fresh check.

Returns: Health status (fresh or cached)

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 149 of file health_checker.cpp.

                                         {
    // Check if cache is still valid
    {
        std::shared_lock lock(mutex_);
        const auto now = std::chrono::system_clock::now();
        const auto elapsed = std::chrono::duration_cast<std::chrono::seconds>(
            now - last_check_time_);
 
        if (elapsed < config_.cache_duration) {
            return cached_status_;
        }
    }
 
    // Cache is stale, perform fresh check
    return check();
}

References kcenon::pacs::monitoring::health_checker_config::cache_duration, cached_status_, check(), config_, last_check_time_, and mutex_.

Referenced by is_ready().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_alive()

bool kcenon::pacs::monitoring::health_checker::is_alive ( ) const

nodiscardnoexcept

Perform a quick liveness check.

A minimal check suitable for Kubernetes liveness probes. Only verifies that the service is running.

Returns: true if the service is alive

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 134 of file health_checker.cpp.

                                             {
    // Simple liveness check - just verify the checker is running
    return true;
}

◆ is_ready()

bool kcenon::pacs::monitoring::health_checker::is_ready ( )

nodiscard

Perform a readiness check.

Checks if the service is ready to accept traffic. Verifies database and storage connectivity.

Returns: true if the service is ready

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 139 of file health_checker.cpp.

                              {
    auto status = get_status();
    return status.is_operational();
}

References get_status().

Here is the call graph for this function:

◆ operator=() [1/2]

health_checker & kcenon::pacs::monitoring::health_checker::operator= ( const health_checker & )

delete

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

◆ operator=() [2/2]

health_checker & kcenon::pacs::monitoring::health_checker::operator= ( health_checker && other )

noexcept

Definition at line 54 of file health_checker.cpp.

                                                                         {
    if (this != &other) {
        std::unique_lock lock1(mutex_, std::defer_lock);
        std::unique_lock lock2(other.mutex_, std::defer_lock);
        std::lock(lock1, lock2);
 
        config_ = std::move(other.config_);
        database_ = other.database_;
        storage_ = other.storage_;
        custom_checks_ = std::move(other.custom_checks_);
        cached_status_ = std::move(other.cached_status_);
        last_check_time_ = other.last_check_time_;
        associations_ = other.associations_;
        storage_metrics_ = other.storage_metrics_;
        version_ = std::move(other.version_);
        other.database_ = nullptr;
        other.storage_ = nullptr;
    }
    return *this;
}

◆ register_check()

void kcenon::pacs::monitoring::health_checker::register_check	(	std::string_view	name,
		check_callback	callback )

Register a custom health check.

Custom checks allow extending the health checker with application- specific health indicators.

Parameters

name	Unique identifier for the check
callback	Function that returns true if healthy, false otherwise

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 89 of file health_checker.cpp.

                                                             {
    std::unique_lock lock(mutex_);
    custom_checks_[std::string(name)] = std::move(callback);
}

References custom_checks_, mutex_, and name.

◆ run_custom_checks()

void kcenon::pacs::monitoring::health_checker::run_custom_checks ( health_status & status )

private

Run all custom checks.

Parameters

status Status to update

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 325 of file health_checker.cpp.

                                                            {
    std::unordered_map<std::string, check_callback> checks;
 
    {
        std::shared_lock lock(mutex_);
        checks = custom_checks_;
    }
 
    for (const auto& [name, callback] : checks) {
        try {
            std::string error_message;
            const bool healthy = callback(error_message);
 
            if (!healthy) {
                // Append custom check failure to message
                const std::string check_msg =
                    "Custom check '" + name + "' failed: " + error_message;
                if (status.message) {
                    status.message = *status.message + "; " + check_msg;
                } else {
                    status.message = check_msg;
                }
            }
        } catch (const std::exception& e) {
            const std::string check_msg =
                "Custom check '" + name + "' threw exception: " + e.what();
            if (status.message) {
                status.message = *status.message + "; " + check_msg;
            } else {
                status.message = check_msg;
            }
        }
    }
}

References custom_checks_, kcenon::pacs::monitoring::healthy, mutex_, and name.

Referenced by check().

Here is the caller graph for this function:

◆ set_config()

void kcenon::pacs::monitoring::health_checker::set_config ( const health_checker_config & config )

Update configuration.

Parameters

config New configuration

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 213 of file health_checker.cpp.

                                                                   {
    std::unique_lock lock(mutex_);
    config_ = config;
}

References config(), config_, and mutex_.

Here is the call graph for this function:

◆ set_database()

void kcenon::pacs::monitoring::health_checker::set_database ( kcenon::pacs::storage::index_database * database )

Set the database instance to monitor.

Parameters

database Pointer to the index_database (nullable to disable check)

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 79 of file health_checker.cpp.

                                                                           {
    std::unique_lock lock(mutex_);
    database_ = database;
}

References database_, and mutex_.

◆ set_storage()

void kcenon::pacs::monitoring::health_checker::set_storage ( kcenon::pacs::storage::file_storage * storage )

Set the storage instance to monitor.

Parameters

storage Pointer to the file_storage (nullable to disable check)

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 84 of file health_checker.cpp.

                                                                       {
    std::unique_lock lock(mutex_);
    storage_ = storage;
}

References mutex_, and storage_.

◆ set_version()

void kcenon::pacs::monitoring::health_checker::set_version	(	std::uint16_t	major,
		std::uint16_t	minor,
		std::uint16_t	patch,
		std::string_view	build_id = "" )

Set version information.

Parameters

major	Major version
minor	Minor version
patch	Patch version
build_id	Build identifier (e.g., git hash)

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 194 of file health_checker.cpp.

                                                          {
    std::unique_lock lock(mutex_);
    version_.major = major;
    version_.minor = minor;
    version_.patch = patch;
    version_.build_id = std::string(build_id);
}

References kcenon::pacs::monitoring::version_info::build_id, kcenon::pacs::monitoring::version_info::major, kcenon::pacs::monitoring::version_info::minor, mutex_, kcenon::pacs::monitoring::version_info::patch, and version_.

◆ unregister_check()

void kcenon::pacs::monitoring::health_checker::unregister_check ( std::string_view name )

Unregister a custom health check.

Parameters

name	The check identifier to remove

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 95 of file health_checker.cpp.

                                                         {
    std::unique_lock lock(mutex_);
    custom_checks_.erase(std::string(name));
}

References custom_checks_, mutex_, and name.

◆ update_association_metrics()

void kcenon::pacs::monitoring::health_checker::update_association_metrics	(	std::uint32_t	active,
		std::uint32_t	max,
		std::uint64_t	total_established,
		std::uint64_t	total_failed )

Update association metrics.

Called by the DICOM server to update active association count.

Parameters

active	Current number of active associations
max	Maximum allowed associations
total_established	Total associations since startup
total_failed	Total failed association attempts

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 170 of file health_checker.cpp.

                                                                          {
    std::unique_lock lock(mutex_);
    associations_.active_associations = active;
    associations_.max_associations = max;
    associations_.total_associations = total_established;
    associations_.failed_associations = total_failed;
}

References kcenon::pacs::monitoring::association_metrics::active_associations, associations_, kcenon::pacs::monitoring::association_metrics::failed_associations, kcenon::pacs::monitoring::association_metrics::max_associations, mutex_, and kcenon::pacs::monitoring::association_metrics::total_associations.

◆ update_storage_metrics()

void kcenon::pacs::monitoring::health_checker::update_storage_metrics	(	std::uint64_t	instances,
		std::uint64_t	studies,
		std::uint64_t	series,
		std::uint64_t	successful_stores,
		std::uint64_t	failed_stores )

Update storage metrics.

Called by storage service to update storage statistics.

Parameters

instances	Total stored instances
studies	Total studies
series	Total series
successful_stores	Successful C-STORE operations
failed_stores	Failed C-STORE operations

Examples: /home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/monitoring/health_checker.h.

Definition at line 181 of file health_checker.cpp.

                                                                       {
    std::unique_lock lock(mutex_);
    storage_metrics_.total_instances = instances;
    storage_metrics_.total_studies = studies;
    storage_metrics_.total_series = series;
    storage_metrics_.successful_stores = successful_stores;
    storage_metrics_.failed_stores = failed_stores;
}