| 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> |