Update man pages and docs

docs/nohang.manpage.md

@@ -23,20 +23,20 @@ nohang is a highly configurable daemon for Linux which is able to correctly prev
 - libnotify (Arch Linux, Fedora, openSUSE) or libnotify-bin (Debian GNU/Linux, Ubuntu)
 - sudo if nohang started with UID=0.
 
-# OPTIONS
+# COMMAND-LINE OPTIONS
 
 #### -h, --help
 show this help message and exit
 
-#### -v, \-\-version
+#### -v, --version
 show version of installed package and exit
 
-#### -m, \-\-memload
+#### -m, --memload
 consume memory until 40 MiB (MemAvailable + SwapFree) remain free, and terminate the process
 
-#### -c CONFIG, \-\-config CONFIG
+#### -c CONFIG, --config CONFIG
 path to the config file. This should only be used with one of the following options:
-\-\-monitor, \-\-tasks, --check
+--monitor, --tasks, --check
 
 #### --check
 check and show the configuration and exit. This should only be used with -c/--config CONFIG option
@@ -47,6 +47,36 @@ start monitoring. This should only be used with -c/--config CONFIG option
 #### --tasks
 show tasks state and exit. This should only be used with -c/--config CONFIG option
 
+# FILES
+
+#### $SYSCONFDIR/nohang/nohang.conf
+path to vanilla nohang configuration file
+
+#### $SYSCONFDIR/nohang/nohang-desktop.conf
+path to configuration file with settings optimized for desktop usage
+
+#### $DATADIR/nohang/nohang.conf
+path to file with *default* nohang.conf values
+
+#### $DATADIR/nohang/nohang-desktop.conf
+path to file with *default* nohang-desktop.conf values
+
+#### $LOGDIR/nohang/nohang.log
+optional log file that stores entries if separate_log=True in the config
+
+#### /etc/logrotate.d/nohang
+logrotate config file that controls rotation in /var/log/nohang/
+
+# nohang.conf vs nohang-desktop.conf
+- nohang.conf provides vanilla default settings without PSI checking enabled, without any badness correction and without GUI notifications enabled.
+- nohang-desktop.conf provides default settings optimized for desktop usage.
+
+# PROBLEMS
+The next problems can occur with out-of-tree kernels and modules:
+
+- The ZFS ARC cache is memory-reclaimable, like the Linux buffer cache. However, in contrast to the buffer cache, it currently does not count to MemAvailable [1]. See also [2] and [3].
+- Linux kernels without CONFIG_CGROUP_CPUACCT=y (linux-ck, for example) provide incorrect PSI metrics, see this thread [4].
+
 # HOW TO CONFIGURE
 The program can be configured by editing the config file. The configuration includes the following sections:
 
@@ -64,6 +94,11 @@ The program can be configured by editing the config file. The configuration incl
 
 Just read the description of the parameters and edit the values. Restart the daemon to apply the changes.
 
+# CHECK CONFIG
+Check the config for errors:
+
+$ nohang --check --config /path/to/config
+
 # HOW TO TEST
 The safest way is to run **nohang --memload**. This causes memory consumption, and the process will exits before OOM occurs. Another way is to run **tail /dev/zero**. This causes fast memory comsumption and causes OOM at the end. If testing occurs while nohang is running, these processes should be terminated before OOM occurs.
 
@@ -77,3 +112,25 @@ or
 $ **sudo journalctl -eu nohang-desktop.service**
 
 You can also enable **separate_log** in the config to logging in **/var/log/nohang/nohang.log**.
+
+# SIGNALS
+Sending SIGTERM, SIGINT, SIGQUIT or SIGHUP signals to the nohang process causes it displays corrective action stats and exits.
+
+# REPORTING BUGS
+Please ask any questions and report bugs at <https://github.com/hakavlad/nohang/issues>.
+
+# AUTHOR
+Written by Alexey Avramov <hakavlad@gmail.com>.
+
+# HOMEPAGE
+Homepage is <https://github.com/hakavlad/nohang>.
+
+# SEE ALSO
+oom-sort(1), psi-top(1), psi2log(1)
+
+# NOTES
+
+1. https://github.com/openzfs/zfs/issues/10255
+2. https://github.com/rfjakob/earlyoom/pull/191#issuecomment-622314296
+3. https://github.com/hakavlad/nohang/issues/89
+4. https://github.com/hakavlad/nohang/issues/25#issuecomment-521390412

