요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
===============
Detailed Usages
===============
DAMON provides below interfaces for different users.
- *DAMON user space tool.*
`This <https://github.com/damonitor/damo>`_ is for privileged people such as
system administrators who want a just-working human-friendly interface.
Using this, users can use the DAMON’s major features in a human-friendly way.
It may not be highly tuned for special cases, though. For more detail,
please refer to its `usage document
<https://github.com/damonitor/damo/blob/next/USAGE.md>`_.
- *sysfs interface.*
:ref:`This <sysfs_interface>` is for privileged user space programmers who
want more optimized use of DAMON. Using this, users can use DAMON’s major
features by reading from and writing to special sysfs files. Therefore,
you can write and use your personalized DAMON sysfs wrapper programs that
reads/writes the sysfs files instead of you. The `DAMON user space tool
<https://github.com/damonitor/damo>`_ is one example of such programs.
- *Kernel Space Programming Interface.*
:doc:`This </mm/damon/api>` is for kernel space programmers. Using this,
users can utilize every feature of DAMON most flexibly and efficiently by
writing kernel space DAMON application programs for you. You can even extend
DAMON for various address spaces. For detail, please refer to the interface
:doc:`document </mm/damon/api>`.
.. _sysfs_interface:
sysfs Interface
===============
DAMON sysfs interface is built when ``CONFIG_DAMON_SYSFS`` is defined. It
creates multiple directories and files under its sysfs directory,
``<sysfs>/kernel/mm/damon/``. You can control DAMON by writing to and reading
from the files under the directory.
For a short example, users can monitor the virtual address space of a given
workload as below. ::
# cd /sys/kernel/mm/damon/admin/
# echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts
# echo vaddr > kdamonds/0/contexts/0/operations
# echo 1 > kdamonds/0/contexts/0/targets/nr_targets
# echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target
# echo on > kdamonds/0/state
Files Hierarchy
---------------
The files hierarchy of DAMON sysfs interface is shown below. In the below
figure, parents-children relations are represented with indentations, each
directory is having ``/`` suffix, and files in each directory are separated by
comma (",").
.. parsed-literal::
:ref:`/sys/kernel/mm/damon <sysfs_root>`/admin
│ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds
│ │ :ref:`0 <sysfs_kdamond>`/state,pid,refresh_ms
│ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts
│ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations,addr_unit
│ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
│ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
│ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
│ │ │ │ │ │ nr_regions/min,max
│ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
│ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
│ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions
│ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end
│ │ │ │ │ │ │ │ ...
│ │ │ │ │ │ ...
│ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes
│ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,target_nid,apply_interval_us
│ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/
│ │ │ │ │ │ │ │ sz/min,max
│ │ │ │ │ │ │ │ nr_accesses/min,max
│ │ │ │ │ │ │ │ age/min,max
│ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms,effective_bytes
│ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil
│ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals
│ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value,nid
│ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low
│ │ │ │ │ │ │ :ref:`{core_,ops_,}filters <sysfs_filters>`/nr_filters
│ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,target_idx,min,max
│ │ │ │ │ │ │ :ref:`dests <damon_sysfs_dests>`/nr_dests
│ │ │ │ │ │ │ │ 0/id,weight
│ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,sz_ops_filter_passed,qt_exceeds
│ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes
│ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age,sz_filter_passed
│ │ │ │ │ │ │ │ ...
│ │ │ │ │ │ ...
│ │ │ │ ...
│ │ ...
.. _sysfs_root:
Root
----
The root of the DAMON sysfs interface is ``<sysfs>/kernel/mm/damon/``, and it
has one directory named ``admin``. The directory contains the files for
privileged user space programs' control of DAMON. User space tools or daemons
having the root permission could use this directory.
.. _sysfs_kdamonds:
kdamonds/
---------
Under the ``admin`` directory, one directory, ``kdamonds``, which has files for
controlling the kdamonds (refer to
:ref:`design <damon_design_execution_model_and_data_structures>` for more
details) exists. In the beginning, this directory has only one file,
``nr_kdamonds``. Writing a number (``N``) to the file creates the number of
child directories named ``0`` to ``N-1``. Each directory represents each
kdamond.
.. _sysfs_kdamond:
kdamonds/<N>/
-------------
In each kdamond directory, three files (``state``, ``pid`` and ``refresh_ms``)
and one directory (``contexts``) exist.
Reading ``state`` returns ``on`` if the kdamond is currently running, or
``off`` if it is not running.
Users can write below commands for the kdamond to the ``state`` file.
- ``on``: Start running.
- ``off``: Stop running.
- ``commit``: Read the user inputs in the sysfs files except ``state`` file
again.
- ``update_tuned_intervals``: Update the contents of ``sample_us`` and
``aggr_us`` files of the kdamond with the auto-tuning applied ``sampling
interval`` and ``aggregation interval`` for the files. Please refer to
:ref:`intervals_goal section <damon_usage_sysfs_monitoring_intervals_goal>`
for more details.
- ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes'
:ref:`quota goals <sysfs_schemes_quota_goals>`.
- ``update_schemes_stats``: Update the contents of stats files for each
DAMON-based operation scheme of the kdamond. For details of the stats,
please refer to :ref:`stats section <sysfs_schemes_stats>`.
- ``update_schemes_tried_regions``: Update the DAMON-based operation scheme
action tried regions directory for each DAMON-based operation scheme of the
kdamond. For details of the DAMON-based operation scheme action tried
regions directory, please refer to
:ref:`tried_regions section <sysfs_schemes_tried_regions>`.
- ``update_schemes_tried_bytes``: Update only ``.../tried_regions/total_bytes``
files.
- ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme
action tried regions directory for each DAMON-based operation scheme of the
kdamond.
- ``update_schemes_effective_quotas``: Update the contents of
``effective_bytes`` files for each DAMON-based operation scheme of the
kdamond. For more details, refer to :ref:`quotas directory <sysfs_quotas>`.
If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread.
Users can ask the kernel to periodically update files showing auto-tuned
parameters and DAMOS stats instead of manually writing
``update_tuned_intervals`` like keywords to ``state`` file. For this, users
should write the desired update time interval in milliseconds to ``refresh_ms``
file. If the interval is zero, the periodic update is disabled. Reading the
file shows currently set time interval.
``contexts`` directory contains files for controlling the monitoring contexts
that this kdamond will execute.
.. _sysfs_contexts:
kdamonds/<N>/contexts/
----------------------
In the beginning, this directory has only one file, ``nr_contexts``. Writing a
number (``N``) to the file creates the number of child directories named as
``0`` to ``N-1``. Each directory represents each monitoring context (refer to
:ref:`design <damon_design_execution_model_and_data_structures>` for more
details). At the moment, only one context per kdamond is supported, so only
``0`` or ``1`` can be written to the file.
.. _sysfs_context:
contexts/<N>/
-------------
In each context directory, three files (``avail_operations``, ``operations``
and ``addr_unit``) and three directories (``monitoring_attrs``, ``targets``,
and ``schemes``) exist.
DAMON supports multiple types of :ref:`monitoring operations
<damon_design_configurable_operations_set>`, including those for virtual address
space and the physical address space. You can get the list of available
monitoring operations set on the currently running kernel by reading
``avail_operations`` file. Based on the kernel configuration, the file will
list different available operation sets. Please refer to the :ref:`design
<damon_operations_set>` for the list of all available operation sets and their
brief explanations.
You can set and get what type of monitoring operations DAMON will use for the
context by writing one of the keywords listed in ``avail_operations`` file and
reading from the ``operations`` file.
``addr_unit`` file is for setting and getting the :ref:`address unit
<damon_design_addr_unit>` parameter of the operations set.
.. _sysfs_monitoring_attrs:
contexts/<N>/monitoring_attrs/
------------------------------
Files for specifying attributes of the monitoring including required quality
and efficiency of the monitoring are in ``monitoring_attrs`` directory.
Specifically, two directories, ``intervals`` and ``nr_regions`` exist in this
directory.
Under ``intervals`` directory, three files for DAMON's sampling interval
(``sample_us``), aggregation interval (``aggr_us``), and update interval
(``update_us``) exist. You can set and get the values in micro-seconds by
writing to and reading from the files.
Under ``nr_regions`` directory, two files for the lower-bound and upper-bound
of DAMON's monitoring regions (``min`` and ``max``, respectively), which
controls the monitoring overhead, exist. You can set and get the values by
writing to and rading from the files.
For more details about the intervals and monitoring regions range, please refer
to the Design document (:doc:`/mm/damon/design`).
.. _damon_usage_sysfs_monitoring_intervals_goal:
contexts/<N>/monitoring_attrs/intervals/intervals_goal/
-------------------------------------------------------
Under the ``intervals`` directory, one directory for automated tuning of
``sample_us`` and ``aggr_us``, namely ``intervals_goal`` directory also exists.
Under the directory, four files for the auto-tuning control, namely
``access_bp``, ``aggrs``, ``min_sample_us`` and ``max_sample_us`` exist.
Please refer to the :ref:`design document of the feature
<damon_design_monitoring_intervals_autotuning>` for the internal of the tuning
mechanism. Reading and writing the four files under ``intervals_goal``
directory shows and updates the tuning parameters that described in the
:ref:design doc <damon_design_monitoring_intervals_autotuning>` with the same
names. The tuning starts with the user-set ``sample_us`` and ``aggr_us``. The
tuning-applied current values of the two intervals can be read from the
``sample_us`` and ``aggr_us`` files after writing ``update_tuned_intervals`` to
the ``state`` file.
.. _sysfs_targets:
contexts/<N>/targets/
---------------------
In the beginning, this directory has only one file, ``nr_targets``. Writing a
number (``N``) to the file creates the number of child directories named ``0``
to ``N-1``. Each directory represents each monitoring target.
.. _sysfs_target:
targets/<N>/
------------
In each target directory, one file (``pid_target``) and one directory
(``regions``) exist.
If you wrote ``vaddr`` to the ``contexts/<N>/operations``, each target should
be a process. You can specify the process to DAMON by writing the pid of the
process to the ``pid_target`` file.
.. _sysfs_regions:
targets/<N>/regions
-------------------
In case of ``fvaddr`` or ``paddr`` monitoring operations sets, users are
required to set the monitoring target address ranges. In case of ``vaddr``
operations set, it is not mandatory, but users can optionally set the initial
monitoring region to specific address ranges. Please refer to the :ref:`design
<damon_design_vaddr_target_regions_construction>` for more details.
For such cases, users can explicitly set the initial monitoring target regions
as they want, by writing proper values to the files under this directory.
In the beginning, this directory has only one file, ``nr_regions``. Writing a
number (``N``) to the file creates the number of child directories named ``0``
to ``N-1``. Each directory represents each initial monitoring target region.
.. _sysfs_region:
regions/<N>/
------------
In each region directory, you will find two files (``start`` and ``end``). You
can set and get the start and end addresses of the initial monitoring target
region by writing to and reading from the files, respectively.
Each region should not overlap with others. ``end`` of directory ``N`` should
be equal or smaller than ``start`` of directory ``N+1``.
.. _sysfs_schemes:
contexts/<N>/schemes/
---------------------
The directory for DAMON-based Operation Schemes (:ref:`DAMOS
<damon_design_damos>`). Users can get and set the schemes by reading from and
writing to files under this directory.
In the beginning, this directory has only one file, ``nr_schemes``. Writing a
number (``N``) to the file creates the number of child directories named ``0``
to ``N-1``. Each directory represents each DAMON-based operation scheme.
.. _sysfs_scheme:
schemes/<N>/
------------
In each scheme directory, eight directories (``access_pattern``, ``quotas``,
``watermarks``, ``core_filters``, ``ops_filters``, ``filters``, ``dests``,
``stats``, and ``tried_regions``) and three files (``action``, ``target_nid``
and ``apply_interval``) exist.
The ``action`` file is for setting and getting the scheme's :ref:`action
<damon_design_damos_action>`. The keywords that can be written to and read
from the file and their meaning are same to those of the list on
:ref:`design doc <damon_design_damos_action>`.
The ``target_nid`` file is for setting the migration target node, which is
only meaningful when the ``action`` is either ``migrate_hot`` or
``migrate_cold``.
The ``apply_interval_us`` file is for setting and getting the scheme's
:ref:`apply_interval <damon_design_damos>` in microseconds.
.. _sysfs_access_pattern:
schemes/<N>/access_pattern/
---------------------------
The directory for the target access :ref:`pattern
<damon_design_damos_access_pattern>` of the given DAMON-based operation scheme.
Under the ``access_pattern`` directory, three directories (``sz``,
``nr_accesses``, and ``age``) each having two files (``min`` and ``max``)
exist. You can set and get the access pattern for the given scheme by writing
to and reading from the ``min`` and ``max`` files under ``sz``,
``nr_accesses``, and ``age`` directories, respectively. Note that the ``min``
and the ``max`` form a closed interval.
.. _sysfs_quotas:
schemes/<N>/quotas/
-------------------
The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given
DAMON-based operation scheme.
Under ``quotas`` directory, four files (``ms``, ``bytes``,
``reset_interval_ms``, ``effective_bytes``) and two directories (``weights`` and
``goals``) exist.
You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and
``reset interval`` in milliseconds by writing the values to the three files,
respectively. Then, DAMON tries to use only up to ``time quota`` milliseconds
for applying the ``action`` to memory regions of the ``access_pattern``, and to
apply the action to only up to ``bytes`` bytes of memory regions within the
``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the
quota limits unless at least one :ref:`goal <sysfs_schemes_quota_goals>` is
set.
The time quota is internally transformed to a size quota. Between the
transformed size quota and user-specified size quota, smaller one is applied.
Based on the user-specified :ref:`goal <sysfs_schemes_quota_goals>`, the
effective size quota is further adjusted. Reading ``effective_bytes`` returns
the current effective size quota. The file is not updated in real time, so
users should ask DAMON sysfs interface to update the content of the file for
the stats by writing a special keyword, ``update_schemes_effective_quotas`` to
the relevant ``kdamonds/<N>/state`` file.
Under ``weights`` directory, three files (``sz_permil``,
``nr_accesses_permil``, and ``age_permil``) exist.
You can set the :ref:`prioritization weights
<damon_design_damos_quotas_prioritization>` for size, access frequency, and age
in per-thousand unit by writing the values to the three files under the
``weights`` directory.
.. _sysfs_schemes_quota_goals:
schemes/<N>/quotas/goals/
-------------------------
The directory for the :ref:`automatic quota tuning goals
<damon_design_damos_quotas_auto_tuning>` of the given DAMON-based operation
scheme.
In the beginning, this directory has only one file, ``nr_goals``. Writing a
number (``N``) to the file creates the number of child directories named ``0``
to ``N-1``. Each directory represents each goal and current achievement.
Among the multiple feedback, the best one is used.
Each goal directory contains four files, namely ``target_metric``,
``target_value``, ``current_value`` and ``nid``. Users can set and get the
four parameters for the quota auto-tuning goals that specified on the
:ref:`design doc <damon_design_damos_quotas_auto_tuning>` by writing to and
reading from each of the files. Note that users should further write
``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond
directory <sysfs_kdamond>` to pass the feedback to DAMON.
.. _sysfs_watermarks:
schemes/<N>/watermarks/
-----------------------
The directory for the :ref:`watermarks <damon_design_damos_watermarks>` of the
given DAMON-based operation scheme.
Under the watermarks directory, five files (``metric``, ``interval_us``,
``high``, ``mid``, and ``low``) for setting the metric, the time interval
between check of the metric, and the three watermarks exist. You can set and
get the five values by writing to the files, respectively.
Keywords and meanings of those that can be written to the ``metric`` file are
as below.
- none: Ignore the watermarks
- free_mem_rate: System's free memory rate (per thousand)
The ``interval`` should written in microseconds unit.
.. _sysfs_filters:
schemes/<N>/{core\_,ops\_,}filters/
-----------------------------------
Directories for :ref:`filters <damon_design_damos_filters>` of the given
DAMON-based operation scheme.
``core_filters`` and ``ops_filters`` directories are for the filters handled by
the DAMON core layer and operations set layer, respectively. ``filters``
directory can be used for installing filters regardless of their handled
layers. Filters that requested by ``core_filters`` and ``ops_filters`` will be
installed before those of ``filters``. All three directories have same files.
Use of ``filters`` directory can make expecting evaluation orders of given
filters with the files under directory bit confusing. Users are hence
recommended to use ``core_filters`` and ``ops_filters`` directories. The
``filters`` directory could be deprecated in future.
In the beginning, the directory has only one file, ``nr_filters``. Writing a
number (``N``) to the file creates the number of child directories named ``0``
to ``N-1``. Each directory represents each filter. The filters are evaluated
in the numeric order.
Each filter directory contains nine files, namely ``type``, ``matching``,
``allow``, ``memcg_path``, ``addr_start``, ``addr_end``, ``min``, ``max``
and ``target_idx``. To ``type`` file, you can write the type of the filter.
Refer to :ref:`the design doc <damon_design_damos_filters>` for available type
names, their meaning and on what layer those are handled.
For ``memcg`` type, you can specify the memory cgroup of the interest by
writing the path of the memory cgroup from the cgroups mount point to
``memcg_path`` file. For ``addr`` type, you can specify the start and end
address of the range (open-ended interval) to ``addr_start`` and ``addr_end``
files, respectively. For ``hugepage_size`` type, you can specify the minimum
and maximum size of the range (closed interval) to ``min`` and ``max`` files,
respectively. For ``target`` type, you can specify the index of the target
between the list of the DAMON context's monitoring targets list to
``target_idx`` file.
You can write ``Y`` or ``N`` to ``matching`` file to specify whether the filter
is for memory that matches the ``type``. You can write ``Y`` or ``N`` to
``allow`` file to specify if applying the action to the memory that satisfies
the ``type`` and ``matching`` should be allowed or not.
For example, below restricts a DAMOS action to be applied to only non-anonymous
pages of all memory cgroups except ``/having_care_already``.::
# cd ops_filters/0/
# echo 2 > nr_filters
# # disallow anonymous pages
echo anon > 0/type
echo Y > 0/matching
echo N > 0/allow
# # further filter out all cgroups except one at '/having_care_already'
echo memcg > 1/type
echo /having_care_already > 1/memcg_path
echo Y > 1/matching
echo N > 1/allow
Refer to the :ref:`DAMOS filters design documentation
<damon_design_damos_filters>` for more details including how multiple filters
of different ``allow`` works, when each of the filters are supported, and
differences on stats.
.. _damon_sysfs_dests:
schemes/<N>/dests/
------------------
Directory for specifying the destinations of given DAMON-based operation
scheme's action. This directory is ignored if the action of the given scheme
is not supporting multiple destinations. Only ``DAMOS_MIGRATE_{HOT,COLD}``
actions are supporting multiple destinations.
In the beginning, the directory has only one file, ``nr_dests``. Writing a
number (``N``) to the file creates the number of child directories named ``0``
to ``N-1``. Each directory represents each action destination.
Each destination directory contains two files, namely ``id`` and ``weight``.
Users can write and read the identifier of the destination to ``id`` file.
For ``DAMOS_MIGRATE_{HOT,COLD}`` actions, the migrate destination node's node
id should be written to ``id`` file. Users can write and read the weight of
the destination among the given destinations to the ``weight`` file. The
weight can be an arbitrary integer. When DAMOS apply the action to each entity
of the memory region, it will select the destination of the action based on the
relative weights of the destinations.
.. _sysfs_schemes_stats:
schemes/<N>/stats/
------------------
DAMON counts statistics for each scheme. This statistics can be used for
online analysis or tuning of the schemes. Refer to :ref:`design doc
<damon_design_damos_stat>` for more details about the stats.
The statistics can be retrieved by reading the files under ``stats`` directory
(``nr_tried``, ``sz_tried``, ``nr_applied``, ``sz_applied``,
``sz_ops_filter_passed``, and ``qt_exceeds``), respectively. The files are not
updated in real time, so you should ask DAMON sysfs interface to update the
content of the files for the stats by writing a special keyword,
``update_schemes_stats`` to the relevant ``kdamonds/<N>/state`` file.
.. _sysfs_schemes_tried_regions:
schemes/<N>/tried_regions/
--------------------------
This directory initially has one file, ``total_bytes``.
When a special keyword, ``update_schemes_tried_regions``, is written to the
relevant ``kdamonds/<N>/state`` file, DAMON updates the ``total_bytes`` file so
that reading it returns the total size of the scheme tried regions, and creates
directories named integer starting from ``0`` under this directory. Each
directory contains files exposing detailed information about each of the memory
region that the corresponding scheme's ``action`` has tried to be applied under
this directory, during next :ref:`apply interval <damon_design_damos>` of the
corresponding scheme. The information includes address range, ``nr_accesses``,
and ``age`` of the region.
Writing ``update_schemes_tried_bytes`` to the relevant ``kdamonds/<N>/state``
file will only update the ``total_bytes`` file, and will not create the
subdirectories.
The directories will be removed when another special keyword,
``clear_schemes_tried_regions``, is written to the relevant
``kdamonds/<N>/state`` file.
The expected usage of this directory is investigations of schemes' behaviors,
and query-like efficient data access monitoring results retrievals. For the
latter use case, in particular, users can set the ``action`` as ``stat`` and
set the ``access pattern`` as their interested pattern that they want to query.
.. _sysfs_schemes_tried_region:
tried_regions/<N>/
------------------
In each region directory, you will find five files (``start``, ``end``,
``nr_accesses``, ``age``, and ``sz_filter_passed``). Reading the files will
show the properties of the region that corresponding DAMON-based operation
scheme ``action`` has tried to be applied.
Example
~~~~~~~
Below commands applies a scheme saying "If a memory region of size in [4KiB,
8KiB] is showing accesses per aggregate interval in [0, 5] for aggregate
interval in [10, 20], page out the region. For the paging out, use only up to
10ms per second, and also don't page out more than 1GiB per second. Under the
limitation, page out memory regions having longer age first. Also, check the
free memory rate of the system every 5 seconds, start the monitoring and paging
out when the free memory rate becomes lower than 50%, but stop it if the free
memory rate becomes larger than 60%, or lower than 30%". ::
# cd <sysfs>/kernel/mm/damon/admin
# # populate directories
# echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts;
# echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes
# cd kdamonds/0/contexts/0/schemes/0
# # set the basic access pattern and the action
# echo 4096 > access_pattern/sz/min
# echo 8192 > access_pattern/sz/max
# echo 0 > access_pattern/nr_accesses/min
# echo 5 > access_pattern/nr_accesses/max
# echo 10 > access_pattern/age/min
# echo 20 > access_pattern/age/max
# echo pageout > action
# # set quotas
# echo 10 > quotas/ms
# echo $((1024*1024*1024)) > quotas/bytes
# echo 1000 > quotas/reset_interval_ms
# # set watermark
# echo free_mem_rate > watermarks/metric
# echo 5000000 > watermarks/interval_us
# echo 600 > watermarks/high
# echo 500 > watermarks/mid
# echo 300 > watermarks/low
Please note that it's highly recommended to use user space tools like `damo
<https://github.com/damonitor/damo>`_ rather than manually reading and writing
the files as above. Above is only for an example.
.. _tracepoint:
Tracepoints for Monitoring Results
==================================
Users can get the monitoring results via the :ref:`tried_regions
<sysfs_schemes_tried_regions>`. The interface is useful for getting a
snapshot, but it could be inefficient for fully recording all the monitoring
results. For the purpose, two trace points, namely ``damon:damon_aggregated``
and ``damon:damos_before_apply``, are provided. ``damon:damon_aggregated``
provides the whole monitoring results, while ``damon:damos_before_apply``
provides the monitoring results for regions that each DAMON-based Operation
Scheme (:ref:`DAMOS <damon_design_damos>`) is gonna be applied. Hence,
``damon:damos_before_apply`` is more useful for recording internal behavior of
DAMOS, or DAMOS target access
:ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient
monitoring results recording.
While the monitoring is turned on, you could record the tracepoint events and
show results using tracepoint supporting tools like ``perf``. For example::
# echo on > kdamonds/0/state
# perf record -e damon:damon_aggregated &
# sleep 5
# kill 9 $(pidof perf)
# echo off > kdamonds/0/state
# perf script
kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864
[...]
Each line of the perf script output represents each monitoring region. The
first five fields are as usual other tracepoint outputs. The sixth field
(``target_id=X``) shows the ide of the monitoring target of the region. The
seventh field (``nr_regions=X``) shows the total number of monitoring regions
for the target. The eighth field (``X-Y:``) shows the start (``X``) and end
(``Y``) addresses of the region in bytes. The ninth field (``X``) shows the
``nr_accesses`` of the region (refer to
:ref:`design <damon_design_region_based_sampling>` for more details of the
counter). Finally the tenth field (``X``) shows the ``age`` of the region
(refer to :ref:`design <damon_design_age_tracking>` for more details of the
counter).
If the event was ``damon:damos_beofre_apply``, the ``perf script`` output would
be somewhat like below::
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
[...]
Each line of the output represents each monitoring region that each DAMON-based
Operation Scheme was about to be applied at the traced time. The first five
fields are as usual. It shows the index of the DAMON context (``ctx_idx=X``)
of the scheme in the list of the contexts of the context's kdamond, the index
of the scheme (``scheme_idx=X``) in the list of the schemes of the context, in
addition to the output of ``damon_aggregated`` tracepoint.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
DAMON 사용 인터페이스
1-29이 문서는 GPL-2.0 라이선스를 따릅니다. DAMON은 사용자의 역할과 필요한 제어 수준에 맞춰 세 가지 인터페이스를 제공합니다.
DAMON user-space tool인 DAMO는 system administrator처럼 권한을 가진 사용자가 별도 wrapper를 만들지 않고 주요 기능을 사람 친화적인 방식으로 사용하도록 합니다. 일반적인 경우에는 바로 동작하지만 특수한 workload에 고도로 최적화된 interface는 아닐 수 있으므로 자세한 명령은 DAMO usage 문서를 봅니다.
sysfs interface는 DAMON을 더 세밀하게 최적화하려는 privileged user-space programmer를 위한 것입니다. 전용 sysfs 파일을 읽고 쓰는 방식이므로 자신의 DAMON wrapper나 daemon을 만들 수 있으며, DAMO도 이런 프로그램의 한 예입니다.
Kernel Space Programming Interface는 kernel programmer를 위한 가장 유연하고 효율적인 경로입니다. kernel 안에서 DAMON application을 작성해 모든 기능을 활용하고 다른 address space를 위한 operation까지 확장할 수 있습니다. 자세한 API는 `Documentation/mm/damon/api`를 참조합니다.
sysfs interface 시작
30-49`CONFIG_DAMON_SYSFS`가 정의된 kernel은 `<sysfs>/kernel/mm/damon/` 아래에 DAMON 제어 디렉터리와 파일을 만듭니다. 사용자는 이 파일을 읽고 쓰면서 DAMON을 구성하고 실행합니다.
다음 최소 예는 admin root로 이동해 kdamond 하나와 context 하나를 만들고, `vaddr` operation을 선택한 뒤 target 하나의 `pid_target`에 workload PID를 기록하고 monitoring을 켭니다.
# cd /sys/kernel/mm/damon/admin/
# echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts
# echo vaddr > kdamonds/0/contexts/0/operations
# echo 1 > kdamonds/0/contexts/0/targets/nr_targets
# echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target
# echo on > kdamonds/0/state파일 계층
50-97아래 원문 계층에서 들여쓰기는 부모·자식 관계를, `/` suffix는 디렉터리를 뜻하며 한 디렉터리의 여러 파일은 comma로 구분됩니다. source path와 symbol을 잃지 않도록 원문 parsed-literal을 그대로 보존하고, 이어지는 표에서 같은 구조를 기능별로 다시 정리합니다.
:ref:`/sys/kernel/mm/damon <sysfs_root>`/admin
│ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds
│ │ :ref:`0 <sysfs_kdamond>`/state,pid,refresh_ms
│ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts
│ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations,addr_unit
│ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
│ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
│ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
│ │ │ │ │ │ nr_regions/min,max
│ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
│ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
│ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions
│ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end
│ │ │ │ │ │ │ │ ...
│ │ │ │ │ │ ...
│ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes
│ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,target_nid,apply_interval_us
│ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/
│ │ │ │ │ │ │ │ sz/min,max
│ │ │ │ │ │ │ │ nr_accesses/min,max
│ │ │ │ │ │ │ │ age/min,max
│ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms,effective_bytes
│ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil
│ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals
│ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value,nid
│ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low
│ │ │ │ │ │ │ :ref:`{core_,ops_,}filters <sysfs_filters>`/nr_filters
│ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,target_idx,min,max
│ │ │ │ │ │ │ :ref:`dests <damon_sysfs_dests>`/nr_dests
│ │ │ │ │ │ │ │ 0/id,weight
│ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,sz_ops_filter_passed,qt_exceeds
│ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes
│ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age,sz_filter_passed
│ │ │ │ │ │ │ │ ...
│ │ │ │ │ │ ...
│ │ │ │ ...
│ │ ...원문의 깊은 ASCII tree를 root, 실행 단위, monitoring 설정, DAMOS 제어와 결과 계층으로 나눠 읽기 쉽게 재구성했습니다.
root와 kdamonds
98-120DAMON sysfs interface의 root는 `<sysfs>/kernel/mm/damon/`이며 그 아래 `admin` 디렉터리는 root 권한을 가진 user-space tool이나 daemon이 DAMON을 제어할 파일을 담습니다.
`admin/kdamonds/`는 kdamond worker를 관리합니다. 처음에는 `nr_kdamonds`만 있고 여기에 N을 쓰면 `0`부터 `N-1`까지 N개 child directory가 생깁니다. 각 디렉터리가 하나의 kdamond를 나타냅니다.
kdamonds/<N>/
121-173각 kdamond 디렉터리에는 `state`, `pid`, `refresh_ms` 세 파일과 `contexts` 디렉터리가 있습니다. `state`를 읽으면 thread가 실행 중일 때 `on`, 그렇지 않을 때 `off`가 반환됩니다.
| state 명령 | 효과 |
|---|---|
| on | kdamond 실행을 시작합니다. |
| off | kdamond 실행을 중지합니다. |
| commit | `state`를 제외한 sysfs 입력 파일을 다시 읽어 실행 설정에 반영합니다. |
| update_tuned_intervals | 자동 조정된 sampling·aggregation 간격을 `sample_us`, `aggr_us`에 갱신합니다. |
| commit_schemes_quota_goals | DAMOS quota goal과 현재 feedback을 DAMON에 전달합니다. |
| update_schemes_stats | 각 DAMOS의 `stats` 파일을 현재 누적값으로 갱신합니다. |
| update_schemes_tried_regions | `tried_regions`의 `total_bytes`와 상세 region 디렉터리를 갱신합니다. |
| update_schemes_tried_bytes | `tried_regions/total_bytes`만 갱신하고 상세 디렉터리는 만들지 않습니다. |
| clear_schemes_tried_regions | 각 DAMOS의 `tried_regions` 상세 디렉터리를 제거합니다. |
| update_schemes_effective_quotas | 각 DAMOS의 현재 유효 size quota를 `effective_bytes`에 갱신합니다. |
`state`가 `on`일 때 `pid`를 읽으면 kdamond thread의 PID가 나옵니다. `refresh_ms`에는 자동 조정 parameter와 DAMOS stats를 kernel이 주기적으로 파일에 반영할 millisecond 간격을 씁니다. 0이면 주기 갱신을 끄며, 읽으면 현재 간격을 확인할 수 있습니다.
`contexts` 디렉터리는 이 kdamond가 실행할 monitoring context를 구성합니다. `update_tuned_intervals`, `update_schemes_stats`, `update_schemes_tried_regions`, `update_schemes_tried_bytes`, `clear_schemes_tried_regions`, `update_schemes_effective_quotas`처럼 별도 갱신이 필요한 값은 수동 `state` 명령이나 `refresh_ms`를 의식해서 읽어야 합니다.
monitoring context
174-210`contexts/nr_contexts`에 N을 쓰면 `0`부터 `N-1`까지 context 디렉터리를 만듭니다. 현재는 kdamond 하나당 context 하나만 지원하므로 `nr_contexts`에는 0 또는 1만 쓸 수 있습니다.
각 `contexts/<N>/`에는 `avail_operations`, `operations`, `addr_unit` 파일과 `monitoring_attrs`, `targets`, `schemes` 디렉터리가 있습니다. `avail_operations`를 읽으면 현재 kernel configuration에서 사용할 수 있는 virtual 또는 physical address monitoring operation set을 확인할 수 있습니다.
`operations`에는 `avail_operations`에 나온 keyword 하나를 써서 이 context의 operation set을 선택하고, 읽어서 현재 선택을 확인합니다. `addr_unit`은 operation set의 address unit parameter를 설정하고 조회합니다.
monitoring attribute와 interval 자동 조정
211-252`monitoring_attrs`는 monitoring 품질과 효율을 결정합니다. `intervals` 아래의 `sample_us`, `aggr_us`, `update_us`는 각각 sampling, aggregation, region update 간격이며 모두 microseconds 단위입니다.
`nr_regions/min`과 `nr_regions/max`는 monitoring region 수의 하한과 상한입니다. 이 범위는 monitoring overhead와 공간 해상도 사이의 균형을 제어합니다. 자세한 interval과 region range 동작은 `Documentation/mm/damon/design`에 설명되어 있습니다.
| 파일 | 단위 | 의미 |
|---|---|---|
| sample_us | microseconds | DAMON sampling interval |
| aggr_us | microseconds | sampling 결과를 합치는 aggregation interval |
| update_us | microseconds | monitoring region을 갱신하는 interval |
| nr_regions/min | regions | monitoring region 수의 하한 |
| nr_regions/max | regions | monitoring region 수의 상한 |
| access_bp | basis points | 자동 interval 조정의 목표 접근 관측 비율 |
| aggrs | aggregations | 자동 조정 판단에 사용하는 aggregation 수 |
| min_sample_us | microseconds | 자동 조정 sampling interval 하한 |
| max_sample_us | microseconds | 자동 조정 sampling interval 상한 |
`intervals/intervals_goal/`은 `sample_us`와 `aggr_us`를 자동 조정합니다. `access_bp`, `aggrs`, `min_sample_us`, `max_sample_us` 네 파일을 읽고 써서 design 문서의 같은 이름을 가진 tuning parameter를 제어합니다. 조정은 사용자가 쓴 `sample_us`, `aggr_us`에서 시작합니다.
`state`에 `update_tuned_intervals`를 쓴 뒤 `sample_us`와 `aggr_us`를 읽으면 tuning이 적용된 현재 값을 얻습니다.
원문 247행의 `:ref:design doc`은 reStructuredText role 표기가 잘못된 원문입니다. 번역에서는 의도한 `damon_design_monitoring_intervals_autotuning` design reference로 해석하되 source text와 줄 anchor는 그대로 보존합니다.
target과 초기 region
253-303`targets/nr_targets`에 N을 쓰면 `0`부터 `N-1`까지 monitoring target 디렉터리가 생깁니다. 각 target에는 `pid_target`과 `regions`가 있습니다. context operation이 `vaddr`라면 target은 process이며 `pid_target`에 그 process의 PID를 씁니다.
`fvaddr` 또는 `paddr` operation은 monitoring할 address range를 반드시 지정해야 합니다. `vaddr`는 필수가 아니지만 초기 monitoring region을 특정 range로 제한할 수 있습니다.
`regions/nr_regions`에 N을 쓰면 N개의 초기 region 디렉터리가 생깁니다. 각 `regions/<N>/`의 `start`와 `end`로 시작·끝 주소를 설정하고 읽습니다. region끼리는 겹치면 안 되며 directory N의 `end`는 directory N+1의 `start`보다 작거나 같아야 합니다.
DAMOS scheme
304-338`contexts/<N>/schemes/`는 DAMON-based Operation Schemes(DAMOS)를 구성합니다. `nr_schemes`에 N을 쓰면 `0`부터 `N-1`까지 scheme 디렉터리가 생기고 각 디렉터리가 하나의 operation scheme을 나타냅니다.
| 구성 요소 | 역할 |
|---|---|
| action | scheme이 수행할 DAMOS action keyword |
| target_nid | `migrate_hot` 또는 `migrate_cold`의 migration destination node |
| apply_interval_us | scheme action 적용 간격, microseconds |
| access_pattern | 대상 region의 size·access frequency·age 범위 |
| quotas | 시간·크기 quota, 우선순위 weight, 자동 tuning goal |
| watermarks | scheme 활성화를 제어하는 metric과 high·mid·low 경계 |
| core_filters | DAMON core layer가 처리하는 filter |
| ops_filters | monitoring operations set layer가 처리하는 filter |
| filters | 처리 layer를 지정하지 않는 호환 filter |
| dests | 여러 action destination과 상대 weight |
| stats | 시도·적용·filter 통과·quota 초과 통계 |
| tried_regions | action을 적용하려 한 region의 snapshot |
`action`에는 DAMOS design 문서에 정의된 action keyword를 씁니다. `target_nid`는 action이 `migrate_hot` 또는 `migrate_cold`일 때 migration target node를 지정합니다. `apply_interval_us`는 scheme의 apply interval을 microseconds 단위로 설정하고 조회합니다.
원문은 `eight directories`라고 쓰지만 괄호 안에는 `access_pattern`, `quotas`, `watermarks`, `core_filters`, `ops_filters`, `filters`, `dests`, `stats`, `tried_regions`의 9개 디렉터리를 열거합니다. 또한 같은 문단은 `apply_interval`이라 쓰고 실제 파일 설명과 계층도는 `apply_interval_us`를 사용합니다. 번역 표는 실제 열거와 파일명을 따릅니다.
access pattern과 quota
339-390`access_pattern`에는 `sz`, `nr_accesses`, `age` 세 디렉터리가 있고 각각 `min`, `max`를 가집니다. 이 세 closed interval로 scheme 대상 region의 size, access frequency, age를 정합니다. 최소와 최대 경계값은 모두 포함됩니다.
`quotas`에는 `ms`, `bytes`, `reset_interval_ms`, `effective_bytes` 파일과 `weights`, `goals` 디렉터리가 있습니다. `ms`는 action 적용에 쓸 time quota, `bytes`는 한 reset interval에 action을 적용할 size quota, `reset_interval_ms`는 quota charge를 초기화하는 기간입니다.
DAMON은 각 `reset_interval_ms` 동안 action 실행에 `ms` milliseconds까지만 쓰고, 최대 `bytes` byte의 matching region에만 action을 적용하려고 합니다. `ms`와 `bytes`를 모두 0으로 설정하면 quota goal이 하나 이상 존재하는 경우를 제외하고 quota limit가 비활성화됩니다.
time quota는 내부에서 size quota로 변환됩니다. 변환한 quota와 사용자가 쓴 size quota 중 작은 값이 먼저 선택되고, quota goal에 따라 다시 조정된 결과가 `effective_bytes`입니다. 이 파일은 실시간 갱신이 아니므로 `kdamonds/<N>/state`에 `update_schemes_effective_quotas`를 쓴 뒤 읽어야 합니다.
`weights`의 `sz_permil`, `nr_accesses_permil`, `age_permil`은 quota 안에서 어느 region을 먼저 처리할지 결정하는 size, access frequency, age의 우선순위 가중치이며 단위는 per-thousand입니다.
quota goal과 watermark
391-433`quotas/goals/nr_goals`에 N을 쓰면 N개의 자동 quota tuning goal 디렉터리가 생깁니다. 각 goal은 `target_metric`, `target_value`, `current_value`, `nid` 네 파일로 목표와 현재 달성 상태를 표현합니다. 여러 feedback이 있으면 그중 가장 좋은 feedback을 사용합니다.
파일을 쓴 것만으로 feedback이 DAMON에 전달되지는 않습니다. 관련 kdamond의 `state`에 `commit_schemes_quota_goals`를 써야 합니다.
`watermarks`에는 `metric`, `interval_us`, `high`, `mid`, `low`가 있습니다. `metric`에는 watermark를 무시하는 `none` 또는 system free memory 비율을 per-thousand 단위로 쓰는 `free_mem_rate`를 지정합니다. `interval_us`는 metric을 확인할 간격이며 microseconds 단위입니다.
세 watermark는 scheme을 시작·유지·중지할 구간을 만듭니다. 실제 경계 동작은 DAMOS watermark design과 함께 확인해야 하며, 원문의 `interval` 표현은 계층과 파일명에서 `interval_us`로 구체화됩니다.
DAMOS filter
434-498`core_filters`, `ops_filters`, `filters`는 각각 DAMON core layer, monitoring operations set layer, layer를 지정하지 않은 방식의 filter를 설치합니다. 세 디렉터리의 파일 구조는 같고 core·ops filter가 generic `filters`보다 먼저 설치됩니다.
generic `filters`는 evaluation order를 예측하기 어렵게 만들 수 있으므로 `core_filters`와 `ops_filters` 사용이 권장됩니다. 원문은 `filters`가 향후 deprecated될 수 있다고 경고합니다.
`nr_filters`에 N을 쓰면 `0`부터 `N-1`까지 filter 디렉터리가 생기며 숫자 순서대로 평가됩니다. 각 filter에는 `type`, `matching`, `allow`, `memcg_path`, `addr_start`, `addr_end`, `min`, `max`, `target_idx`의 9개 파일이 있습니다.
| type | 설정 파일 | 범위·대상 |
|---|---|---|
| memcg | memcg_path | cgroups mount point를 기준으로 한 memory cgroup path |
| addr | addr_start, addr_end | 시작은 포함하고 끝은 제외하는 open-ended address interval |
| hugepage_size | min, max | 최소·최대 huge page size를 모두 포함하는 closed interval |
| target | target_idx | DAMON context의 monitoring target 목록에 있는 index |
`matching`에 Y 또는 N을 써서 지정한 `type`에 일치하는 memory를 고를지, 일치하지 않는 memory를 고를지 정합니다. `allow`에 Y 또는 N을 써서 그 조건을 만족한 memory에 action 적용을 허용할지 금지할지 정합니다.
다음 예는 `ops_filters/0/`에 filter 두 개를 만들고 anonymous page를 금지한 뒤, `/having_care_already`를 제외한 모든 memory cgroup을 추가로 걸러냅니다. 결과적으로 그 cgroup에 속한 non-anonymous page에만 DAMOS action을 허용합니다.
# cd ops_filters/0/
# echo 2 > nr_filters
# # disallow anonymous pages
echo anon > 0/type
echo Y > 0/matching
echo N > 0/allow
# # further filter out all cgroups except one at '/having_care_already'
echo memcg > 1/type
echo /having_care_already > 1/memcg_path
echo Y > 1/matching
echo N > 1/allow여러 filter의 `allow` 조합, 각 filter type의 지원 시점, layer에 따른 statistics 차이는 DAMOS filter design 문서를 참조합니다.
destination과 scheme 통계
499-537`dests`는 scheme action의 목적지를 지정합니다. 여러 destination을 지원하지 않는 action에서는 무시되며 현재 복수 목적지를 지원하는 action은 `DAMOS_MIGRATE_{HOT,COLD}`뿐입니다.
`nr_dests`에 N을 쓰면 destination N개가 생깁니다. 각 destination의 `id`에는 식별자를, `weight`에는 임의의 정수 가중치를 씁니다. migrate action에서는 `id`가 destination node ID이며, 각 memory entity에 action을 적용할 때 상대 weight에 따라 목적지를 선택합니다.
`stats`는 scheme의 online analysis와 tuning에 사용할 누적 통계를 제공합니다. 파일은 실시간으로 갱신되지 않으므로 관련 `kdamonds/<N>/state`에 `update_schemes_stats`를 쓴 뒤 읽습니다.
| 통계 파일 | 의미 |
|---|---|
| nr_tried | scheme action 적용을 시도한 region 수 |
| sz_tried | scheme action 적용을 시도한 총 byte 수 |
| nr_applied | scheme action이 실제 적용된 region 수 |
| sz_applied | scheme action이 실제 적용된 총 byte 수 |
| sz_ops_filter_passed | operations-set filter를 통과해 action 대상으로 남은 byte 수 |
| qt_exceeds | scheme이 quota를 초과해 작업을 멈춘 횟수 |
tried_regions 조회
538-577`tried_regions`에는 처음에 `total_bytes`만 있습니다. `state`에 `update_schemes_tried_regions`를 쓰면 DAMON은 scheme이 action 적용을 시도한 region의 총 크기를 `total_bytes`에 갱신하고, 다음 scheme apply interval 동안 수집한 상세 region을 `0`부터 시작하는 디렉터리로 만듭니다.
상세 정보에는 address range, `nr_accesses`, `age`가 포함됩니다. `update_schemes_tried_bytes`는 `total_bytes`만 갱신하고 child directory를 만들지 않으며, `clear_schemes_tried_regions`는 상세 directory를 제거합니다.
이 interface는 scheme 동작 조사나 query 형태의 효율적인 access monitoring 결과 조회에 적합합니다. query 용도로는 scheme `action`을 `stat`으로 설정하고 관심 있는 `access_pattern`을 지정합니다.
각 `tried_regions/<N>/`의 `start`, `end`, `nr_accesses`, `age`, `sz_filter_passed`를 읽으면 해당 DAMOS action이 적용을 시도한 region의 주소, 접근 특성, filter 통과 크기를 확인할 수 있습니다.
DAMOS sysfs 설정 예
578-617다음 설정은 크기가 [4 KiB, 8 KiB], aggregation interval당 access 수가 [0, 5], 그 상태의 age가 [10, 20] aggregation interval인 memory region을 page out합니다. pageout에는 1초당 CPU time 10 ms, memory 1 GiB까지만 쓰고, 제한 안에서는 age가 큰 region을 먼저 처리합니다.
system free memory rate는 5초마다 확인합니다. free memory가 50%보다 낮아지면 monitoring과 pageout을 시작하고, 60%보다 높아지거나 30%보다 낮아지면 중지합니다. watermark 값 600, 500, 300은 per-thousand 단위입니다.
# cd <sysfs>/kernel/mm/damon/admin
# # populate directories
# echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts;
# echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes
# cd kdamonds/0/contexts/0/schemes/0
# # set the basic access pattern and the action
# echo 4096 > access_pattern/sz/min
# echo 8192 > access_pattern/sz/max
# echo 0 > access_pattern/nr_accesses/min
# echo 5 > access_pattern/nr_accesses/max
# echo 10 > access_pattern/age/min
# echo 20 > access_pattern/age/max
# echo pageout > action
# # set quotas
# echo 10 > quotas/ms
# echo $((1024*1024*1024)) > quotas/bytes
# echo 1000 > quotas/reset_interval_ms
# # set watermark
# echo free_mem_rate > watermarks/metric
# echo 5000000 > watermarks/interval_us
# echo 600 > watermarks/high
# echo 500 > watermarks/mid
# echo 300 > watermarks/low이 명령은 sysfs 구조를 보여 주기 위한 예입니다. 실제 운영에서는 파일을 직접 읽고 쓰기보다 DAMO 같은 user-space tool 사용이 강하게 권장됩니다.
monitoring result tracepoint
618-659`tried_regions`는 snapshot 조회에는 유용하지만 monitoring 결과 전체를 계속 기록하기에는 비효율적일 수 있습니다. 이를 위해 `damon:damon_aggregated`와 `damon:damos_before_apply` tracepoint가 제공됩니다.
`damon:damon_aggregated`는 전체 monitoring 결과를 내보냅니다. `damon:damos_before_apply`는 각 DAMOS가 곧 적용될 region만 내보내므로 DAMOS 내부 동작 기록이나 target access pattern 기반 query에 더 적합합니다.
monitoring이 켜진 동안 `perf`처럼 tracepoint를 지원하는 도구로 event를 기록하고 출력할 수 있습니다. 다음 예는 5초 동안 aggregated event를 수집합니다.
# echo on > kdamonds/0/state
# perf record -e damon:damon_aggregated &
# sleep 5
# kill 9 $(pidof perf)
# echo off > kdamonds/0/state
# perf script
kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864
[...]| 필드 | 의미 |
|---|---|
| 1-5 | 일반적인 tracepoint 공통 필드 |
| 6 | `target_id=X`: monitoring target ID |
| 7 | `nr_regions=X`: 해당 target의 전체 monitoring region 수 |
| 8 | `X-Y:`: region의 byte 단위 시작·끝 주소 |
| 9 | `X`: region의 `nr_accesses` |
| 10 | `X`: region의 `age` |
| before_apply 추가 | `ctx_idx=X`: kdamond context 목록에서 context index |
| before_apply 추가 | `scheme_idx=X`: context의 scheme 목록에서 scheme index |
| before_apply 추가 | `target_idx=X`: context의 target 목록에서 target index |
`perf script`의 각 줄은 monitoring region 하나입니다. 주소 `X-Y`는 byte 단위이고 뒤의 두 숫자는 각각 DAMON region-based sampling의 `nr_accesses`와 age tracking의 `age` counter입니다.
원문 650행의 `ide`는 문맥상 monitoring target의 `id`를 뜻하는 오탈자입니다. 원문과 line anchor는 그대로 보존하고 번역에서는 ID로 풀이합니다.
damos_before_apply 출력
660-671`damon:damos_before_apply` event의 각 줄은 trace 시점에 DAMOS action이 적용되기 직전인 monitoring region 하나를 나타냅니다. 일반 tracepoint 공통 필드와 `damon_aggregated`의 region 정보에 더해 `ctx_idx`, `scheme_idx`, `target_idx`를 출력합니다.
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
[...]`ctx_idx`는 해당 kdamond의 context 목록에서 context index, `scheme_idx`는 context의 scheme 목록에서 scheme index, `target_idx`는 context의 target 목록에서 target index입니다.
원문 660행은 event 이름을 `damon:damos_beofre_apply`로 잘못 적었지만 실제 tracepoint와 예제 출력은 `damon:damos_before_apply`입니다. 두 literal을 모두 보존해 검색과 원문 대조가 가능하게 했습니다.
DAMON 상세 사용 지도
usage.rst:1-671이 문서는 DAMON의 세 사용자 interface를 구분한 뒤, privileged user space에서 쓰는 sysfs 계층을 root부터 결과 조회까지 따라갑니다. 실제 명령을 적용하기 전에 각 `nr_*` 파일로 directory를 만들고 `state` 명령으로 설정과 통계를 언제 commit·refresh해야 하는지 이해하는 것이 핵심입니다.
운영에서는 DAMO를 우선 사용하고, sysfs는 특별한 자동화나 세밀한 tuning이 필요할 때 직접 다루는 편이 좋습니다. `stats`, `tried_regions`, tracepoint는 각각 누적 통계, 선택적 snapshot, 연속 기록이라는 서로 다른 관측 목적을 가집니다.