kcenon::pacs::monitoring::health_checker Class Reference

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.

Example:

// Create and configure the health checker
health_checker_config config;
config.check_interval = std::chrono::seconds{30};
config.storage_warning_threshold = 80.0;
 
health_checker checker{config};
 
// Register components to monitor
checker.set_database(&database);
checker.set_storage(&storage);
 
// Perform health check
auto status = checker.check();
if (status.is_healthy()) {
    // System is healthy
}
 
// Get cached result for frequent calls
auto cached = checker.get_cached_status();

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.

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.

Definition at line 25 of file health_checker.cpp.

: health_checker(health_checker_config{}) {}

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.

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

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

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

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

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)

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)

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

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

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

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

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

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

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)

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)

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)

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

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

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

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

References kcenon::pacs::monitoring::storage_metrics::failed_stores, mutex_, storage_metrics_, kcenon::pacs::monitoring::storage_metrics::successful_stores, kcenon::pacs::monitoring::storage_metrics::total_instances, kcenon::pacs::monitoring::storage_metrics::total_series, and kcenon::pacs::monitoring::storage_metrics::total_studies.

Member Data Documentation

associations_

association_metrics kcenon::pacs::monitoring::health_checker::associations_

private

Association metrics (updated externally)

Definition at line 341 of file health_checker.h.

Referenced by check(), and update_association_metrics().

cached_status_

health_status kcenon::pacs::monitoring::health_checker::cached_status_

private

Cached health status.

Definition at line 335 of file health_checker.h.

Referenced by check(), get_cached_status(), get_status(), and health_checker().

config_

health_checker_config kcenon::pacs::monitoring::health_checker::config_

private

Configuration.

Definition at line 323 of file health_checker.h.

Referenced by check_database(), check_storage(), config(), get_status(), and set_config().

custom_checks_

std::unordered_map<std::string, check_callback> kcenon::pacs::monitoring::health_checker::custom_checks_

private

Custom health checks.

Definition at line 332 of file health_checker.h.

Referenced by register_check(), run_custom_checks(), and unregister_check().

database_

kcenon::pacs::storage::index_database* kcenon::pacs::monitoring::health_checker::database_ {nullptr}

private

Database instance to monitor.

Definition at line 326 of file health_checker.h.

{nullptr};

Referenced by check_database(), and set_database().

last_check_time_

std::chrono::system_clock::time_point kcenon::pacs::monitoring::health_checker::last_check_time_

private

Timestamp of last check.

Definition at line 338 of file health_checker.h.

Referenced by check(), and get_status().

mutex_

std::shared_mutex kcenon::pacs::monitoring::health_checker::mutex_

mutableprivate

Mutex for thread safety.

Definition at line 350 of file health_checker.h.

Referenced by check(), check_database(), check_storage(), get_cached_status(), get_status(), register_check(), run_custom_checks(), set_config(), set_database(), set_storage(), set_version(), unregister_check(), update_association_metrics(), and update_storage_metrics().

storage_

kcenon::pacs::storage::file_storage* kcenon::pacs::monitoring::health_checker::storage_ {nullptr}

private

Storage instance to monitor.

Definition at line 329 of file health_checker.h.

{nullptr};

Referenced by check_storage(), and set_storage().

storage_metrics_

storage_metrics kcenon::pacs::monitoring::health_checker::storage_metrics_

private

Storage metrics (updated externally)

Definition at line 344 of file health_checker.h.

Referenced by check(), and update_storage_metrics().

version_

version_info kcenon::pacs::monitoring::health_checker::version_

private

Version information.

Definition at line 347 of file health_checker.h.

Referenced by check(), health_checker(), and set_version().

---

The documentation for this class was generated from the following files:

• include/kcenon/pacs/monitoring/health_checker.h
• src/monitoring/health_checker.cpp