docs/oom-sort.manpage.md

@@ -1,9 +1,36 @@
 % oom-sort(1) | General Commands Manual
 
 # NAME
-
 oom-sort - sort processes by oom_score
 
 # SYNOPSIS
-
 **oom-sort** [**OPTION**]...
+
+# DESCRIPTION
+oom-sort is script that sorts tasks by oom_score by default. oom-sort is part of nohang package.
+
+# OPTIONS
+
+#### -h, --help
+show this help message and exit
+
+#### --num NUM, -n NUM
+max number of lines; default: 99999
+
+#### --len LEN, -l LEN
+max cmdline length; default: 99999
+
+#### --sort SORT, -s SORT
+sort by unit; available units: oom_score, oom_score_adj, UID, PID, Name, VmRSS, VmSwap, cmdline (optional); default unit: oom_score
+
+# REPORTING BUGS
+Please ask any questions and report bugs at <https://github.com/hakavlad/nohang/issues>.
+
+# AUTHOR
+Written by Alexey Avramov <hakavlad@gmail.com>.
+
+# HOMEPAGE
+Homepage is <https://github.com/hakavlad/nohang>.
+
+# SEE ALSO
+psi-top(1), psi2log(1), nohang(8)

docs/psi-top.manpage.md

@@ -1,9 +1,37 @@
 % psi-top(1) | General Commands Manual
 
 # NAME
-
+psi-top - print the PSI metrics values for every cgroup.
-psi-top
 
 # SYNOPSIS
-
 **psi-top** [**OPTION**]...
+
+# DESCRIPTION
+psi-top is script that prints the PSI metrics values for every cgroup. psi-top is part of nohang package.
+
+# OPTIONS
+
+#### -h, --help
+show this help message and exit
+
+#### -m METRICS, --metrics METRICS
+metrics (memory, io or cpu)
+
+# EXAMPLES
+$ psi-top
+
+$ psi-top --metrics io
+
+$ psi-top -m cpu
+
+# REPORTING BUGS
+Please ask any questions and report bugs at <https://github.com/hakavlad/nohang/issues>.
+
+# AUTHOR
+Written by Alexey Avramov <hakavlad@gmail.com>.
+
+# HOMEPAGE
+Homepage is <https://github.com/hakavlad/nohang>.
+
+# SEE ALSO
+oom-sort(1), psi2log(1), nohang(8)

docs/psi2log.manpage.md

@@ -1,9 +1,52 @@
 % psi2log(1) | General Commands Manual
 
 # NAME
-
 psi2log \- PSI metrics monitor and logger
 
 # SYNOPSIS
-
 **psi2log** [**OPTION**]...
+
+# DESCRIPTION
+psi2log is a CLI tool that can check and log PSI metrics from specified target. psi2log is part of nohang package.
+
+# OPTIONS
+
+#### -h, --help
+show this help message and exit
+
+#### -t TARGET, --target TARGET
+target (cgroup_v2 or SYTSTEM_WIDE)
+
+#### -i INTERVAL, --interval INTERVAL
+interval in sec
+
+#### -l LOG, --log LOG
+path to log file
+
+#### -m MODE, --mode MODE
+mode (1 or 2)
+
+#### -s SUPPRESS_OUTPUT, --suppress-output SUPPRESS_OUTPUT
+suppress output
+
+# EXAMPLES
+$ psi2log
+
+$ psi2log --mode 2
+
+$ psi2log --target /user.slice --interval 1.5 --log psi.log
+
+# SIGNALS
+Sending SIGTERM, SIGINT, SIGQUIT or SIGHUP signals to the psi2log process causes it displays peak values and exits..
+
+# REPORTING BUGS
+Please ask any questions and report bugs at <https://github.com/hakavlad/nohang/issues>.
+
+# AUTHOR
+Written by Alexey Avramov <hakavlad@gmail.com>.
+
+# HOMEPAGE
+Homepage is <https://github.com/hakavlad/nohang>.
+
+# SEE ALSO
+oom-sort(1), psi-top(1), nohang(8)

man/nohang.8

