166 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===============4Getting Started5===============6 7This document briefly describes how you can use DAMON by demonstrating its8default user space tool. Please note that this document describes only a part9of its features for brevity. Please refer to the usage `doc10<https://github.com/damonitor/damo/blob/next/USAGE.md>`_ of the tool for more11details.12 13 14Prerequisites15=============16 17Kernel18------19 20You should first ensure your system is running on a kernel built with21``CONFIG_DAMON_*=y``.22 23 24User Space Tool25---------------26 27For the demonstration, we will use the default user space tool for DAMON,28called DAMON Operator (DAMO). It is available at29https://github.com/damonitor/damo. The examples below assume that ``damo`` is on30your ``$PATH``. It's not mandatory, though.31 32Because DAMO is using the sysfs interface (refer to :doc:`usage` for the33detail) of DAMON, you should ensure :doc:`sysfs </filesystems/sysfs>` is34mounted.35 36 37Snapshot Data Access Patterns38=============================39 40The commands below show the memory access pattern of a program at the moment of41the execution. ::42 43 $ git clone https://github.com/sjp38/masim; cd masim; make44 $ sudo damo start "./masim ./configs/stairs.cfg --quiet"45 $ sudo ./damo show46 0 addr [85.541 TiB , 85.541 TiB ) (57.707 MiB ) access 0 % age 10.400 s47 1 addr [85.541 TiB , 85.542 TiB ) (413.285 MiB) access 0 % age 11.400 s48 2 addr [127.649 TiB , 127.649 TiB) (57.500 MiB ) access 0 % age 1.600 s49 3 addr [127.649 TiB , 127.649 TiB) (32.500 MiB ) access 0 % age 500 ms50 4 addr [127.649 TiB , 127.649 TiB) (9.535 MiB ) access 100 % age 300 ms51 5 addr [127.649 TiB , 127.649 TiB) (8.000 KiB ) access 60 % age 0 ns52 6 addr [127.649 TiB , 127.649 TiB) (6.926 MiB ) access 0 % age 1 s53 7 addr [127.998 TiB , 127.998 TiB) (120.000 KiB) access 0 % age 11.100 s54 8 addr [127.998 TiB , 127.998 TiB) (8.000 KiB ) access 40 % age 100 ms55 9 addr [127.998 TiB , 127.998 TiB) (4.000 KiB ) access 0 % age 11 s56 total size: 577.590 MiB57 $ sudo ./damo stop58 59The first command of the above example downloads and builds an artificial60memory access generator program called ``masim``. The second command asks DAMO61to execute the artificial generator process start via the given command and62make DAMON monitors the generator process. The third command retrieves the63current snapshot of the monitored access pattern of the process from DAMON and64shows the pattern in a human readable format.65 66Each line of the output shows which virtual address range (``addr [XX, XX)``)67of the process is how frequently (``access XX %``) accessed for how long time68(``age XX``). For example, the fifth region of ~9 MiB size is being most69frequently accessed for last 300 milliseconds. Finally, the fourth command70stops DAMON.71 72Note that DAMON can monitor not only virtual address spaces but multiple types73of address spaces including the physical address space.74 75 76Recording Data Access Patterns77==============================78 79The commands below record the memory access patterns of a program and save the80monitoring results to a file. ::81 82 $ ./masim ./configs/zigzag.cfg &83 $ sudo damo record -o damon.data $(pidof masim)84 85The line of the commands run the artificial memory access86generator program again. The generator will repeatedly87access two 100 MiB sized memory regions one by one. You can substitute this88with your real workload. The last line asks ``damo`` to record the access89pattern in the ``damon.data`` file.90 91 92Visualizing Recorded Patterns93=============================94 95You can visualize the pattern in a heatmap, showing which memory region96(x-axis) got accessed when (y-axis) and how frequently (number).::97 98 $ sudo damo report heats --heatmap stdout99 22222222222222222222222222222222222222211111111111111111111111111111111111111100100 44444444444444444444444444444444444444434444444444444444444444444444444444443200101 44444444444444444444444444444444444444433444444444444444444444444444444444444200102 33333333333333333333333333333333333333344555555555555555555555555555555555555200103 33333333333333333333333333333333333344444444444444444444444444444444444444444200104 22222222222222222222222222222222222223355555555555555555555555555555555555555200105 00000000000000000000000000000000000000288888888888888888888888888888888888888400106 00000000000000000000000000000000000000288888888888888888888888888888888888888400107 33333333333333333333333333333333333333355555555555555555555555555555555555555200108 88888888888888888888888888888888888888600000000000000000000000000000000000000000109 88888888888888888888888888888888888888600000000000000000000000000000000000000000110 33333333333333333333333333333333333333444444444444444444444444444444444444443200111 00000000000000000000000000000000000000288888888888888888888888888888888888888400112 [...]113 # access_frequency: 0 1 2 3 4 5 6 7 8 9114 # x-axis: space (139728247021568-139728453431248: 196.848 MiB)115 # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s)116 # resolution: 80x40 (2.461 MiB and 1.758 s for each character)117 118You can also visualize the distribution of the working set size, sorted by the119size.::120 121 $ sudo damo report wss --range 0 101 10122 # <percentile> <wss>123 # target_id 18446632103789443072124 # avr: 107.708 MiB125 0 0 B | |126 10 95.328 MiB |**************************** |127 20 95.332 MiB |**************************** |128 30 95.340 MiB |**************************** |129 40 95.387 MiB |**************************** |130 50 95.387 MiB |**************************** |131 60 95.398 MiB |**************************** |132 70 95.398 MiB |**************************** |133 80 95.504 MiB |**************************** |134 90 190.703 MiB |********************************************************* |135 100 196.875 MiB |***********************************************************|136 137Using ``--sortby`` option with the above command, you can show how the working138set size has chronologically changed.::139 140 $ sudo damo report wss --range 0 101 10 --sortby time141 # <percentile> <wss>142 # target_id 18446632103789443072143 # avr: 107.708 MiB144 0 3.051 MiB | |145 10 190.703 MiB |***********************************************************|146 20 95.336 MiB |***************************** |147 30 95.328 MiB |***************************** |148 40 95.387 MiB |***************************** |149 50 95.332 MiB |***************************** |150 60 95.320 MiB |***************************** |151 70 95.398 MiB |***************************** |152 80 95.398 MiB |***************************** |153 90 95.340 MiB |***************************** |154 100 95.398 MiB |***************************** |155 156 157Data Access Pattern Aware Memory Management158===========================================159 160Below command makes every memory region of size >=4K that has not accessed for161>=60 seconds in your workload to be swapped out. ::162 163 $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \164 --damos_age 60s max --damos_action pageout \165 <pid of your workload>166