Debian Codegraph @

Documentation/admin-guide/mm/damon/stat.rst

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