@@ -31,7 +31,7 @@ libnotify (Arch Linux, Fedora, openSUSE) or libnotify\-bin (Debian
 GNU/Linux, Ubuntu)
 .IP \[bu] 2
 sudo if nohang started with UID=0.
-.SH OPTIONS
+.SH COMMAND\-LINE OPTIONS
 .SS \-h, \-\-help
 .PP
 show this help message and exit
@@ -59,6 +59,44 @@ This should only be used with \-c/\-\-config CONFIG option
 .PP
 show tasks state and exit.
 This should only be used with \-c/\-\-config CONFIG option
+.SH FILES
+.SS $SYSCONFDIR/nohang/nohang.conf
+.PP
+path to vanilla nohang configuration file
+.SS $SYSCONFDIR/nohang/nohang\-desktop.conf
+.PP
+path to configuration file with settings optimized for desktop usage
+.SS $DATADIR/nohang/nohang.conf
+.PP
+path to file with \f[I]default\f[] nohang.conf values
+.SS $DATADIR/nohang/nohang\-desktop.conf
+.PP
+path to file with \f[I]default\f[] nohang\-desktop.conf values
+.SS $LOGDIR/nohang/nohang.log
+.PP
+optional log file that stores entries if separate_log=True in the config
+.SS /etc/logrotate.d/nohang
+.PP
+logrotate config file that controls rotation in /var/log/nohang/
+.SH nohang.conf vs nohang\-desktop.conf
+.IP \[bu] 2
+nohang.conf provides vanilla default settings without PSI checking
+enabled, without any badness correction and without GUI notifications
+enabled.
+.IP \[bu] 2
+nohang\-desktop.conf provides default settings optimized for desktop
+usage.
+.SH PROBLEMS
+.PP
+The next problems can occur with out\-of\-tree kernels and modules:
+.IP \[bu] 2
+The ZFS ARC cache is memory\-reclaimable, like the Linux buffer cache.
+However, in contrast to the buffer cache, it currently does not count to
+MemAvailable [1].
+See also [2] and [3].
+.IP \[bu] 2
+Linux kernels without CONFIG_CGROUP_CPUACCT=y (linux\-ck, for example)
+provide incorrect PSI metrics, see this thread [4].
 .SH HOW TO CONFIGURE
 .PP
 The program can be configured by editing the config file.
@@ -92,6 +130,11 @@ Misc
 .PP
 Just read the description of the parameters and edit the values.
 Restart the daemon to apply the changes.
+.SH CHECK CONFIG
+.PP
+Check the config for errors:
+.PP
+$ nohang \-\-check \-\-config /path/to/config
 .SH HOW TO TEST
 .PP
 The safest way is to run \f[B]nohang \-\-memload\f[].
@@ -113,3 +156,29 @@ $ \f[B]sudo journalctl \-eu nohang\-desktop.service\f[]
 .PP
 You can also enable \f[B]separate_log\f[] in the config to logging in
 \f[B]/var/log/nohang/nohang.log\f[].
+.SH SIGNALS
+.PP
+Sending SIGTERM, SIGINT, SIGQUIT or SIGHUP signals to the nohang process
+causes it displays corrective action stats and exits.
+.SH REPORTING BUGS
+.PP
+Please ask any questions and report bugs at
+<https://github.com/hakavlad/nohang/issues>.
+.SH AUTHOR
+.PP
+Written by Alexey Avramov <hakavlad@gmail.com>.
+.SH HOMEPAGE
+.PP
+Homepage is <https://github.com/hakavlad/nohang>.
+.SH SEE ALSO
+.PP
+oom\-sort(1), psi\-top(1), psi2log(1)
+.SH NOTES
+.IP "1." 3
+https://github.com/openzfs/zfs/issues/10255
+.IP "2." 3
+https://github.com/rfjakob/earlyoom/pull/191#issuecomment\-622314296
+.IP "3." 3
+https://github.com/hakavlad/nohang/issues/89
+.IP "4." 3
+https://github.com/hakavlad/nohang/issues/25#issuecomment\-521390412

man/oom-sort.1

@@ -8,3 +8,34 @@ oom\-sort \- sort processes by oom_score
 .SH SYNOPSIS
 .PP
 \f[B]oom\-sort\f[] [\f[B]OPTION\f[]]...
