Debian Codegraph @

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

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===============
4 Getting Started
5 ===============
6
7 This document briefly describes how you can use DAMON by demonstrating its
8 default user space tool. Please note that this document describes only a part
9 of its features for brevity. Please refer to the usage `doc
10 <https://github.com/damonitor/damo/blob/next/USAGE.md>`_ of the tool for more
11 details.
12
13
14 Prerequisites
15 =============
16
17 Kernel
18 ------
19
20 You should first ensure your system is running on a kernel built with
21 ``CONFIG_DAMON_*=y``.
22
23
24 User Space Tool
25 ---------------
26
27 For the demonstration, we will use the default user space tool for DAMON,
28 called DAMON Operator (DAMO). It is available at
29 https://github.com/damonitor/damo. The examples below assume that ``damo`` is on
30 your ``$PATH``. It's not mandatory, though.
31
32 Because DAMO is using the sysfs interface (refer to :doc:`usage` for the
33 detail) of DAMON, you should ensure :doc:`sysfs </filesystems/sysfs>` is
34 mounted.
35
36
37 Snapshot Data Access Patterns
38 =============================
39
40 The commands below show the memory access pattern of a program at the moment of
41 the execution. ::
42
43 $ git clone https://github.com/sjp38/masim; cd masim; make
44 $ sudo damo start "./masim ./configs/stairs.cfg --quiet"
45 $ sudo damo report access
46 heatmap: 641111111000000000000000000000000000000000000000000000[...]33333333333333335557984444[...]7
47 # min/max temperatures: -1,840,000,000, 370,010,000, column size: 3.925 MiB
48 0 addr 86.182 TiB size 8.000 KiB access 0 % age 14.900 s
49 1 addr 86.182 TiB size 8.000 KiB access 60 % age 0 ns
50 2 addr 86.182 TiB size 3.422 MiB access 0 % age 4.100 s
51 3 addr 86.182 TiB size 2.004 MiB access 95 % age 2.200 s
52 4 addr 86.182 TiB size 29.688 MiB access 0 % age 14.100 s
53 5 addr 86.182 TiB size 29.516 MiB access 0 % age 16.700 s
54 6 addr 86.182 TiB size 29.633 MiB access 0 % age 17.900 s
55 7 addr 86.182 TiB size 117.652 MiB access 0 % age 18.400 s
56 8 addr 126.990 TiB size 62.332 MiB access 0 % age 9.500 s
57 9 addr 126.990 TiB size 13.980 MiB access 0 % age 5.200 s
58 10 addr 126.990 TiB size 9.539 MiB access 100 % age 3.700 s
59 11 addr 126.990 TiB size 16.098 MiB access 0 % age 6.400 s
60 12 addr 127.987 TiB size 132.000 KiB access 0 % age 2.900 s
61 total size: 314.008 MiB
62 $ sudo damo stop
63
64 The first command of the above example downloads and builds an artificial
65 memory access generator program called ``masim``. The second command asks DAMO
66 to start the program via the given command and make DAMON monitors the newly
67 started process. The third command retrieves the current snapshot of the
68 monitored access pattern of the process from DAMON and shows the pattern in a
69 human readable format.
70
71 The first line of the output shows the relative access temperature (hotness) of
72 the regions in a single row hetmap format. Each column on the heatmap
73 represents regions of same size on the monitored virtual address space. The
74 position of the colun on the row and the number on the column represents the
75 relative location and access temperature of the region. ``[...]`` means
76 unmapped huge regions on the virtual address spaces. The second line shows
77 additional information for better understanding the heatmap.
78
79 Each line of the output from the third line shows which virtual address range
80 (``addr XX size XX``) of the process is how frequently (``access XX %``)
81 accessed for how long time (``age XX``). For example, the evelenth region of
82 ~9.5 MiB size is being most frequently accessed for last 3.7 seconds. Finally,
83 the fourth command stops DAMON.
84
85 Note that DAMON can monitor not only virtual address spaces but multiple types
86 of address spaces including the physical address space.
87
88
89 Recording Data Access Patterns
90 ==============================
91
92 The commands below record the memory access patterns of a program and save the
93 monitoring results to a file. ::
94
95 $ ./masim ./configs/zigzag.cfg &
96 $ sudo damo record -o damon.data $(pidof masim)
97
98 The line of the commands run the artificial memory access
99 generator program again. The generator will repeatedly
100 access two 100 MiB sized memory regions one by one. You can substitute this
101 with your real workload. The last line asks ``damo`` to record the access
102 pattern in the ``damon.data`` file.
103
104
105 Visualizing Recorded Patterns
106 =============================
107
108 You can visualize the pattern in a heatmap, showing which memory region
109 (x-axis) got accessed when (y-axis) and how frequently (number).::
110
111 $ sudo damo report heatmap
112 22222222222222222222222222222222222222211111111111111111111111111111111111111100
113 44444444444444444444444444444444444444434444444444444444444444444444444444443200
114 44444444444444444444444444444444444444433444444444444444444444444444444444444200
115 33333333333333333333333333333333333333344555555555555555555555555555555555555200
116 33333333333333333333333333333333333344444444444444444444444444444444444444444200
117 22222222222222222222222222222222222223355555555555555555555555555555555555555200
118 00000000000000000000000000000000000000288888888888888888888888888888888888888400
119 00000000000000000000000000000000000000288888888888888888888888888888888888888400
120 33333333333333333333333333333333333333355555555555555555555555555555555555555200
121 88888888888888888888888888888888888888600000000000000000000000000000000000000000
122 88888888888888888888888888888888888888600000000000000000000000000000000000000000
123 33333333333333333333333333333333333333444444444444444444444444444444444444443200
124 00000000000000000000000000000000000000288888888888888888888888888888888888888400
125 [...]
126 # access_frequency: 0 1 2 3 4 5 6 7 8 9
127 # x-axis: space (139728247021568-139728453431248: 196.848 MiB)
128 # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s)
129 # resolution: 80x40 (2.461 MiB and 1.758 s for each character)
130
131 You can also visualize the distribution of the working set size, sorted by the
132 size.::
133
134 $ sudo damo report wss --range 0 101 10
135 # <percentile> <wss>
136 # target_id 18446632103789443072
137 # avr: 107.708 MiB
138 0 0 B | |
139 10 95.328 MiB |**************************** |
140 20 95.332 MiB |**************************** |
141 30 95.340 MiB |**************************** |
142 40 95.387 MiB |**************************** |
143 50 95.387 MiB |**************************** |
144 60 95.398 MiB |**************************** |
145 70 95.398 MiB |**************************** |
146 80 95.504 MiB |**************************** |
147 90 190.703 MiB |********************************************************* |
148 100 196.875 MiB |***********************************************************|
149
150 Using ``--sortby`` option with the above command, you can show how the working
151 set size has chronologically changed.::
152
153 $ sudo damo report wss --range 0 101 10 --sortby time
154 # <percentile> <wss>
155 # target_id 18446632103789443072
156 # avr: 107.708 MiB
157 0 3.051 MiB | |
158 10 190.703 MiB |***********************************************************|
159 20 95.336 MiB |***************************** |
160 30 95.328 MiB |***************************** |
161 40 95.387 MiB |***************************** |
162 50 95.332 MiB |***************************** |
163 60 95.320 MiB |***************************** |
164 70 95.398 MiB |***************************** |
165 80 95.398 MiB |***************************** |
166 90 95.340 MiB |***************************** |
167 100 95.398 MiB |***************************** |
168
169
170 Data Access Pattern Aware Memory Management
171 ===========================================
172
173 Below command makes every memory region of size >=4K that has not accessed for
174 >=60 seconds in your workload to be swapped out. ::
175
176 $ sudo damo start --damos_access_rate 0 0 --damos_sz_region 4K max \
177 --damos_age 60s max --damos_action pageout \
178 --target_pid <pid of your workload>