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 show 46 0 addr [85.541 TiB , 85.541 TiB ) (57.707 MiB ) access 0 % age 10.400 s 47 1 addr [85.541 TiB , 85.542 TiB ) (413.285 MiB) access 0 % age 11.400 s 48 2 addr [127.649 TiB , 127.649 TiB) (57.500 MiB ) access 0 % age 1.600 s 49 3 addr [127.649 TiB , 127.649 TiB) (32.500 MiB ) access 0 % age 500 ms 50 4 addr [127.649 TiB , 127.649 TiB) (9.535 MiB ) access 100 % age 300 ms 51 5 addr [127.649 TiB , 127.649 TiB) (8.000 KiB ) access 60 % age 0 ns 52 6 addr [127.649 TiB , 127.649 TiB) (6.926 MiB ) access 0 % age 1 s 53 7 addr [127.998 TiB , 127.998 TiB) (120.000 KiB) access 0 % age 11.100 s 54 8 addr [127.998 TiB , 127.998 TiB) (8.000 KiB ) access 40 % age 100 ms 55 9 addr [127.998 TiB , 127.998 TiB) (4.000 KiB ) access 0 % age 11 s 56 total size: 577.590 MiB 57 $ sudo ./damo stop 58 59 The first command of the above example downloads and builds an artificial 60 memory access generator program called ``masim``. The second command asks DAMO 61 to execute the artificial generator process start via the given command and 62 make DAMON monitors the generator process. The third command retrieves the 63 current snapshot of the monitored access pattern of the process from DAMON and 64 shows the pattern in a human readable format. 65 66 Each line of the output shows which virtual address range (``addr [XX, XX)``) 67 of the process is how frequently (``access XX %``) accessed for how long time 68 (``age XX``). For example, the fifth region of ~9 MiB size is being most 69 frequently accessed for last 300 milliseconds. Finally, the fourth command 70 stops DAMON. 71 72 Note that DAMON can monitor not only virtual address spaces but multiple types 73 of address spaces including the physical address space. 74 75 76 Recording Data Access Patterns 77 ============================== 78 79 The commands below record the memory access patterns of a program and save the 80 monitoring results to a file. :: 81 82 $ ./masim ./configs/zigzag.cfg & 83 $ sudo damo record -o damon.data $(pidof masim) 84 85 The line of the commands run the artificial memory access 86 generator program again. The generator will repeatedly 87 access two 100 MiB sized memory regions one by one. You can substitute this 88 with your real workload. The last line asks ``damo`` to record the access 89 pattern in the ``damon.data`` file. 90 91 92 Visualizing Recorded Patterns 93 ============================= 94 95 You can visualize the pattern in a heatmap, showing which memory region 96 (x-axis) got accessed when (y-axis) and how frequently (number).:: 97 98 $ sudo damo report heats --heatmap stdout 99 22222222222222222222222222222222222222211111111111111111111111111111111111111100 100 44444444444444444444444444444444444444434444444444444444444444444444444444443200 101 44444444444444444444444444444444444444433444444444444444444444444444444444444200 102 33333333333333333333333333333333333333344555555555555555555555555555555555555200 103 33333333333333333333333333333333333344444444444444444444444444444444444444444200 104 22222222222222222222222222222222222223355555555555555555555555555555555555555200 105 00000000000000000000000000000000000000288888888888888888888888888888888888888400 106 00000000000000000000000000000000000000288888888888888888888888888888888888888400 107 33333333333333333333333333333333333333355555555555555555555555555555555555555200 108 88888888888888888888888888888888888888600000000000000000000000000000000000000000 109 88888888888888888888888888888888888888600000000000000000000000000000000000000000 110 33333333333333333333333333333333333333444444444444444444444444444444444444443200 111 00000000000000000000000000000000000000288888888888888888888888888888888888888400 112 [...] 113 # access_frequency: 0 1 2 3 4 5 6 7 8 9 114 # 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 118 You can also visualize the distribution of the working set size, sorted by the 119 size.:: 120 121 $ sudo damo report wss --range 0 101 10 122 # <percentile> <wss> 123 # target_id 18446632103789443072 124 # avr: 107.708 MiB 125 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 137 Using ``--sortby`` option with the above command, you can show how the working 138 set size has chronologically changed.:: 139 140 $ sudo damo report wss --range 0 101 10 --sortby time 141 # <percentile> <wss> 142 # target_id 18446632103789443072 143 # avr: 107.708 MiB 144 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 157 Data Access Pattern Aware Memory Management 158 =========================================== 159 160 Below command makes every memory region of size >=4K that has not accessed for 161 >=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>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.