Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Docs/admin-guide/mm/damon: add DAMON_STAT usage document
Document DAMON_STAT usage and add a link to it on DAMON admin-guide page.
Link: https://lkml.kernel.org/r/20250604183127.13968-5-sj@kernel.org
Signed-off-by: SeongJae Park <sj@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
authored by
SeongJae Park
and committed by
Andrew Morton
7c33c6c4
e5d2585d
+70
+1
Documentation/admin-guide/mm/damon/index.rst
+1
Documentation/admin-guide/mm/damon/index.rst
+69
Documentation/admin-guide/mm/damon/stat.rst
+69
Documentation/admin-guide/mm/damon/stat.rst
···
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
+
Monitoring Accuracy and Overhead
14
+
================================
15
+
16
+
DAMON_STAT uses monitoring intervals :ref:`auto-tuning
17
+
<damon_design_monitoring_intervals_autotuning>` to make its accuracy high and
18
+
overhead minimum. It auto-tunes the intervals aiming 4 % of observable access
19
+
events to be captured in each snapshot, while limiting the resulting sampling
20
+
events to be 5 milliseconds in minimum and 10 seconds in maximum. On a few
21
+
production server systems, it resulted in consuming only 0.x % single CPU time,
22
+
while capturing reasonable quality of access patterns.
23
+
24
+
Interface: Module Parameters
25
+
============================
26
+
27
+
To use this feature, you should first ensure your system is running on a kernel
28
+
that is built with ``CONFIG_DAMON_STAT=y``. The feature can be enabled by
29
+
default at build time, by setting ``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` true.
30
+
31
+
To let sysadmins enable or disable it at boot and/or runtime, and read the
32
+
monitoring results, DAMON_STAT provides module parameters. Following
33
+
sections are descriptions of the parameters.
34
+
35
+
enabled
36
+
-------
37
+
38
+
Enable or disable DAMON_STAT.
39
+
40
+
You can enable DAMON_STAT by setting the value of this parameter as ``Y``.
41
+
Setting it as ``N`` disables DAMON_STAT. The default value is set by
42
+
``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` build config option.
43
+
44
+
estimated_memory_bandwidth
45
+
--------------------------
46
+
47
+
Estimated memory bandwidth consumption (bytes per second) of the system.
48
+
49
+
DAMON_STAT reads observed access events on the current DAMON results snapshot
50
+
and converts it to memory bandwidth consumption estimation in bytes per second.
51
+
The resulting metric is exposed to user via this read-only parameter. Because
52
+
DAMON uses sampling, this is only an estimation of the access intensity rather
53
+
than accurate memory bandwidth.
54
+
55
+
memory_idle_ms_percentiles
56
+
--------------------------
57
+
58
+
Per-byte idle time (milliseconds) percentiles of the system.
59
+
60
+
DAMON_STAT calculates how long each byte of the memory was not accessed until
61
+
now (idle time), based on the current DAMON results snapshot. If DAMON found a
62
+
region of access frequency (nr_accesses) larger than zero, every byte of the
63
+
region gets zero idle time. If a region has zero access frequency
64
+
(nr_accesses), how long the region was keeping the zero access frequency (age)
65
+
becomes the idle time of every byte of the region. Then, DAMON_STAT exposes
66
+
the percentiles of the idle time values via this read-only parameter. Reading
67
+
the parameter returns 101 idle time values in milliseconds, separated by comma.
68
+
Each value represents 0-th, 1st, 2nd, 3rd, ..., 99th and 100th percentile idle
69
+
times.