WL#17325: Health Monitor: Platform Support

High Level Description

The Health Monitor collectors currently assume a Linux host. They read resource data directly from Linux-specific sources such as /proc and /sys.

This worklog moves operating system resource collection behind platform APIs in components/library_mysys. The Health Monitor will use these APIs instead of reading platform files or calling native operating system APIs directly.

Linux remains the complete behavioral baseline. The first Community Edition release will add basic macOS support for memory usage, filesystem usage and CPU usage. Metrics without a reasonable macOS equivalent will be reported as unavailable and exposed as NULL in the corresponding Performance Schema columns.

Windows support is not part of the first release. Existing Windows-specific Health Monitor resource collection will be removed. A future Windows implementation can be designed against the new platform-neutral API.

The current Linux implementation will also be reviewed for correctness, security and performance issues before it becomes a public shared implementation.

Scope for the First Release

Memory

macOS will provide a reasonable view of:

• Total physical memory.
• Free memory.
• Available memory.
• Used memory derived from the documented available-memory definition.
• Swap capacity where macOS provides an equivalent value.

Linux-specific memory breakdowns such as buffers and slab memory will remain unavailable on macOS unless an Apple value with equivalent semantics is identified. The implementation must document how macOS available memory is calculated. It must not present a related Apple value as equivalent to Linux MemAvailable without defining the difference.

Disk

macOS will provide filesystem usage for the configured monitored path:

• Filesystem identity.
• Mount point and filesystem type.
• Capacity in bytes.
• Available space in bytes.
• Used space derived from capacity and available space.

Basic macOS support does not require Linux-equivalent block device inventory, partition hierarchy, device I/O timing or flush counters. Those metrics may remain unavailable.

APFS volumes can share container capacity. The reported and forecast values describe available space for the filesystem containing the monitored path. They do not represent MySQL data growth in isolation.

CPU

macOS will provide:

• Aggregate CPU user, system, idle and nice time.
• Per-CPU values where the Apple API provides them reliably.

Linux-specific CPU fields such as I/O wait, IRQ, soft IRQ, steal, guest and guest nice time will remain unavailable on macOS unless equivalent semantics are verified.

Functional Requirements

FR-1 Platform API

library_mysys provides platform-neutral APIs for filesystem, storage device, host memory, host CPU, process memory and process thread data used by the Health Monitor.

FR-2 Linux Support

library_mysys provides Linux implementations for the resource capabilities currently used by the Health Monitor.

FR-3 macOS Support

library_mysys provides basic macOS implementations for memory usage, filesystem usage and CPU usage. The implementation uses supported Apple APIs instead of Linux /proc or /sys paths.

FR-4 Health Monitor Integration

The Health Monitor collectors use library_mysys for operating system resource data. Health Monitor code no longer reads /proc or /sys, parses platform-specific formats or calls native resource APIs directly.

FR-5 Metric Availability

Each API query returns an aggregate snapshot. Each capability within the snapshot is complete, unavailable or failed. Individual fields inside a populated capability are not optional.

Unavailable and failed capabilities remain distinct from measurements whose value is zero.

FR-6 Nullable Metrics

Performance Schema metric columns are nullable. The Health Monitor writes NULL when an API capability needed for a metric is unavailable. It must not write zero as a substitute for an unavailable metric.

Timestamps and identity columns may remain non-null when they are always known and are not themselves metrics.

FR-7 MHS Compatibility

The Linux implementation preserves the resource values, units and collector behavior currently used by MHS unless a correctness or security fix is identified and reviewed as part of this worklog.

FR-8 Windows Removal

Existing Windows-specific Health Monitor resource collection code is removed. No replacement Windows implementation is included in this worklog.

FR-9 Build Support

The Health Monitor component builds on Linux and macOS.

FR-10 Disk Forecast Input

Linux and macOS provide complete, validated filesystem usage samples for the disk metric buffer. Incomplete or failed samples are not used by disk forecasting.

FR-11 Tests

