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 48.. _damon_stat_aggr_interval_us: 49 50aggr_interval_us 51---------------- 52 53Auto-tuned aggregation time interval in microseconds. 54 55Users can read the aggregation interval of DAMON that is being used by the 56DAMON instance for DAMON_STAT. It is :ref:`auto-tuned 57<damon_stat_monitoring_accuracy_overhead>` and therefore the value is 58dynamically changed. 59 60estimated_memory_bandwidth 61-------------------------- 62 63Estimated memory bandwidth consumption (bytes per second) of the system. 64 65DAMON_STAT reads observed access events on the current DAMON results snapshot 66and converts it to memory bandwidth consumption estimation in bytes per second. 67The resulting metric is exposed to user via this read-only parameter. Because 68DAMON uses sampling, this is only an estimation of the access intensity rather 69than accurate memory bandwidth. 70 71memory_idle_ms_percentiles 72-------------------------- 73 74Per-byte idle time (milliseconds) percentiles of the system. 75 76DAMON_STAT calculates how long each byte of the memory was not accessed until 77now (idle time), based on the current DAMON results snapshot. For regions 78having access frequency (nr_accesses) larger than zero, how long the current 79access frequency level was kept multiplied by ``-1`` becomes the idlee time of 80every byte of the region. If a region has zero access frequency (nr_accesses), 81how long the region was keeping the zero access frequency (age) becomes the 82idle time of every byte of the region. Then, DAMON_STAT exposes the 83percentiles of the idle time values via this read-only parameter. Reading the 84parameter returns 101 idle time values in milliseconds, separated by comma. 85Each value represents 0-th, 1st, 2nd, 3rd, ..., 99th and 100th percentile idle 86times. 87