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

   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/awslabs/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/awslabs/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 Recording Data Access Patterns
  38 ==============================
  39
  40 The commands below record the memory access patterns of a program and save the
  41 monitoring results to a file. ::
  42
  43     $ git clone https://github.com/sjp38/masim
  44     $ cd masim; make; ./masim ./configs/zigzag.cfg &
  45     $ sudo damo record -o damon.data $(pidof masim)
  46
  47 The first two lines of the commands download an artificial memory access
  48 generator program and run it in the background.  The generator will repeatedly
  49 access two 100 MiB sized memory regions one by one.  You can substitute this
  50 with your real workload.  The last line asks ``damo`` to record the access
  51 pattern in the ``damon.data`` file.
  52
  53
  54 Visualizing Recorded Patterns
  55 =============================
  56
  57 You can visualize the pattern in a heatmap, showing which memory region
  58 (x-axis) got accessed when (y-axis) and how frequently (number).::
  59
  60     $ sudo damo report heats --heatmap stdout
  61     22222222222222222222222222222222222222211111111111111111111111111111111111111100
  62     44444444444444444444444444444444444444434444444444444444444444444444444444443200
  63     44444444444444444444444444444444444444433444444444444444444444444444444444444200
  64     33333333333333333333333333333333333333344555555555555555555555555555555555555200
  65     33333333333333333333333333333333333344444444444444444444444444444444444444444200
  66     22222222222222222222222222222222222223355555555555555555555555555555555555555200
  67     00000000000000000000000000000000000000288888888888888888888888888888888888888400
  68     00000000000000000000000000000000000000288888888888888888888888888888888888888400
  69     33333333333333333333333333333333333333355555555555555555555555555555555555555200
  70     88888888888888888888888888888888888888600000000000000000000000000000000000000000
  71     88888888888888888888888888888888888888600000000000000000000000000000000000000000
  72     33333333333333333333333333333333333333444444444444444444444444444444444444443200
  73     00000000000000000000000000000000000000288888888888888888888888888888888888888400
  74     [...]
  75     # access_frequency:  0  1  2  3  4  5  6  7  8  9
  76     # x-axis: space (139728247021568-139728453431248: 196.848 MiB)
  77     # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s)
  78     # resolution: 80x40 (2.461 MiB and 1.758 s for each character)
  79
  80 You can also visualize the distribution of the working set size, sorted by the
  81 size.::
  82
  83     $ sudo damo report wss --range 0 101 10
  84     # <percentile> <wss>
  85     # target_id     18446632103789443072
  86     # avr:  107.708 MiB
  87       0             0 B |                                                           |
  88      10      95.328 MiB |****************************                               |
  89      20      95.332 MiB |****************************                               |
  90      30      95.340 MiB |****************************                               |
  91      40      95.387 MiB |****************************                               |
  92      50      95.387 MiB |****************************                               |
  93      60      95.398 MiB |****************************                               |
  94      70      95.398 MiB |****************************                               |
  95      80      95.504 MiB |****************************                               |
  96      90     190.703 MiB |*********************************************************  |
  97     100     196.875 MiB |***********************************************************|
  98
  99 Using ``--sortby`` option with the above command, you can show how the working
 100 set size has chronologically changed.::
 101
 102     $ sudo damo report wss --range 0 101 10 --sortby time
 103     # <percentile> <wss>
 104     # target_id     18446632103789443072
 105     # avr:  107.708 MiB
 106       0       3.051 MiB |                                                           |
 107      10     190.703 MiB |***********************************************************|
 108      20      95.336 MiB |*****************************                              |
 109      30      95.328 MiB |*****************************                              |
 110      40      95.387 MiB |*****************************                              |
 111      50      95.332 MiB |*****************************                              |
 112      60      95.320 MiB |*****************************                              |
 113      70      95.398 MiB |*****************************                              |
 114      80      95.398 MiB |*****************************                              |
 115      90      95.340 MiB |*****************************                              |
 116     100      95.398 MiB |*****************************                              |
 117
 118
 119 Data Access Pattern Aware Memory Management
 120 ===========================================
 121
 122 Below command makes every memory region of size >=4K that has not accessed for
 123 >=60 seconds in your workload to be swapped out. ::
 124
 125     $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \
 126                         --damos_age 60s max --damos_action pageout \
 127                         <pid of your workload>