The worklog adds unit tests for the shared API contract, Linux parsing, basic macOS collection, unavailable capabilities, failure handling and nullable Performance Schema metrics.

Non-functional Requirements

NFR-1 Platform-neutral Interface

Public types and function names describe resource capabilities, not operating system sources. Names such as ProcFS, Proc_Meminfo and SysFS do not become public API names.

NFR-2 Dependencies

The implementation adds no third-party dependencies. Platform-specific source files may use operating system libraries or frameworks available on the target platform.

NFR-3 Performance

One domain query should reuse native results when populating related capabilities. The implementation must avoid duplicate file reads, repeated directory scans and repeated native API calls within one snapshot.

Values that do not change during the process lifetime, such as page size and clock tick rate, may be cached.

NFR-4 Security and Robustness

The Linux implementation validates dynamic path elements such as device names and thread identifiers before using them to construct /proc or /sys paths. Parsers handle missing, partial and malformed input without out-of-bounds access, integer overflow or acceptance of partial records.

NFR-5 Error Handling

The API distinguishes unavailable capabilities from collection failures. Native errors are retained as std::error_code values where practical. Repeated failures must not produce repeated noisy warnings.

NFR-6 Thread Safety

The APIs are safe for calls from Health Monitor collector threads. Shared caches are immutable after initialization or protected from concurrent access.

NFR-7 Scope Control

This worklog does not change Health Monitor thresholds, state machine policy, configuration defaults, public names or source location. Resource simulation, broad refactoring, comprehensive disk forecasting work and the public source move remain separate worklogs.

Generic component runtime calls such as thread joins and timestamps remain in the Health Monitor. Only operating system resource discovery and collection move behind library_mysys.

High Level Specification

• Platform API Boundary
• API Principles
  • Capability-based Results
  • No Platform Knowledge in Callers
  • Metric Normalization
  • Availability and Failure
  • Nullable Performance Schema Metrics
  • One Query Per Resource Domain
  • C++23 and Library Support
  • Platform Isolation
  • Data Integrity
• Health Monitor Functions To Move
• Existing-to-New Function Mapping
• Linux Implementation
• Apple Implementation
• Health Monitor Integration
• Build Changes
• Existing Shared Code
• Disk Forecasting
• Testing

Platform API Boundary

The public declarations will be under include/mysql/components/library_mysys. Common orchestration will be implemented under components/library_mysys, with Linux and Apple implementations under components/library_mysys/my_system_api.

The new API consists of six domain queries:

Each function returns one aggregate snapshot. It does not accept a capability request mask. The platform implementation collects the related data available at that sampling point and marks each substructure as available, unavailable or failed.

API Principles

Capability-based Results

Each domain query returns a superset of related capability structures. A capability is all-or-nothing: If it is available, every field in the structure is valid and has the documented meaning.

std::optional is used only inside the capability wrapper to hold an entire result structure. Individual metric fields do not mix optional and non-optional values.

No Platform Knowledge in Callers

Health Monitor code checks capability state, not LINUX, APPLE or platform-specific metric lists. The platform implementation decides which capabilities it can provide.

Metric Normalization

The API normalizes values before returning them:

• Memory and storage values use bytes.
• Time values use std::chrono::milliseconds.
• Swap activity uses bytes.
• CPU and I/O counters are cumulative and their starting point is documented.
• Device sectors, memory pages, clock ticks and KiB source values do not cross the public API boundary.

Availability and Failure

Unavailable means the platform does not provide a capability with the required semantics. Failed means the platform supports the capability but collection failed.

Unavailable and failed capabilities do not contain a value. A successful measurement of zero remains a valid value.

Nullable Performance Schema Metrics

The Health Monitor maps unavailable metrics to SQL NULL. Nullable table columns are a presentation boundary only. Internal calculations, state machines and forecasting consume complete validated capability structures.

One Query Per Resource Domain

Related values are returned by one domain query so the platform implementation can share file reads and native calls. Unrelated resources with different sampling costs remain separate queries. In particular, process memory remains separate from process thread enumeration.

