1.. SPDX-License-Identifier: GPL-2.0 2 3=================================== 4Data Access Monitoring Results Stat 5=================================== 6 7Data Access Monitoring Results Stat (DAMON_STAT) is a static kernel module that 8is aimed to be used for simple access pattern monitoring. It monitors accesses 9on the system's entire physical memory using DAMON, and provides simplified 10access monitoring results statistics, namely idle time percentiles and 11estimated memory bandwidth. 12 13.. _damon_stat_monitoring_accuracy_overhead: 14 15Monitoring Accuracy and Overhead 16================================ 17 18DAMON_STAT uses monitoring intervals :ref:`auto-tuning 19<damon_design_monitoring_intervals_autotuning>` to make its accuracy high and 20overhead minimum. It auto-tunes the intervals aiming 4 % of observable access 21events to be captured in each snapshot, while limiting the resulting sampling 22interval to be 5 milliseconds in minimum and 10 seconds in maximum. On a few 23production server systems, it resulted in consuming only 0.x % single CPU time, 24while capturing reasonable quality of access patterns. The tuning-resulting 25intervals can be retrieved via ``aggr_interval_us`` :ref:`parameter 26<damon_stat_aggr_interval_us>`. 27 28Interface: Module Parameters 29============================ 30 31To use this feature, you should first ensure your system is running on a kernel 32that is built with ``CONFIG_DAMON_STAT=y``. The feature can be enabled by 33default at build time, by setting ``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` true. 34 35To let sysadmins enable or disable it at boot and/or runtime, and read the 36monitoring results, DAMON_STAT provides module parameters. Following 37sections are descriptions of the parameters. 38 39enabled 40------- 41 42Enable or disable DAMON_STAT. 43 44You can enable DAMON_STAT by setting the value of this parameter as ``Y``. 45Setting it as ``N`` disables DAMON_STAT. The default value is set by 46``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` build config option. 47 48Note that this module (damon_stat) cannot run simultaneously with other 49DAMON-based special-purpose modules. Refer to :ref:`DAMON design special 50purpose modules exclusivity <damon_design_special_purpose_modules_exclusivity>` 51for more details. 52 53.. _damon_stat_aggr_interval_us: 54 55aggr_interval_us 56---------------- 57 58Auto-tuned aggregation time interval in microseconds. 59 60Users can read the aggregation interval of DAMON that is being used by the 61DAMON instance for DAMON_STAT. It is :ref:`auto-tuned 62<damon_stat_monitoring_accuracy_overhead>` and therefore the value is 63dynamically changed. 64 65estimated_memory_bandwidth 66-------------------------- 67 68Estimated memory bandwidth consumption (bytes per second) of the system. 69 70DAMON_STAT reads observed access events on the current DAMON results snapshot 71and converts it to memory bandwidth consumption estimation in bytes per second. 72The resulting metric is exposed to user via this read-only parameter. Because 73DAMON uses sampling, this is only an estimation of the access intensity rather 74than accurate memory bandwidth. 75 76memory_idle_ms_percentiles 77-------------------------- 78 79Per-byte idle time (milliseconds) percentiles of the system. 80 81DAMON_STAT calculates how long each byte of the memory was not accessed until 82now (idle time), based on the current DAMON results snapshot. For regions 83having access frequency (nr_accesses) larger than zero, how long the current 84access frequency level was kept multiplied by ``-1`` becomes the idlee time of 85every byte of the region. If a region has zero access frequency (nr_accesses), 86how long the region was keeping the zero access frequency (age) becomes the 87idle time of every byte of the region. Then, DAMON_STAT exposes the 88percentiles of the idle time values via this read-only parameter. Reading the 89parameter returns 101 idle time values in milliseconds, separated by comma. 90Each value represents 0-th, 1st, 2nd, 3rd, ..., 99th and 100th percentile idle 91times. 92