xref: /linux/Documentation/admin-guide/mm/damon/usage.rst (revision a58f3dcf20ea9e7e968ee8369fd782bbb53dff73)
1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4Detailed Usages
5===============
6
7DAMON provides below interfaces for different users.
8
9- *DAMON user space tool.*
10  `This <https://github.com/damonitor/damo>`_ is for privileged people such as
11  system administrators who want a just-working human-friendly interface.
12  Using this, users can use the DAMON’s major features in a human-friendly way.
13  It may not be highly tuned for special cases, though.  For more detail,
14  please refer to its `usage document
15  <https://github.com/damonitor/damo/blob/next/USAGE.md>`_.
16- *sysfs interface.*
17  :ref:`This <sysfs_interface>` is for privileged user space programmers who
18  want more optimized use of DAMON.  Using this, users can use DAMON’s major
19  features by reading from and writing to special sysfs files.  Therefore,
20  you can write and use your personalized DAMON sysfs wrapper programs that
21  reads/writes the sysfs files instead of you.  The `DAMON user space tool
22  <https://github.com/damonitor/damo>`_ is one example of such programs.
23- *Kernel Space Programming Interface.*
24  :doc:`This </mm/damon/api>` is for kernel space programmers.  Using this,
25  users can utilize every feature of DAMON most flexibly and efficiently by
26  writing kernel space DAMON application programs for you.  You can even extend
27  DAMON for various address spaces.  For detail, please refer to the interface
28  :doc:`document </mm/damon/api>`.
29
30.. _sysfs_interface:
31
32sysfs Interface
33===============
34
35DAMON sysfs interface is built when ``CONFIG_DAMON_SYSFS`` is defined.  It
36creates multiple directories and files under its sysfs directory,
37``<sysfs>/kernel/mm/damon/``.  You can control DAMON by writing to and reading
38from the files under the directory.
39
40For a short example, users can monitor the virtual address space of a given
41workload as below. ::
42
43    # cd /sys/kernel/mm/damon/admin/
44    # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts
45    # echo vaddr > kdamonds/0/contexts/0/operations
46    # echo 1 > kdamonds/0/contexts/0/targets/nr_targets
47    # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target
48    # echo on > kdamonds/0/state
49
50Files Hierarchy
51---------------
52
53The files hierarchy of DAMON sysfs interface is shown below.  In the below
54figure, parents-children relations are represented with indentations, each
55directory is having ``/`` suffix, and files in each directory are separated by
56comma (",").
57
58.. parsed-literal::
59
60    :ref:`/sys/kernel/mm/damon <sysfs_root>`/admin
61    │ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds
62    │ │ :ref:`0 <sysfs_kdamond>`/state,pid
63    │ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts
64    │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations
65    │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
66    │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
67    │ │ │ │ │ │ nr_regions/min,max
68    │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
69    │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
70    │ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions
71    │ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end
72    │ │ │ │ │ │ │ │ ...
73    │ │ │ │ │ │ ...
74    │ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes
75    │ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,target_nid,apply_interval_us
76    │ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/
77    │ │ │ │ │ │ │ │ sz/min,max
78    │ │ │ │ │ │ │ │ nr_accesses/min,max
79    │ │ │ │ │ │ │ │ age/min,max
80    │ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms,effective_bytes
81    │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil
82    │ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals
83    │ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value
84    │ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low
85    │ │ │ │ │ │ │ :ref:`filters <sysfs_filters>`/nr_filters
86    │ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,target_idx,min,max
87    │ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,sz_ops_filter_passed,qt_exceeds
88    │ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes
89    │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age,sz_filter_passed
90    │ │ │ │ │ │ │ │ ...
91    │ │ │ │ │ │ ...
92    │ │ │ │ ...
93    │ │ ...
94
95.. _sysfs_root:
96
97Root
98----
99
100The root of the DAMON sysfs interface is ``<sysfs>/kernel/mm/damon/``, and it
101has one directory named ``admin``.  The directory contains the files for
102privileged user space programs' control of DAMON.  User space tools or daemons
103having the root permission could use this directory.
104
105.. _sysfs_kdamonds:
106
107kdamonds/
108---------
109
110Under the ``admin`` directory, one directory, ``kdamonds``, which has files for
111controlling the kdamonds (refer to
112:ref:`design <damon_design_execution_model_and_data_structures>` for more
113details) exists.  In the beginning, this directory has only one file,
114``nr_kdamonds``.  Writing a number (``N``) to the file creates the number of
115child directories named ``0`` to ``N-1``.  Each directory represents each
116kdamond.
117
118.. _sysfs_kdamond:
119
120kdamonds/<N>/
121-------------
122
123In each kdamond directory, two files (``state`` and ``pid``) and one directory
124(``contexts``) exist.
125
126Reading ``state`` returns ``on`` if the kdamond is currently running, or
127``off`` if it is not running.
128
129Users can write below commands for the kdamond to the ``state`` file.
130
131- ``on``: Start running.
132- ``off``: Stop running.
133- ``commit``: Read the user inputs in the sysfs files except ``state`` file
134  again.
135- ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes'
136  :ref:`quota goals <sysfs_schemes_quota_goals>`.
137- ``update_schemes_stats``: Update the contents of stats files for each
138  DAMON-based operation scheme of the kdamond.  For details of the stats,
139  please refer to :ref:`stats section <sysfs_schemes_stats>`.
140- ``update_schemes_tried_regions``: Update the DAMON-based operation scheme
141  action tried regions directory for each DAMON-based operation scheme of the
142  kdamond.  For details of the DAMON-based operation scheme action tried
143  regions directory, please refer to
144  :ref:`tried_regions section <sysfs_schemes_tried_regions>`.
145- ``update_schemes_tried_bytes``: Update only ``.../tried_regions/total_bytes``
146  files.
147- ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme
148  action tried regions directory for each DAMON-based operation scheme of the
149  kdamond.
150- ``update_schemes_effective_quotas``: Update the contents of
151  ``effective_bytes`` files for each DAMON-based operation scheme of the
152  kdamond.  For more details, refer to :ref:`quotas directory <sysfs_quotas>`.
153
154If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread.
155
156``contexts`` directory contains files for controlling the monitoring contexts
157that this kdamond will execute.
158
159.. _sysfs_contexts:
160
161kdamonds/<N>/contexts/
162----------------------
163
164In the beginning, this directory has only one file, ``nr_contexts``.  Writing a
165number (``N``) to the file creates the number of child directories named as
166``0`` to ``N-1``.  Each directory represents each monitoring context (refer to
167:ref:`design <damon_design_execution_model_and_data_structures>` for more
168details).  At the moment, only one context per kdamond is supported, so only
169``0`` or ``1`` can be written to the file.
170
171.. _sysfs_context:
172
173contexts/<N>/
174-------------
175
176In each context directory, two files (``avail_operations`` and ``operations``)
177and three directories (``monitoring_attrs``, ``targets``, and ``schemes``)
178exist.
179
180DAMON supports multiple types of :ref:`monitoring operations
181<damon_design_configurable_operations_set>`, including those for virtual address
182space and the physical address space.  You can get the list of available
183monitoring operations set on the currently running kernel by reading
184``avail_operations`` file.  Based on the kernel configuration, the file will
185list different available operation sets.  Please refer to the :ref:`design
186<damon_operations_set>` for the list of all available operation sets and their
187brief explanations.
188
189You can set and get what type of monitoring operations DAMON will use for the
190context by writing one of the keywords listed in ``avail_operations`` file and
191reading from the ``operations`` file.
192
193.. _sysfs_monitoring_attrs:
194
195contexts/<N>/monitoring_attrs/
196------------------------------
197
198Files for specifying attributes of the monitoring including required quality
199and efficiency of the monitoring are in ``monitoring_attrs`` directory.
200Specifically, two directories, ``intervals`` and ``nr_regions`` exist in this
201directory.
202
203Under ``intervals`` directory, three files for DAMON's sampling interval
204(``sample_us``), aggregation interval (``aggr_us``), and update interval
205(``update_us``) exist.  You can set and get the values in micro-seconds by
206writing to and reading from the files.
207
208Under ``nr_regions`` directory, two files for the lower-bound and upper-bound
209of DAMON's monitoring regions (``min`` and ``max``, respectively), which
210controls the monitoring overhead, exist.  You can set and get the values by
211writing to and rading from the files.
212
213For more details about the intervals and monitoring regions range, please refer
214to the Design document (:doc:`/mm/damon/design`).
215
216.. _sysfs_targets:
217
218contexts/<N>/targets/
219---------------------
220
221In the beginning, this directory has only one file, ``nr_targets``.  Writing a
222number (``N``) to the file creates the number of child directories named ``0``
223to ``N-1``.  Each directory represents each monitoring target.
224
225.. _sysfs_target:
226
227targets/<N>/
228------------
229
230In each target directory, one file (``pid_target``) and one directory
231(``regions``) exist.
232
233If you wrote ``vaddr`` to the ``contexts/<N>/operations``, each target should
234be a process.  You can specify the process to DAMON by writing the pid of the
235process to the ``pid_target`` file.
236
237.. _sysfs_regions:
238
239targets/<N>/regions
240-------------------
241
242In case of ``fvaddr`` or ``paddr`` monitoring operations sets, users are
243required to set the monitoring target address ranges.  In case of ``vaddr``
244operations set, it is not mandatory, but users can optionally set the initial
245monitoring region to specific address ranges.  Please refer to the :ref:`design
246<damon_design_vaddr_target_regions_construction>` for more details.
247
248For such cases, users can explicitly set the initial monitoring target regions
249as they want, by writing proper values to the files under this directory.
250
251In the beginning, this directory has only one file, ``nr_regions``.  Writing a
252number (``N``) to the file creates the number of child directories named ``0``
253to ``N-1``.  Each directory represents each initial monitoring target region.
254
255.. _sysfs_region:
256
257regions/<N>/
258------------
259
260In each region directory, you will find two files (``start`` and ``end``).  You
261can set and get the start and end addresses of the initial monitoring target
262region by writing to and reading from the files, respectively.
263
264Each region should not overlap with others.  ``end`` of directory ``N`` should
265be equal or smaller than ``start`` of directory ``N+1``.
266
267.. _sysfs_schemes:
268
269contexts/<N>/schemes/
270---------------------
271
272The directory for DAMON-based Operation Schemes (:ref:`DAMOS
273<damon_design_damos>`).  Users can get and set the schemes by reading from and
274writing to files under this directory.
275
276In the beginning, this directory has only one file, ``nr_schemes``.  Writing a
277number (``N``) to the file creates the number of child directories named ``0``
278to ``N-1``.  Each directory represents each DAMON-based operation scheme.
279
280.. _sysfs_scheme:
281
282schemes/<N>/
283------------
284
285In each scheme directory, five directories (``access_pattern``, ``quotas``,
286``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and three files
287(``action``, ``target_nid`` and ``apply_interval``) exist.
288
289The ``action`` file is for setting and getting the scheme's :ref:`action
290<damon_design_damos_action>`.  The keywords that can be written to and read
291from the file and their meaning are same to those of the list on
292:ref:`design doc <damon_design_damos_action>`.
293
294The ``target_nid`` file is for setting the migration target node, which is
295only meaningful when the ``action`` is either ``migrate_hot`` or
296``migrate_cold``.
297
298The ``apply_interval_us`` file is for setting and getting the scheme's
299:ref:`apply_interval <damon_design_damos>` in microseconds.
300
301.. _sysfs_access_pattern:
302
303schemes/<N>/access_pattern/
304---------------------------
305
306The directory for the target access :ref:`pattern
307<damon_design_damos_access_pattern>` of the given DAMON-based operation scheme.
308
309Under the ``access_pattern`` directory, three directories (``sz``,
310``nr_accesses``, and ``age``) each having two files (``min`` and ``max``)
311exist.  You can set and get the access pattern for the given scheme by writing
312to and reading from the ``min`` and ``max`` files under ``sz``,
313``nr_accesses``, and ``age`` directories, respectively.  Note that the ``min``
314and the ``max`` form a closed interval.
315
316.. _sysfs_quotas:
317
318schemes/<N>/quotas/
319-------------------
320
321The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given
322DAMON-based operation scheme.
323
324Under ``quotas`` directory, four files (``ms``, ``bytes``,
325``reset_interval_ms``, ``effective_bytes``) and two directores (``weights`` and
326``goals``) exist.
327
328You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and
329``reset interval`` in milliseconds by writing the values to the three files,
330respectively.  Then, DAMON tries to use only up to ``time quota`` milliseconds
331for applying the ``action`` to memory regions of the ``access_pattern``, and to
332apply the action to only up to ``bytes`` bytes of memory regions within the
333``reset_interval_ms``.  Setting both ``ms`` and ``bytes`` zero disables the
334quota limits unless at least one :ref:`goal <sysfs_schemes_quota_goals>` is
335set.
336
337The time quota is internally transformed to a size quota.  Between the
338transformed size quota and user-specified size quota, smaller one is applied.
339Based on the user-specified :ref:`goal <sysfs_schemes_quota_goals>`, the
340effective size quota is further adjusted.  Reading ``effective_bytes`` returns
341the current effective size quota.  The file is not updated in real time, so
342users should ask DAMON sysfs interface to update the content of the file for
343the stats by writing a special keyword, ``update_schemes_effective_quotas`` to
344the relevant ``kdamonds/<N>/state`` file.
345
346Under ``weights`` directory, three files (``sz_permil``,
347``nr_accesses_permil``, and ``age_permil``) exist.
348You can set the :ref:`prioritization weights
349<damon_design_damos_quotas_prioritization>` for size, access frequency, and age
350in per-thousand unit by writing the values to the three files under the
351``weights`` directory.
352
353.. _sysfs_schemes_quota_goals:
354
355schemes/<N>/quotas/goals/
356-------------------------
357
358The directory for the :ref:`automatic quota tuning goals
359<damon_design_damos_quotas_auto_tuning>` of the given DAMON-based operation
360scheme.
361
362In the beginning, this directory has only one file, ``nr_goals``.  Writing a
363number (``N``) to the file creates the number of child directories named ``0``
364to ``N-1``.  Each directory represents each goal and current achievement.
365Among the multiple feedback, the best one is used.
366
367Each goal directory contains three files, namely ``target_metric``,
368``target_value`` and ``current_value``.  Users can set and get the three
369parameters for the quota auto-tuning goals that specified on the :ref:`design
370doc <damon_design_damos_quotas_auto_tuning>` by writing to and reading from each
371of the files.  Note that users should further write
372``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond
373directory <sysfs_kdamond>` to pass the feedback to DAMON.
374
375.. _sysfs_watermarks:
376
377schemes/<N>/watermarks/
378-----------------------
379
380The directory for the :ref:`watermarks <damon_design_damos_watermarks>` of the
381given DAMON-based operation scheme.
382
383Under the watermarks directory, five files (``metric``, ``interval_us``,
384``high``, ``mid``, and ``low``) for setting the metric, the time interval
385between check of the metric, and the three watermarks exist.  You can set and
386get the five values by writing to the files, respectively.
387
388Keywords and meanings of those that can be written to the ``metric`` file are
389as below.
390
391 - none: Ignore the watermarks
392 - free_mem_rate: System's free memory rate (per thousand)
393
394The ``interval`` should written in microseconds unit.
395
396.. _sysfs_filters:
397
398schemes/<N>/filters/
399--------------------
400
401The directory for the :ref:`filters <damon_design_damos_filters>` of the given
402DAMON-based operation scheme.
403
404In the beginning, this directory has only one file, ``nr_filters``.  Writing a
405number (``N``) to the file creates the number of child directories named ``0``
406to ``N-1``.  Each directory represents each filter.  The filters are evaluated
407in the numeric order.
408
409Each filter directory contains nine files, namely ``type``, ``matching``,
410``allow``, ``memcg_path``, ``addr_start``, ``addr_end``, ``min``, ``max``
411and ``target_idx``.  To ``type`` file, you can write the type of the filter.
412Refer to :ref:`the design doc <damon_design_damos_filters>` for available type
413names and their meanings.
414
415For ``memcg`` type, you can specify the memory cgroup of the interest by
416writing the path of the memory cgroup from the cgroups mount point to
417``memcg_path`` file.  For ``addr`` type, you can specify the start and end
418address of the range (open-ended interval) to ``addr_start`` and ``addr_end``
419files, respectively.  For ``hugepage_size`` type, you can specify the minimum
420and maximum size of the range (closed interval) to ``min`` and ``max`` files,
421respectively.  For ``target`` type, you can specify the index of the target
422between the list of the DAMON context's monitoring targets list to
423``target_idx`` file.
424
425You can write ``Y`` or ``N`` to ``matching`` file to specify whether the filter
426is for memory that matches the ``type``.  You can write ``Y`` or ``N`` to
427``allow`` file to specify if applying the action to the memory that satisfies
428the ``type`` and ``matching`` should be allowed or not.
429
430For example, below restricts a DAMOS action to be applied to only non-anonymous
431pages of all memory cgroups except ``/having_care_already``.::
432
433    # echo 2 > nr_filters
434    # # disallow anonymous pages
435    echo anon > 0/type
436    echo Y > 0/matching
437    echo N > 0/allow
438    # # further filter out all cgroups except one at '/having_care_already'
439    echo memcg > 1/type
440    echo /having_care_already > 1/memcg_path
441    echo Y > 1/matching
442    echo N > 1/allow
443
444Refer to the :ref:`DAMOS filters design documentation
445<damon_design_damos_filters>` for more details including how multiple filters
446of different ``allow`` works, when each of the filters are supported, and
447differences on stats.
448
449.. _sysfs_schemes_stats:
450
451schemes/<N>/stats/
452------------------
453
454DAMON counts statistics for each scheme.  This statistics can be used for
455online analysis or tuning of the schemes.  Refer to :ref:`design doc
456<damon_design_damos_stat>` for more details about the stats.
457
458The statistics can be retrieved by reading the files under ``stats`` directory
459(``nr_tried``, ``sz_tried``, ``nr_applied``, ``sz_applied``,
460``sz_ops_filter_passed``, and ``qt_exceeds``), respectively.  The files are not
461updated in real time, so you should ask DAMON sysfs interface to update the
462content of the files for the stats by writing a special keyword,
463``update_schemes_stats`` to the relevant ``kdamonds/<N>/state`` file.
464
465.. _sysfs_schemes_tried_regions:
466
467schemes/<N>/tried_regions/
468--------------------------
469
470This directory initially has one file, ``total_bytes``.
471
472When a special keyword, ``update_schemes_tried_regions``, is written to the
473relevant ``kdamonds/<N>/state`` file, DAMON updates the ``total_bytes`` file so
474that reading it returns the total size of the scheme tried regions, and creates
475directories named integer starting from ``0`` under this directory.  Each
476directory contains files exposing detailed information about each of the memory
477region that the corresponding scheme's ``action`` has tried to be applied under
478this directory, during next :ref:`apply interval <damon_design_damos>` of the
479corresponding scheme.  The information includes address range, ``nr_accesses``,
480and ``age`` of the region.
481
482Writing ``update_schemes_tried_bytes`` to the relevant ``kdamonds/<N>/state``
483file will only update the ``total_bytes`` file, and will not create the
484subdirectories.
485
486The directories will be removed when another special keyword,
487``clear_schemes_tried_regions``, is written to the relevant
488``kdamonds/<N>/state`` file.
489
490The expected usage of this directory is investigations of schemes' behaviors,
491and query-like efficient data access monitoring results retrievals.  For the
492latter use case, in particular, users can set the ``action`` as ``stat`` and
493set the ``access pattern`` as their interested pattern that they want to query.
494
495.. _sysfs_schemes_tried_region:
496
497tried_regions/<N>/
498------------------
499
500In each region directory, you will find five files (``start``, ``end``,
501``nr_accesses``, ``age``, and ``sz_filter_passed``).  Reading the files will
502show the properties of the region that corresponding DAMON-based operation
503scheme ``action`` has tried to be applied.
504
505Example
506~~~~~~~
507
508Below commands applies a scheme saying "If a memory region of size in [4KiB,
5098KiB] is showing accesses per aggregate interval in [0, 5] for aggregate
510interval in [10, 20], page out the region.  For the paging out, use only up to
51110ms per second, and also don't page out more than 1GiB per second.  Under the
512limitation, page out memory regions having longer age first.  Also, check the
513free memory rate of the system every 5 seconds, start the monitoring and paging
514out when the free memory rate becomes lower than 50%, but stop it if the free
515memory rate becomes larger than 60%, or lower than 30%". ::
516
517    # cd <sysfs>/kernel/mm/damon/admin
518    # # populate directories
519    # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts;
520    # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes
521    # cd kdamonds/0/contexts/0/schemes/0
522    # # set the basic access pattern and the action
523    # echo 4096 > access_pattern/sz/min
524    # echo 8192 > access_pattern/sz/max
525    # echo 0 > access_pattern/nr_accesses/min
526    # echo 5 > access_pattern/nr_accesses/max
527    # echo 10 > access_pattern/age/min
528    # echo 20 > access_pattern/age/max
529    # echo pageout > action
530    # # set quotas
531    # echo 10 > quotas/ms
532    # echo $((1024*1024*1024)) > quotas/bytes
533    # echo 1000 > quotas/reset_interval_ms
534    # # set watermark
535    # echo free_mem_rate > watermarks/metric
536    # echo 5000000 > watermarks/interval_us
537    # echo 600 > watermarks/high
538    # echo 500 > watermarks/mid
539    # echo 300 > watermarks/low
540
541Please note that it's highly recommended to use user space tools like `damo
542<https://github.com/damonitor/damo>`_ rather than manually reading and writing
543the files as above.  Above is only for an example.
544
545.. _tracepoint:
546
547Tracepoints for Monitoring Results
548==================================
549
550Users can get the monitoring results via the :ref:`tried_regions
551<sysfs_schemes_tried_regions>`.  The interface is useful for getting a
552snapshot, but it could be inefficient for fully recording all the monitoring
553results.  For the purpose, two trace points, namely ``damon:damon_aggregated``
554and ``damon:damos_before_apply``, are provided.  ``damon:damon_aggregated``
555provides the whole monitoring results, while ``damon:damos_before_apply``
556provides the monitoring results for regions that each DAMON-based Operation
557Scheme (:ref:`DAMOS <damon_design_damos>`) is gonna be applied.  Hence,
558``damon:damos_before_apply`` is more useful for recording internal behavior of
559DAMOS, or DAMOS target access
560:ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient
561monitoring results recording.
562
563While the monitoring is turned on, you could record the tracepoint events and
564show results using tracepoint supporting tools like ``perf``.  For example::
565
566    # echo on > kdamonds/0/state
567    # perf record -e damon:damon_aggregated &
568    # sleep 5
569    # kill 9 $(pidof perf)
570    # echo off > kdamonds/0/state
571    # perf script
572    kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864
573    [...]
574
575Each line of the perf script output represents each monitoring region.  The
576first five fields are as usual other tracepoint outputs.  The sixth field
577(``target_id=X``) shows the ide of the monitoring target of the region.  The
578seventh field (``nr_regions=X``) shows the total number of monitoring regions
579for the target.  The eighth field (``X-Y:``) shows the start (``X``) and end
580(``Y``) addresses of the region in bytes.  The ninth field (``X``) shows the
581``nr_accesses`` of the region (refer to
582:ref:`design <damon_design_region_based_sampling>` for more details of the
583counter).  Finally the tenth field (``X``) shows the ``age`` of the region
584(refer to :ref:`design <damon_design_age_tracking>` for more details of the
585counter).
586
587If the event was ``damon:damos_beofre_apply``, the ``perf script`` output would
588be somewhat like below::
589
590    kdamond.0 47293 [000] 80801.060214: damon:damos_before_apply: ctx_idx=0 scheme_idx=0 target_idx=0 nr_regions=11 121932607488-135128711168: 0 136
591    [...]
592
593Each line of the output represents each monitoring region that each DAMON-based
594Operation Scheme was about to be applied at the traced time.  The first five
595fields are as usual.  It shows the index of the DAMON context (``ctx_idx=X``)
596of the scheme in the list of the contexts of the context's kdamond, the index
597of the scheme (``scheme_idx=X``) in the list of the schemes of the context, in
598addition to the output of ``damon_aggregated`` tracepoint.
599