C++23 and Library Support

MySQL builds as C++23, but std::expected and related library support are not available in every supported compiler and standard library. This API does not use std::expected and does not introduce a new general-purpose substitute.

The API uses std::optional only for whole capability results, plus C++17 or earlier library features such as std::string_view, std::error_code and std::chrono.

The InnoDB and Router substitutes for std::expected remain owned by those subsystems. Moving either implementation to a common location is outside this worklog.

Platform Isolation

Platform selection occurs in CMake. Common source files do not contain chains of Linux, Apple and Windows preprocessor branches. Platform-specific parsing and native calls remain in platform translation units.

The private Linux implementation may use a stateful Procfs_reader with configurable /proc and /sys roots for deterministic unit tests. ProcFS and SysFS are not public API classes.

Data Integrity

Platform implementations build capability values locally and publish them only after all required fields validate. Partial parser output is never exposed as an available capability.

The public query functions are not declared noexcept because their result types contain strings and vectors. Platform, parsing and filesystem failures are returned through capability state. Allocation failures follow the existing MySQL process policy rather than being hidden as platform collection errors.

Health Monitor Functions To Move

The following functions or operations are currently implemented in the Health Monitor. Their resource collection will move to, or be replaced by, the new library_mysys API.

Parser helpers and lookup-only functions remain private implementation details or are removed when no longer needed. Unused data is not added to the public API only because the current Linux parser collects it.

New Function Mapping

Linux Implementation

The Linux implementation moves required /proc and /sys parsing behind the new API. It preserves current units and meanings where they are correct.

The implementation review includes:

• Validation of device names, thread identifiers and constructed paths.
• Safe handling of missing fields, short records, malformed values and files that change while being read.
• Overflow checks when converting pages, sectors, clock ticks and KiB values.
• Correct device-number handling and mount matching.
• Correct sector size handling without silently applying an incorrect conversion.
• Avoiding repeated reads of the same /proc or /sys source within one query.
• Removing collection of values that have no consumer.
• Verifying ProcFS::check_paths() return semantics. Its documented success value is 0, but the current implementation returns 1 when no bad paths are found.
• Complete capability validation before publishing a value.

Linux parser unit tests use controlled input files. Access to live /proc and /sys is limited to platform integration tests.

Apple Implementation

The Apple implementation provides the same six entry points. It uses native interfaces such as sysctl, Mach host APIs, mount APIs and filesystem APIs as appropriate.

First-release Apple work is limited to the memory, filesystem and CPU capabilities defined under First-release Scope. Other capabilities return unavailable rather than fabricated data.

Related values returned by one Apple API call are collected once and reused within the aggregate snapshot.

Health Monitor Integration

The disk, memory and system collectors convert available capability structures into Health Monitor records. The collectors continue to own timestamps, buffers, state transitions, warning policy and Performance Schema table updates.

After integration:

• health_monitor_procfs.cc and health_monitor_procfs.h no longer provide the collector-facing platform interface.
• Health Monitor code does not open /proc or /sys directly.
• Health Monitor code does not call Apple native resource APIs directly.
• Existing Windows-specific resource collection branches are removed.
• Metric columns are set to NULL when their source capability is unavailable.
• Platform-specific compilation is contained in library_mysys platform files.

Build Changes

components/library_mysys/CMakeLists.txt already selects my_system_api_linux.cc for LINUX and my_system_api_apple.cc for APPLE. It will include the new common and platform source files and private Apple frameworks if required.

The supported build condition remains explicit:

cmake IF(LINUX OR APPLE) ADD_SUBDIRECTORY(components/health_monitor) ENDIF()

Existing Shared Code

components/group_replication_resource_manager contains separate Linux and Apple host-memory collection. Its Apple implementation will be reviewed for reusable logic.

The new memory API is suitable for both consumers, but changing Group Replication to consume it is not required by this worklog. That change can be tracked separately after the API is available.

Disk Forecasting