+.SH DESCRIPTION
+.PP
+oom\-sort is script that sorts tasks by oom_score by default.
+oom\-sort is part of nohang package.
+.SH OPTIONS
+.SS \-h, \-\-help
+.PP
+show this help message and exit
+.SS \-\-num NUM, \-n NUM
+.PP
+max number of lines; default: 99999
+.SS \-\-len LEN, \-l LEN
+.PP
+max cmdline length; default: 99999
+.SS \-\-sort SORT, \-s SORT
+.PP
+sort by unit; available units: oom_score, oom_score_adj, UID, PID, Name,
+VmRSS, VmSwap, cmdline (optional); default unit: oom_score
+.SH REPORTING BUGS
+.PP
+Please ask any questions and report bugs at
+<https://github.com/hakavlad/nohang/issues>.
+.SH AUTHOR
+.PP
+Written by Alexey Avramov <hakavlad@gmail.com>.
+.SH HOMEPAGE
+.PP
+Homepage is <https://github.com/hakavlad/nohang>.
+.SH SEE ALSO
+.PP
+psi\-top(1), psi2log(1), nohang(8)

man/psi-top.1

@@ -4,7 +4,38 @@
 .hy
 .SH NAME
 .PP
-psi\-top
+psi\-top \- print the PSI metrics values for every cgroup.
 .SH SYNOPSIS
 .PP
 \f[B]psi\-top\f[] [\f[B]OPTION\f[]]...
+.SH DESCRIPTION
+.PP
+psi\-top is script that prints the PSI metrics values for every cgroup.
+psi\-top is part of nohang package.
+.SH OPTIONS
+.SS \-h, \-\-help
+.PP
+show this help message and exit
+.SS \-m METRICS, \-\-metrics METRICS
+.PP
+metrics (memory, io or cpu)
+.SH EXAMPLES
+.PP
+$ psi\-top
+.PP
+$ psi\-top \-\-metrics io
+.PP
+$ psi\-top \-m cpu
+.SH REPORTING BUGS
+.PP
+Please ask any questions and report bugs at
+<https://github.com/hakavlad/nohang/issues>.
+.SH AUTHOR
+.PP
+Written by Alexey Avramov <hakavlad@gmail.com>.
+.SH HOMEPAGE
+.PP
+Homepage is <https://github.com/hakavlad/nohang>.
+.SH SEE ALSO
+.PP
+oom\-sort(1), psi2log(1), nohang(8)

man/psi2log.1

@@ -8,3 +8,51 @@ psi2log \- PSI metrics monitor and logger
 .SH SYNOPSIS
 .PP
 \f[B]psi2log\f[] [\f[B]OPTION\f[]]...
+.SH DESCRIPTION
+.PP
+psi2log is a CLI tool that can check and log PSI metrics from specified
+target.
+psi2log is part of nohang package.
+.SH OPTIONS
+.SS \-h, \-\-help
+.PP
+show this help message and exit
+.SS \-t TARGET, \-\-target TARGET
+.PP
+target (cgroup_v2 or SYTSTEM_WIDE)
+.SS \-i INTERVAL, \-\-interval INTERVAL
+.PP
+interval in sec
+.SS \-l LOG, \-\-log LOG
+.PP
+path to log file
+.SS \-m MODE, \-\-mode MODE
+.PP
+mode (1 or 2)
+.SS \-s SUPPRESS_OUTPUT, \-\-suppress\-output SUPPRESS_OUTPUT
+.PP
+suppress output
+.SH EXAMPLES
+.PP
+$ psi2log
+.PP
+$ psi2log \-\-mode 2
+.PP
+$ psi2log \-\-target /user.slice \-\-interval 1.5 \-\-log psi.log
+.SH SIGNALS
+.PP
+Sending SIGTERM, SIGINT, SIGQUIT or SIGHUP signals to the psi2log
+process causes it displays peak values and exits..
+.SH REPORTING BUGS
+.PP
+Please ask any questions and report bugs at
+<https://github.com/hakavlad/nohang/issues>.
+.SH AUTHOR
+.PP
+Written by Alexey Avramov <hakavlad@gmail.com>.
+.SH HOMEPAGE
+.PP
+Homepage is <https://github.com/hakavlad/nohang>.
+.SH SEE ALSO
+.PP
+oom\-sort(1), psi\-top(1), nohang(8)