MySQL :: MySQL 26.10 Reference Manual :: 7.5.11.1 Disk Monitoring

Selecting the Monitored Filesystem

The health_monitor.disk_monitored system variable specifies the path to monitor. If health_monitor.disk_monitored is empty, the default, the Health Monitor monitors the filesystem containing the MySQL data directory. Health Monitor monitors one target filesystem; it does not combine capacity from every filesystem used by the server.

A nonempty value must be a valid absolute path, must not exceed 511 bytes. The path does not have to exist when the variable is set.

Measurements are stored in health_block_device. Each measurement contains the device, mount point, measurement time, total capacity, available capacity, and percentage in use. Storage quantities are expressed in bytes.

For example, to display the most recent measurements:

SELECT TIMESTAMP, DEVICE, MOUNT_POINT, TOTAL_BYTES, AVAILABLE_BYTES, USE_PERCENT
FROM performance_schema.health_block_device
ORDER BY `TIMESTAMP` DESC
LIMIT 10;

+---------------------+---------------------+-------------+-------------+-----------------+-------------+
| TIMESTAMP           | DEVICE              | MOUNT_POINT | TOTAL_BYTES | AVAILABLE_BYTES | USE_PERCENT |
+---------------------+---------------------+-------------+-------------+-----------------+-------------+
| 2026-10-12 17:02:01 | /dev/mapper/ok-root | /           | 75125227520 |     60801060864 |       19.07 |
| 2026-10-12 17:01:01 | /dev/mapper/ok-root | /           | 75125227520 |     60801060864 |       19.07 |
| 2026-10-12 17:00:01 | /dev/mapper/ok-root | /           | 75125227520 |     60801060864 |       19.07 |
| 2026-10-12 16:59:01 | /dev/mapper/ok-root | /           | 75125227520 |     60801060864 |       19.07 |
| 2026-10-12 16:58:01 | /dev/mapper/ok-root | /           | 75125227520 |     60801060864 |       19.07 |
| 2026-10-12 16:57:01 | /dev/mapper/ok-root | /           | 75125227520 |     60801060864 |       19.07 |
| 2026-10-12 16:56:01 | /dev/mapper/ok-root | /           | 75125227520 |     60800983040 |       19.07 |
| 2026-10-12 16:55:01 | /dev/mapper/ok-root | /           | 75125227520 |     60800983040 |       19.07 |
| 2026-10-12 16:54:01 | /dev/mapper/ok-root | /           | 75125227520 |     60800983040 |       19.07 |
| 2026-10-12 16:53:01 | /dev/mapper/ok-root | /           | 75125227520 |     60800983040 |       19.07 |
+---------------------+---------------------+-------------+-------------+-----------------+-------------+
10 rows in set (0.003 sec)

The default recording interval is 60 seconds, and the default history capacity represents 86400 seconds of samples. These settings retain 1440 measurements. Adjust them with health_monitor.disk_sample_rate and health_monitor.disk_retention.

If the configured path or data directory is unavailable:

The disk collector remains active but publishes no new disk samples.
Existing rows retain their normal retention behavior.
Disk forecasting pauses in `NORMAL` mode.
No fencing or recovery transition starts from an unavailable sample.
Memory and system-statistics collection continue.
The collector retries at its configured sample interval.
The Health Monitor writes one warning when the resource becomes unavailable and one message when sampling resumes.

Disk Limits and Warnings

The total storage available to a MySQL Server contains the following:

Available storage: The disk space after the storage reserve is excluded from the total storage.
Storage reserve: The disk space that is lesser of the health_monitor.disk_low_space_level and health_monitor.disk_low_space_percent system variables. The default value of health_monitor.disk_low_space_level is 5,000 MiB, and the default value of health_monitor.disk_low_space_percent is 4% of the total storage.
For example, if the total storage is 100,000 MiB, health_monitor.disk_low_space_level is 5,000 MiB, and health_monitor.disk_low_space_percent is 4%, the storage reserve is defined by health_monitor.disk_low_space_percent, which is the lesser of the two variables, 4000MiB.
Critical storage: The disk space in the storage reserve below the critical threshold, which is defined by health_monitor.disk_low_space_critical_level. This is the minimum viable disk space for the system to avoid disk exhaustion. The default critical storage space is 2,000 MiB.

Disk space warnings are defined using the health_monitor.disk_usage_warning_level_n system variables. Use these to generate warnings when the available disk space falls below defined percentages. The warnings, WARNING_DISK_USAGE_LEVEL_N, are logged in the error_log table.

Assuming a total storage of 100,000MiB, and a storage reserve of 4%, 4,000MiB, the following warnings are logged:

WARNING_DISK_USAGE_LEVEL_1: When the disk space falls below 20% of the available storage, which is 20/100*96,000 = 19,200 MiB.
WARNING_DISK_USAGE_LEVEL_2: When the disk space falls below 10% of the available storage, which is 10/100*96,000 = 9,600 MiB.
WARNING_DISK_USAGE_LEVEL_3: When the disk space falls below 5% of the available storage, which is 5/100*96,000 = 4,800 MiB.

Disk Fencing

When there is a significant or sustained shortage of disk space, and health_monitor.disk_fallback_enable=ON, Health Monitor does the following:

Sets the system variables, super_read_only=ON. MySQL rejects all new incoming SQL write statements, regardless of users and privileges. Running transactions are allowed to complete, but new writes are prohibited until disk space is available.

Note