The current disk forecaster consumes timestamp, total space and used space. It does not require Linux block device I/O statistics. Linux and macOS can therefore provide the same forecasting input from the filesystem usage capability.

Only complete and validated filesystem usage samples enter the disk metric buffer. NULL, unavailable and failed values are never converted to zero or passed to the forecaster. The implementation validates that capacity is greater than zero and available space does not exceed capacity before calculating used space.

The filesystem identity is used to detect that the monitored path has moved to another filesystem. A filesystem identity change resets the metric series so samples from different filesystems are not combined.

APFS shared capacity means the forecast describes available space for the monitored filesystem, not MySQL data growth alone.

Testing

library_mysys tests cover:

• Capability result state and value invariants.
• Linux parser success and failure using controlled files.
• Missing, truncated, malformed and out-of-range Linux input.
• Basic Apple memory, filesystem and CPU success paths.
• Available, unavailable and failed capability states.
• Unit and time conversions.
• Filesystem identity and usage validation.
• Repeated sampling without stale or accumulated output.

Health Monitor tests cover:

• Collector conversion from capability results.
• Existing Linux table values and behavior.
• NULL for unavailable metrics and zero for valid zero measurements.
• Collector failure and recovery behavior.
• Complete disk metric samples and rejection of incomplete samples.
• Linux and macOS component build coverage.

Low Level Design Specification

Public Header

The new API will be declared in include/mysql/components/library_mysys/system_info.h.

#pragma once

#include <cassert>
#include <chrono>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <system_error>
#include <utility>
#include <vector>

namespace mysql::system_info {

enum class Result_state {
  available,
  unavailable,
  failed
};

template <typename T>
class System_result {
public:
  System_result() = default;

  [[nodiscard]] static System_result success(T value) {
    System_result result;
    result.m_state = Result_state::available;
    result.m_value.emplace(std::move(value));
    return result;
  }

  [[nodiscard]] static System_result unavailable() {
    return System_result{};
  }

  [[nodiscard]] static System_result failure(std::error_code error) {
    System_result result;
    result.m_state = Result_state::failed;
    result.m_error = error;
    return result;
  }

  [[nodiscard]] Result_state state() const noexcept { return m_state; }

  [[nodiscard]] bool has_value() const noexcept {
    return m_state == Result_state::available;
  }

  [[nodiscard]] const T &value() const & {
    assert(has_value());
    return *m_value;
  }

  [[nodiscard]] T &value() & {
    assert(has_value());
    return *m_value;
  }

  [[nodiscard]] T &&value() && {
    assert(has_value());
    return std::move(*m_value);
  }

  [[nodiscard]] const std::error_code &error() const noexcept {
    assert(m_state == Result_state::failed);
    return m_error;
  }

private:
  Result_state m_state{Result_state::unavailable};
  std::optional<T> m_value;
  std::error_code m_error;
};

struct Filesystem_identity {
  std::string filesystem_id;
  std::string mount_point;
  std::string mount_source;
  std::string filesystem_type;
};

struct Filesystem_usage {
  uint64_t capacity_bytes{0};
  uint64_t available_bytes{0};
};

struct Filesystem_snapshot {
  System_result<Filesystem_identity> identity;
  System_result<Filesystem_usage> usage;
};

enum class Storage_device_kind {
  disk,
  partition,
  volume,
  virtual_device,
  unknown
};

struct Storage_device {
  std::string name;
  Storage_device_kind kind{Storage_device_kind::unknown};
};

struct Storage_inventory {
  std::vector<Storage_device> devices;
};

struct Storage_device_capacity {
  std::string device;
  uint64_t capacity_bytes{0};
  uint64_t sector_size_bytes{0};
};

struct Storage_capacities {
  std::vector<Storage_device_capacity> devices;
};

struct Storage_device_relationship {
  std::string device;
  std::string parent_device;
};

struct Storage_hierarchy {
  std::vector<Storage_device_relationship> relationships;
};

struct Storage_read_write_counters {
  std::string device;
  uint64_t read_count{0};
  uint64_t read_bytes{0};
  std::chrono::milliseconds read_time{0};
  uint64_t write_count{0};
  uint64_t write_bytes{0};
  std::chrono::milliseconds write_time{0};
};

struct Storage_read_write_snapshot {
  std::vector<Storage_read_write_counters> devices;
};

struct Storage_flush_counters {
  std::string device;
  uint64_t flush_count{0};
  std::chrono::milliseconds flush_time{0};
};

struct Storage_flush_snapshot {
  std::vector<Storage_flush_counters> devices;
};

struct Storage_snapshot {
  System_result<Storage_inventory> inventory;
  System_result<Storage_capacities> capacities;
  System_result<Storage_hierarchy> hierarchy;
  System_result<Storage_read_write_snapshot> read_write;
  System_result<Storage_flush_snapshot> flush;
};

struct Host_memory_info {
  uint64_t total_bytes{0};
  uint64_t free_bytes{0};
  uint64_t available_bytes{0};
};

struct Host_memory_breakdown {
  uint64_t buffer_bytes{0};
  uint64_t cache_bytes{0};
  uint64_t slab_bytes{0};
};

struct Swap_capacity_info {
  uint64_t total_bytes{0};
  uint64_t free_bytes{0};
};

struct Swap_activity_info {
  uint64_t bytes_in{0};
  uint64_t bytes_out{0};
};

struct Host_memory_snapshot {
  System_result<Host_memory_info> memory;
  System_result<Host_memory_breakdown> breakdown;
  System_result<Swap_capacity_info> swap_capacity;
  System_result<Swap_activity_info> swap_activity;
};

struct Cpu_times {
  std::string cpu;
  std::chrono::milliseconds user{0};
  std::chrono::milliseconds nice{0};
  std::chrono::milliseconds system{0};
  std::chrono::milliseconds idle{0};
};

struct Cpu_times_snapshot {
  std::vector<Cpu_times> cpus;
};

struct Cpu_extended_times {
  std::string cpu;
  std::chrono::milliseconds io_wait{0};
  std::chrono::milliseconds irq{0};
  std::chrono::milliseconds soft_irq{0};
  std::chrono::milliseconds steal{0};
  std::chrono::milliseconds guest{0};
  std::chrono::milliseconds guest_nice{0};
};

struct Cpu_extended_snapshot {
  std::vector<Cpu_extended_times> cpus;
};

struct Host_cpu_snapshot {
  System_result<Cpu_times_snapshot> times;
  System_result<Cpu_extended_snapshot> extended_times;
};

struct Process_identity {
  uint64_t pid{0};
  std::string name;
};

struct Process_memory_usage {
  uint64_t resident_bytes{0};
  uint64_t virtual_bytes{0};
  uint64_t data_bytes{0};
  uint64_t swap_bytes{0};
  uint64_t resident_limit_bytes{0};
};

struct Process_page_faults {
  uint64_t major_faults{0};
};

struct Process_memory_snapshot {
  System_result<Process_identity> identity;
  System_result<Process_memory_usage> memory;
  System_result<Process_page_faults> page_faults;
};

enum class Thread_state {
  running,
  sleeping,
  waiting,
  stopped,
  zombie,
  unknown
};

struct Thread_identity {
  uint64_t tid{0};
  std::string name;
  Thread_state state{Thread_state::unknown};
};

struct Thread_inventory {
  std::vector<Thread_identity> threads;
};

struct Process_runtime_info {
  uint32_t thread_count{0};
  uint64_t virtual_bytes{0};
  uint64_t resident_bytes{0};
  uint64_t resident_limit_bytes{0};
};

struct Thread_cpu_times {
  uint64_t tid{0};
  std::chrono::milliseconds user{0};
  std::chrono::milliseconds system{0};
};

struct Thread_cpu_snapshot {
  std::vector<Thread_cpu_times> threads;
};

struct Thread_extended_cpu_times {
  uint64_t tid{0};
  std::chrono::milliseconds child_user{0};
  std::chrono::milliseconds child_system{0};
  std::chrono::milliseconds guest{0};
  std::chrono::milliseconds child_guest{0};
};

struct Thread_extended_cpu_snapshot {
  std::vector<Thread_extended_cpu_times> threads;
};

struct Thread_scheduler_info {
  uint64_t tid{0};
  uint32_t last_cpu{0};
  std::chrono::milliseconds block_io_delay{0};
};

struct Thread_scheduler_snapshot {
  std::vector<Thread_scheduler_info> threads;
};

struct Thread_io_counters {
  uint64_t tid{0};
  uint64_t read_bytes{0};
  uint64_t write_bytes{0};
};

struct Thread_io_snapshot {
  std::vector<Thread_io_counters> threads;
};

struct Process_threads_snapshot {
  System_result<Process_identity> identity;
  System_result<Thread_inventory> threads;
  System_result<Process_runtime_info> runtime;
  System_result<Thread_cpu_snapshot> cpu;
  System_result<Thread_extended_cpu_snapshot> extended_cpu;
  System_result<Thread_scheduler_snapshot> scheduler;
  System_result<Thread_io_snapshot> io;
};

[[nodiscard]] Filesystem_snapshot query_filesystem(std::string_view path);

[[nodiscard]] Storage_snapshot query_storage_devices();

[[nodiscard]] Host_memory_snapshot query_host_memory();

[[nodiscard]] Host_cpu_snapshot query_host_cpu();

[[nodiscard]] Process_memory_snapshot query_process_memory();

[[nodiscard]] Process_threads_snapshot query_process_threads();

}  // namespace mysql::system_info