In some cases, global read locks, ongoing commits, or metadata locks block the Health Monitor from setting super_read_only. In such cases, setting health_monitor.disk_fallback_force=ON enables the Health Monitor to identify and terminate active queries holding global locks before setting super_read_only=ON.
Sets the system variable, offline_mode=ON. The server disconnects client users who do not have the CONNECTION_ADMIN privilege, terminates running statements and releases locks, and blocks new connections with an appropriate error.
Sets the status variable, super_read_only_disk_full=ON indicating that read-only mode was triggered due to low disk space. You can see the value of super_read_only_disk_full status variable with either of the following commands:
```
SHOW GLOBAL STATUS WHERE variable_name = 'super_read_only_disk_full';
SELECT * FROM performance_schema.global_status WHERE variable_name = 'super_read_only_disk_full';
```

Disk fencing is disabled by default. To enable Health Monitor to change server modes in response to low storage:

SET GLOBAL health_monitor.disk_fallback_enable = ON;

When health_monitor.disk_fallback_enable=ON, Health Monitor activates disk fencing if either of the following conditions is detected:

Available space remains below the low space limit for longer than the value in health_monitor.disk_low_space_duration (default is 300 seconds).
Available space falls below health_monitor.disk_low_space_critical_level. This condition is unaffected by health_monitor.disk_low_space_duration.

Important

On a Group Replication primary, Health Monitor applies the disk protection policy used for a standalone server. On a secondary, it issues low space warnings but does not enable or disable offline_mode or super_read_only.

If a secondary is promoted to primary while storage remains low, it becomes eligible for the disk protection response. Before restoring normal operation on a primary, Health Monitor verifies that the server is online with the group majority.

Disk Recovery

Automatic disk recovery is enabled by default, with health_monitor.disk_recovery_enable=ON. Recovery applies only to server mode changes owned by Health Monitor.

If the super_read_only and offline_mode are set by Health Monitor, the following occurs:

Health Monitor checks the disk space every minute.
If the available disk space recovers and remains above health_monitor.disk_recovery_level for health_monitor.disk_recovery_time_1 seconds or more, Health Monitor sets offline_mode=OFF.
If the available disk space recovers and remains above health_monitor.disk_recovery_level for an additional health_monitor.disk_recovery_time_2 seconds or more, Health Monitor sets super_read_only=OFF.

Normal operations are resumed once the disk space remains above health_monitor.disk_recovery_level for health_monitor.disk_recovery_time_1 + health_monitor.disk_recovery_time_2 seconds. Once the disk space recovers, Health Monitor sets super_read_only=OFF and offline_mode=OFF.

Each time the server recovers from a significant or sustained shortage of disk space, Health Monitor increases the value of health_monitor.disk_recovery_time_1 and health_monitor.disk_recovery_time_2 by health_monitor.disk_recovery_increment seconds.

For example, if health_monitor.disk_recovery_time_1 is 300 seconds, and health_monitor.disk_recovery_time_2 is 600 seconds, and health_monitor.disk_recovery_increment is 400 seconds, the disk recovery time for each cycle is as follows:

Cycle 1: health_monitor.disk_recovery_time_1=300 and health_monitor.disk_recovery_time_2=600
Cycle 2: health_monitor.disk_recovery_time_1=700 and health_monitor.disk_recovery_time_2=1000
Cycle 3: health_monitor.disk_recovery_time_1=1100 and health_monitor.disk_recovery_time_2=1400

Health Monitor restores the normal operating mode a maximum of health_monitor.disk_recovery_max_cycles times within a fixed window of health_monitor.disk_recovery_window seconds from the last recovery cycle. For example, if health_monitor.disk_recovery_max_cycles is set to 5, and health_monitor.disk_recovery_window is set to 86,400 seconds (1 day), the Health Monitor can restore to the normal operating mode five times in a window of 86,400 seconds. If a significant or sustained shortage happens the sixth time in the same window, the system variables, super_read_only and offline_mode are set to ON.

Disk Forecasting

Health Monitor uses recent disk measurements to estimate future storage usage for the filesystem selected by health_monitor.disk_monitored. The empty default selects the data-directory filesystem. Forecasting is available on Linux and macOS when valid filesystem samples are available. It does not forecast object storage usage. Forecasting requires the following system variables:

health_monitor.disk_running = ON
health_monitor.disk_forecast_running = ON
health_monitor.disk_forecast_run_mode = 'NORMAL'

The forecaster uses the additive Holt-Winters model to account for a usage trend and recurring daily patterns. It provides forecasts for 1 hour, 24 hours, and 7 days ahead, together with confidence interval bounds. Forecasts are estimates based on prior measurements; abrupt workload or capacity changes can affect their accuracy.

Raw measurements and forecasts are available in the following Performance Schema tables:

disk_metric: Raw disk capacity and usage measurements.
disk_forecast: Predicted usage for each forecast horizon.
disk_forecast_summary: Current usage, projected growth, estimated time to exhaustion where applicable, and forecast status.

The raw metric table retains up to 20160 measurements. At the default interval of one minute, this represents 14 days. Forecast history has capacity for 1008 rows, corresponding to 14 days of hourly forecasts with three horizons; summary history has capacity for 336 rows. Forecast data is not persisted across restarts. Disabling and re-enabling collection does not erase existing data.

Forecast status is based on current usage, the projected usage rate, and estimated days to exhaustion. The usage rate expresses percentage points of total capacity per day.

The forecast is CRITICAL if any of these conditions applies:

Current usage is at least 90 percent and estimated exhaustion is within 2 days.
The usage rate is at least 15 percentage points per day.
Current usage is at least 95 percent.
Estimated exhaustion is within 1 day.

The forecast is WARNING if any of these conditions applies:

Current usage is at least 80 percent and estimated exhaustion is within 7 days.
The usage rate is at least 8 percentage points per day.

Otherwise, the status is NORMAL.