System Result

System_result<T> has these invariants:

• available means value() contains a complete valid T.
• unavailable means no equivalent platform capability exists for this release.
• failed means collection was attempted but failed. error() contains the native or mapped error where practical.
• value() is valid only when has_value() is true.
• A failed or unavailable capability does not contain a partial value.
• Metric value zero has no special availability meaning.

Source Layout

The implementation will use this layout:

include/mysql/components/library_mysys/
  system_info.h

components/library_mysys/
  system_info.cc
  my_system_api/system_info_platform.h
  my_system_api/system_info_linux.cc
  my_system_api/system_info_linux_procfs.h
  my_system_api/system_info_linux_procfs.cc
  my_system_api/system_info_apple.cc

system_info.cc contains common validation and public orchestration. CMake selects the Linux or Apple platform implementation. No Windows implementation is added.

The private Linux reader owns configurable /proc and /sys root paths. Parser tests use fixture roots without changing global path variables.

Performance Schema Mapping

Collectors join available substructures when building a table row. If a substructure is unavailable or failed, only the columns derived from that substructure are set to NULL.

Examples:

• Host_memory_info populates total, free, available and derived used memory.
• Host_memory_breakdown populates buffers, cache and slab columns.
• Swap_capacity_info populates swap total, free and derived used columns.
• Swap_activity_info populates swap-in and swap-out columns.
• Cpu_times populates user, nice, system and idle columns.
• Cpu_extended_times populates I/O wait, IRQ, soft IRQ, steal, guest and guest nice columns.
• Storage_read_write_counters populates read and write columns.
• Storage_flush_counters populates flush columns.

The table adapter must set SQL NULL explicitly. It must not leave a stale field value from a previous row.

Filesystem Usage and Disk Metrics

query_filesystem() is successful for forecasting only when both identity and usage are available and these conditions hold:

capacity_bytes > 0
available_bytes <= capacity_bytes

Health Monitor calculates:

used_bytes = capacity_bytes - available_bytes

The library returns bytes. Health Monitor converts to MiB when writing Disk_Metric and Performance Schema rows.

filesystem_id is an opaque platform value. It must remain stable across samples for the same mounted filesystem during the server process lifetime, but callers must not parse it or persist assumptions about its format.

If identity changes, Health Monitor resets the disk metric stream before writing a sample for the new filesystem. If usage is unavailable or failed, no disk metric sample is written.