pmemstat 4.2.0__tar.gz → 4.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.5
1
+ Metadata-Version: 2.4
2
2
  Name: pmemstat
3
- Version: 4.2.0
3
+ Version: 4.3.1
4
4
  Summary: Report Proportional Memory on Linux
5
5
  Keywords: proportional memory,RAM,htop,top,monitor
6
6
  Author-email: Joe Defen <joedef@duck.com>
@@ -18,18 +18,8 @@ Classifier: License :: OSI Approved :: MIT License
18
18
  Classifier: Operating System :: POSIX :: Linux
19
19
  License-File: LICENSE.txt
20
20
  Requires-Dist: console-window ~= 3.1.0
21
- Requires-Dist: pylint == 3.3.4 ; extra == "dev"
22
- Requires-Dist: ruff >= 0.9 ; extra == "dev"
23
- Requires-Dist: pytest >= 7.0 ; extra == "dev"
24
- Requires-Dist: pytest-cov >= 4.0 ; extra == "dev"
25
- Requires-Dist: build >= 1.2 ; extra == "dev"
26
- Requires-Dist: twine >= 7 ; extra == "dev"
27
- Requires-Dist: packaging >= 26 ; extra == "dev"
28
- Requires-Dist: tomli >= 2.0 ; extra == "dev" and ( python_version < "3.11")
29
21
  Project-URL: Bug Tracker, https://github.com/joedefen/pmemstat/issues
30
22
  Project-URL: Homepage, https://github.com/joedefen/pmemstat
31
- Provides-Extra: dev
32
- Import-Name: pmemstat
33
23
 
34
24
  > **Quick Start**: from the CLI (requires **Python 3.10 or later**)
35
25
  > * **Install (preferred, per-user):** `pipx install pmemstat`
@@ -60,26 +50,23 @@ Without `-o`, `pmemstat` is much faster but less detailed (it omits classes such
60
50
  Grouping rolls up the resources of multiple processes of one feature (e.g. a browser) so its total memory/CPU impact is apparent. Looping reveals growth that may be a leak, and segregating memory by type makes leaks easier to identify.
61
51
 
62
52
  ## How `pmemstat` Compares to Other Tools
63
- Reach for `top`/`ps` when you need a tool that is always installed, and `htop` for a friendly full-screen overview. `pmemstat` differs in its focus on **accurate, proportional memory**: rather than RES/RSS — which double-counts shared pages and ignores uninstantiated virtual memory — it digests `smaps`/`smaps_rollup` to attribute shared memory fairly and break memory down by type. That makes it slower to start (especially with `-o`) but far more truthful about who is really using RAM. The table compares it with its closest peers: `smem` (the other tool that derives **PSS** from `smaps`) and `systemd-cgtop` (whose per-cgroup view `pmemstat` mirrors, with proportional numbers).
64
-
65
- | Feature | `pmemstat` | `smem` | `systemd-cgtop` | `htop` |
66
- |---|---|---|---|---|
67
- | **Proportional memory (PSS)** accounting | ✓ core design | ✓ core design | ✗ (`memory.current`) | ✗ (RES, double-counts) |
68
- | **Memory-type breakdown** (shared/swap/stack/text/data) | ✓ | ✗ (USS/PSS/RSS/Swap only) | ✗ | ✗ |
69
- | **Proportional swap** per grouping | ✓ | ✗ (flat Swap column) | ✗ | ✗ (total swap only) |
70
- | **Group processes** by executable/command | ✓ aggregates PIDs into one row | ✓ by command by default | ✗ | ✗ (tree view only) |
71
- | **Group by cgroup v2** (services, scopes, containers) | ✓ (`-g cgroup`) | ✗ | ✓ (its core design) | ✗ |
72
- | **Memory-leak / growth monitoring** (annotates top-N growers; only re-shows significant growth) | ✓ (`G`, `--growth-style`, growth sort) | ✗ | ✗ | ✗ |
73
- | **zRAM-aware effective RAM** (eTot/eUsed/eAvail) | ✓ | ✗ | ✗ | ✗ |
74
- | **System pressure (PSI)** in header (memory/cpu/io, some/full) | ✓ (`-P`) | ✗ | ✗ | ✗ |
75
- | **Data source** | `/proc/{PID}/smaps*` | `/proc/{PID}/smaps` | `/sys/fs/cgroup` | `/proc` + libs |
76
- | **Interactive full-screen window** | ✓ (curses) | ✗ (one-shot) | ✓ | ✓ |
77
- | **CPU usage reporting** | ✓ | ✗ (memory only) | ✓ | ✓ |
78
- | **Kill processes** | ✓ (inline confirm) | ✗ | ✗ | ✓ |
79
- | **Inline search-as-you-type** | ✓ (`/`) | ✗ | ✗ | ✓ (F3) |
80
- | **Requires root for all-process detail** | ✓ (else only your own) | ✓ (else only your own) | ✗ | ✗ |
81
-
82
- For **per-mapped-file attribution** (which shared library or mmap'd file costs the most RAM), use `smem -m` or `pmap`; `pmemstat` deliberately stays focused on per-process and per-cgroup responsibility rather than rolling PSS up by mapped file.
53
+ Reach for `top`/`ps`/`htop` for a quick overview; `pmemstat` focuses on accurate, **proportional** memory and the sources of growth. Main features:
54
+
55
+ * Proportional PSS accounting (shared pages split fairly)
56
+ * Memory-type breakdown (shared, swap, stack, text, data)
57
+ * Proportional swap per grouping
58
+ * Group processes by executable, command, PID or cgroup v2
59
+ * Memory-leak / growth monitoring with cross-run history
60
+ * zRAM-aware effective RAM (`eTot`/`eUsed`/`eAvail`)
61
+ * System pressure (PSI) in the header
62
+ * Full-screen window: inline search, themes, kill mode
63
+
64
+ Selected competitors:
65
+ * `top` / `htop` — familiar, but no PSS or memory-type breakdown.
66
+ * `smem` — has PSS; lacks cgroup grouping, growth history and PSI.
67
+ * `systemd-cgtop` — per-cgroup view; no proportional memory or leak tracking.
68
+
69
+ For per-mapped-file attribution, use `smem -m` or `pmap`.
83
70
 
84
71
  ## Installation Options
85
72
  * `pmemstat` requires **Python 3.10 or later**.
@@ -114,8 +101,8 @@ options:
114
101
  dflt=20]
115
102
  -P, --psi show PSI (system pressure in header + memPSI% column)
116
103
  [dflt=off]
117
- --theme NAME initial colour theme (see --list-themes); "mono"
118
- disables colour (it is also the last entry in the T
104
+ --theme NAME initial color theme (see --list-themes); "mono"
105
+ disables color (it is also the last entry in the T
119
106
  picker).
120
107
  --list-themes list the available themes and exit
121
108
  -g, --groupby {exe,cmd,pid,cgroup,cgroupCharge}
@@ -170,7 +157,7 @@ Explanation of some options and arguments:
170
157
 
171
158
 
172
159
  ## Grouping by cgroup v2
173
- With `-g cgroup` (or cycling `g` in window mode) `pmemstat` groups processes by their **cgroup v2** path (read from `/proc/<pid>/cgroup`), which corresponds to systemd services/scopes and to container sandboxes. Each row is labelled with the cgroup's leaf unit name (e.g. `foo.service`), and a trailing `+` marks a cgroup that also contains descendant cgroups listed on their own rows. If the leaf name matches none of the row's member executables — common with launcher-created app scopes (e.g. niri's `app-niri-fuzzel-*.scope`, which actually host the launched app) — the row is labelled with the dominant member executable instead; the full cgroup path stays searchable with `/`.
160
+ With `-g cgroup` (or cycling `g` in window mode) `pmemstat` groups processes by their **cgroup v2** path (read from `/proc/<pid>/cgroup`), which corresponds to systemd services/scopes and to container sandboxes. Each row is labeled with the cgroup's leaf unit name (e.g. `foo.service`), and a trailing `+` marks a cgroup that also contains descendant cgroups listed on their own rows. If the leaf name matches none of the row's member executables — common with launcher-created app scopes (e.g. niri's `app-niri-fuzzel-*.scope`, which actually host the launched app) — the row is labeled with the dominant member executable instead; the full cgroup path stays searchable with `/`.
174
161
 
175
162
  There are two cgroup memory views:
176
163
  * `kcharge` - what the kernel charges, and what `memory.max` / the OOM killer act on; the number `systemd-cgtop`/`docker stats` show.
@@ -191,7 +178,7 @@ The kernel columns, read from `/sys/fs/cgroup/<path>/` in the `-u` units, decomp
191
178
 
192
179
  These columns appear only in the cgroup groupings (`-g cgroup` / `-g cgroupCharge`), and are omitted entirely when the kernel exposes no cgroup v2 data (e.g. a cgroup v1 host).
193
180
 
194
- cgroup v2 accounting is **hierarchical**: each cgroup's figures include its descendants, so a row with separately listed descendants (marked `+`) has their figures **subtracted** and shows only its own share; rows therefore add up to `TOTALS`. The unified root (`/`, labelled `(root)`) is everyone's ancestor, so a process living directly in it — as inside a container, where it may be the only cgroup visible — makes the `(root)+` row count every other row as a descendant. `memPSI%` is not totalled (`n/a` in `TOTALS` and `---- OTHERS ----`).
181
+ cgroup v2 accounting is **hierarchical**: each cgroup's figures include its descendants, so a row with separately listed descendants (marked `+`) has their figures **subtracted** and shows only its own share; rows therefore add up to `TOTALS`. The unified root (`/`, labeled `(root)`) is everyone's ancestor, so a process living directly in it — as inside a container, where it may be the only cgroup visible — makes the `(root)+` row count every other row as a descendant. `memPSI%` is not totaled (`n/a` in `TOTALS` and `---- OTHERS ----`).
195
182
 
196
183
  Reading `/proc/<pid>/cgroup` and `/sys/fs/cgroup` needs no root, so the grouping works unprivileged too (the PSS columns still reflect only the processes you can read).
197
184
 
@@ -253,107 +240,52 @@ In the default window loop we see
253
240
  * **growth** - inline growth annotation for top-N growers (e.g. `3.5G 2h3m`); only when growth mode is not `off`
254
241
  * **key/info** - **{num}x**, the number of processes in the grouping (e.g. `24x browser`), plus the grouping key; `pid` grouping rows show `1x`, the pid and the command line.
255
242
 
256
- ## Colour and Themes
257
- In window mode colour highlights titles and values that are changing; it is
258
- decoration only, so a terminal without colour (or `TERM=dumb`) still shows the
259
- full report in plain text.
243
+ ## Color and Themes
244
+ In window mode color highlights titles and values that are changing; it is decoration only, so a terminal without color (or `TERM=dumb`) still shows the full report in plain text.
260
245
 
261
- `t` opens console-window's theme picker (`ESC` returns) and `t` there cycles the
262
- appearance: the palettes, then `mono`, which turns colour off and wraps back to
263
- the first palette. A pick is applied immediately and remembered per user.
246
+ `t` opens console-window's theme picker (`ESC` returns) and `t` there cycles the appearance: the palettes, then `mono`, which turns color off and wraps back to the first palette. A pick is applied immediately and remembered per user.
264
247
 
265
- `--theme` selects a theme and `--list-themes` prints the available names.
266
- `--theme mono`, or the standard `NO_COLOR` convention, turns colour off; `mono`
267
- is the last entry in the `t` picker cycle, and there is no separate colour flag.
248
+ `--theme` selects a theme and `--list-themes` prints the available names. `--theme mono`, or the standard `NO_COLOR` convention, turns color off; `mono` is the last entry in the `t` picker cycle, and there is no separate color flag.
268
249
 
269
250
  ## Memory growth (leak) detection
270
251
 
271
- With `--growth-style` (or the `G` key in window mode) `pmemstat` annotates the
272
- groups that are growing, making slow leaks visible without scrolling history:
252
+ With `--growth-style` (or the `G` key in window mode) `pmemstat` annotates the groups that are growing, making slow leaks visible without scrolling history:
273
253
 
274
254
  ```
275
255
  5.9 270 32 291 593 3.5G 2h3m 1x firefox
276
256
  ```
277
257
 
278
- * The annotation is `{human growth} {interval}` (e.g. `3.5G 2h3m`); `rate` adds
279
- a per-day projection (`3.5G/d`) once the baseline spans at least a minute, and
280
- `growth` shows just the size.
281
- * The column's `growth` label sits on the **TOTALS** row, directly above the
282
- annotations it titles; the TOTALS row's `T` marker is dropped there (its info
283
- already reads TOTALS) and returns when growth is `off`.
284
- * Changing the grouping (`g`/`o`) rebuilds every row, which would mark them all
285
- new for one refresh. With growth `off` that `A` flash is kept (it explains the
286
- reshuffle), but in a growth mode the annotations are shown instead, from the
287
- per-view history that survives the change; a key that genuinely appears later
288
- still gets its `A`.
289
- * Growth is measured from the group's **first observation this boot** (possibly
290
- an earlier run), not merely since this invocation; a reboot resets it. This
291
- history is system-wide and **root-only**: a non-root run (`-U`) measures only
292
- from this run's start. Opt out with `--no-growth-history`,
293
- `--dont-save-growth-history`, or `PMEMSTAT_NO_HISTORY` (both).
294
- * Startup bursts age out, and growth is clamped at zero, so shrinking is not
295
- reported.
296
- * A row is annotated only if its growth (KB) is at least `-k` **and** it is
297
- among the top-N growers (`--growth-top`, default `all`; `p` cycles `all`/`10`).
298
- `-s growth` sorts by the displayed metric.
299
- * With a cgroup grouping the metric is the grouping's total (`footprt` for
300
- `-g cgroup`, `kcharge` for `-g cgroupCharge`) rather than proportional PSS.
301
- * A system-wide line beneath the leader closes the identity
302
- `ΔUsed = ΔTOTALS(ptotal) + Δ(Sh+Tmp) + ΔOth`; as **root** the residual splits
303
- into `ΔOthK`/`ΔOthU`, so kernel/driver growth is separable from userspace and
304
- tmpfs, while a non-root run shows a single `ΔOth`. The shared baseline interval
305
- trails as `[1h58m]` in every growth mode.
258
+ * The annotation is `{human growth} {interval}` (e.g. `3.5G 2h3m`); `rate` adds a per-day projection (`3.5G/d`) once the baseline spans at least a minute, and `growth` shows just the size.
259
+ * The column's `growth` label sits on the **TOTALS** row, directly above the annotations it titles; the TOTALS row's `T` marker is dropped there (its info already reads TOTALS) and returns when growth is `off`.
260
+ * Changing the grouping (`g`/`o`) rebuilds every row, which would mark them all new for one refresh. With growth `off` that `A` flash is kept (it explains the reshuffle), but in a growth mode the annotations are shown instead, from the per-view history that survives the change; a key that genuinely appears later still gets its `A`.
261
+ * Growth is measured from the group's **first observation this boot** (possibly an earlier run), not merely since this invocation; a reboot resets it. This history is system-wide and **root-only**: a non-root run (`-U`) measures only from this run's start. Opt out with `--no-growth-history`, `--dont-save-growth-history`, or `PMEMSTAT_NO_HISTORY` (both).
262
+ * Startup bursts age out, and growth is clamped at zero, so shrinking is not reported.
263
+ * A row is annotated only if its growth (KB) is at least `-k` **and** it is among the top-N growers (`--growth-top`, default `all`; `p` cycles `all`/`10`). `-s growth` sorts by the displayed metric.
264
+ * With a cgroup grouping the metric is the grouping's total (`footprt` for `-g cgroup`, `kcharge` for `-g cgroupCharge`) rather than proportional PSS.
265
+ * A system-wide line beneath the leader closes the identity `ΔUsed = ΔTOTALS(ptotal) + Δ(Sh+Tmp) + ΔOth`; as **root** the residual splits into `ΔOthK`/`ΔOthU`, so kernel/driver growth is separable from userspace and tmpfs, while a non-root run shows a single `ΔOth`. The shared baseline interval trails as `[1h58m]` in every growth mode.
306
266
 
307
267
  ## Updating History from Cron / Startup
308
- `pmemstat --save-history-now` performs one silent scan, saves the current
309
- history and exits (`0` on success, `1` on failure with a message on stderr). It
310
- runs as root (elevating via `sudo` if needed) and ignores all other options and
311
- `PMEMSTAT_ARGS`, so it is safe from cron or a startup unit. Run it as the user
312
- whose history you want to update.
313
-
314
- `pmemstat --reset-history-now` scans the same way but **replaces** the saved
315
- history rather than merging: current values become the new baseline, as if the
316
- tool had first run just after boot. It likewise runs as root and ignores other
317
- options. Inside the window, `z` performs the same reset (only as root while the
318
- growth annotation is on), asking for `y`/`Y` confirmation first; `ESC` or 10
319
- seconds declines.
268
+ `pmemstat --save-history-now` performs one silent scan, saves the current history and exits (`0` on success, `1` on failure with a message on stderr). It runs as root (elevating via `sudo` if needed) and ignores all other options and `PMEMSTAT_ARGS`, so it is safe from cron or a startup unit. Run it as the user whose history you want to update.
269
+
270
+ `pmemstat --reset-history-now` scans the same way but **replaces** the saved history rather than merging: current values become the new baseline, as if the tool had first run just after boot. It likewise runs as root and ignores other options. Inside the window, `z` performs the same reset (only as root while the growth annotation is on), asking for `y`/`Y` confirmation first; `ESC` or 10 seconds declines.
320
271
 
321
272
  ## Key Legend (Window Mode)
322
- The top line of the header is an always-visible key legend with the live search
323
- field appended, so the available keys are in evidence without opening the help
324
- screen:
273
+ The top line of the header is an always-visible key legend with the live search field appended, so the available keys are in evidence without opening the help screen:
325
274
 
326
275
  ?:help group units sort cpu Kill PSI Growth /{regex}
327
276
 
328
- `?` opens the complete list of keys plus the navigation keys (press it again, or
329
- `ESC`, to return). `zap` is appended for a root run while the growth annotation
330
- is showing, since resetting the baseline has no visible effect otherwise.
277
+ `?` opens the complete list of keys plus the navigation keys (press it again, or `ESC`, to return). `zap` is appended for a root run while the growth annotation is showing, since resetting the baseline has no visible effect otherwise.
331
278
 
332
279
  ## Help Screen (in Window Mode, Press '?')
333
- In window mode, `?` opens the help screen (and closes it again); **ESC** also
334
- closes it. The navigation legend is at the top and, below the line, the option
335
- keys for the screen you came from with their possible values (the current choice
336
- is highlighted). Typing an option key (e.g. `c`) advances to the next value,
337
- applied on the next loop; the option keys also work directly on the main screen
338
- without opening the help screen. `t` opens the theme picker (where `t` cycles
339
- the appearance), and `K` on this screen toggles **demo mode**, which shows the
340
- last key pressed — handy for screencasts. **ENTER** closes nothing here — it
341
- stays reserved for kill mode's row selection.
342
-
343
- The first help page of a run also carries a **Fonts** section: the named
344
- one-cell symbols and the emoji are drawn as fixed-width blocks, so a terminal
345
- missing a glyph or shifting a wide character shows up as a visibly broken row
346
- rather than a silently misaligned report.
280
+ In window mode, `?` opens the help screen (and closes it again); **ESC** also closes it. The navigation legend is at the top and, below the line, the option keys for the screen you came from with their possible values (the current choice is highlighted). Typing an option key (e.g. `c`) advances to the next value, applied on the next loop; the option keys also work directly on the main screen without opening the help screen. `t` opens the theme picker (where `t` cycles the appearance), and `K` on this screen toggles **demo mode**, which shows the last key pressed — handy for screencasts. **ENTER** closes nothing here — it stays reserved for kill mode's row selection.
281
+
282
+ The first help page of a run also carries a **Fonts** section: the named one-cell symbols and the emoji are drawn as fixed-width blocks, so a terminal missing a glyph or shifting a wide character shows up as a visibly broken row rather than a silently misaligned report.
347
283
 
348
284
  ## Inline Search (Window Mode)
349
- Press `/` to activate inline search mode; the live search field is the trailing
350
- `/{regex}` on the first header line. The display filters in real-time,
351
- case-insensitively, matching any part of the process info. **Enter** commits the
352
- search; **ESC** cancels and clears it.
285
+ Press `/` to activate inline search mode; the live search field is the trailing `/{regex}` on the first header line. The display filters in real-time, case-insensitively, matching any part of the process info. **Enter** commits the search; **ESC** cancels and clears it.
353
286
 
354
287
  ## Kill Mode (Window Mode)
355
- Press `K` (on the report; on the Help screen `K` is demo mode instead) to enter
356
- "Kill Mode" where you can select and kill processes:
288
+ Press `K` (on the report; on the Help screen `K` is demo mode instead) to enter "Kill Mode" where you can select and kill processes:
357
289
  1. Use the navigation keys to highlight a row and press **Enter**
358
290
  2. An inline confirmation prompt names the process and its PID count; press **`y`** to kill the process(es) or **ESC** to cancel
359
291
  3. A brief flash message reports the result
@@ -364,10 +296,7 @@ Press `K` (on the report; on the Help screen `K` is demo mode instead) to enter
364
296
  Sometimes, the horizontal line between the header and scrollable region has a reverse video block (under the "351" in this case):
365
297
  ![scroll-pos example](https://github.com/joedefen/pmemstat/blob/main/images/scroll-pos.png?raw=true)
366
298
 
367
- Its position and length indicate how far through the document you are and how
368
- much of it is visible; with no block, the document does not overflow. Press `f`
369
- to fit the document to the screen with a "rollup" line summarizing the lines
370
- that would not fit.
299
+ Its position and length indicate how far through the document you are and how much of it is visible; with no block, the document does not overflow. Press `f` to fit the document to the screen with a "rollup" line summarizing the lines that would not fit.
371
300
 
372
301
  ## Quirks and Details
373
302
  * **pswap** comes only from `smaps_rollup`, so it may be slightly out of sync with the `smaps` data.
@@ -27,26 +27,23 @@ Without `-o`, `pmemstat` is much faster but less detailed (it omits classes such
27
27
  Grouping rolls up the resources of multiple processes of one feature (e.g. a browser) so its total memory/CPU impact is apparent. Looping reveals growth that may be a leak, and segregating memory by type makes leaks easier to identify.
28
28
 
29
29
  ## How `pmemstat` Compares to Other Tools
30
- Reach for `top`/`ps` when you need a tool that is always installed, and `htop` for a friendly full-screen overview. `pmemstat` differs in its focus on **accurate, proportional memory**: rather than RES/RSS — which double-counts shared pages and ignores uninstantiated virtual memory — it digests `smaps`/`smaps_rollup` to attribute shared memory fairly and break memory down by type. That makes it slower to start (especially with `-o`) but far more truthful about who is really using RAM. The table compares it with its closest peers: `smem` (the other tool that derives **PSS** from `smaps`) and `systemd-cgtop` (whose per-cgroup view `pmemstat` mirrors, with proportional numbers).
31
-
32
- | Feature | `pmemstat` | `smem` | `systemd-cgtop` | `htop` |
33
- |---|---|---|---|---|
34
- | **Proportional memory (PSS)** accounting | ✓ core design | ✓ core design | ✗ (`memory.current`) | ✗ (RES, double-counts) |
35
- | **Memory-type breakdown** (shared/swap/stack/text/data) | ✓ | ✗ (USS/PSS/RSS/Swap only) | ✗ | ✗ |
36
- | **Proportional swap** per grouping | ✓ | ✗ (flat Swap column) | ✗ | ✗ (total swap only) |
37
- | **Group processes** by executable/command | ✓ aggregates PIDs into one row | ✓ by command by default | ✗ | ✗ (tree view only) |
38
- | **Group by cgroup v2** (services, scopes, containers) | ✓ (`-g cgroup`) | ✗ | ✓ (its core design) | ✗ |
39
- | **Memory-leak / growth monitoring** (annotates top-N growers; only re-shows significant growth) | ✓ (`G`, `--growth-style`, growth sort) | ✗ | ✗ | ✗ |
40
- | **zRAM-aware effective RAM** (eTot/eUsed/eAvail) | ✓ | ✗ | ✗ | ✗ |
41
- | **System pressure (PSI)** in header (memory/cpu/io, some/full) | ✓ (`-P`) | ✗ | ✗ | ✗ |
42
- | **Data source** | `/proc/{PID}/smaps*` | `/proc/{PID}/smaps` | `/sys/fs/cgroup` | `/proc` + libs |
43
- | **Interactive full-screen window** | ✓ (curses) | ✗ (one-shot) | ✓ | ✓ |
44
- | **CPU usage reporting** | ✓ | ✗ (memory only) | ✓ | ✓ |
45
- | **Kill processes** | ✓ (inline confirm) | ✗ | ✗ | ✓ |
46
- | **Inline search-as-you-type** | ✓ (`/`) | ✗ | ✗ | ✓ (F3) |
47
- | **Requires root for all-process detail** | ✓ (else only your own) | ✓ (else only your own) | ✗ | ✗ |
48
-
49
- For **per-mapped-file attribution** (which shared library or mmap'd file costs the most RAM), use `smem -m` or `pmap`; `pmemstat` deliberately stays focused on per-process and per-cgroup responsibility rather than rolling PSS up by mapped file.
30
+ Reach for `top`/`ps`/`htop` for a quick overview; `pmemstat` focuses on accurate, **proportional** memory and the sources of growth. Main features:
31
+
32
+ * Proportional PSS accounting (shared pages split fairly)
33
+ * Memory-type breakdown (shared, swap, stack, text, data)
34
+ * Proportional swap per grouping
35
+ * Group processes by executable, command, PID or cgroup v2
36
+ * Memory-leak / growth monitoring with cross-run history
37
+ * zRAM-aware effective RAM (`eTot`/`eUsed`/`eAvail`)
38
+ * System pressure (PSI) in the header
39
+ * Full-screen window: inline search, themes, kill mode
40
+
41
+ Selected competitors:
42
+ * `top` / `htop` — familiar, but no PSS or memory-type breakdown.
43
+ * `smem` — has PSS; lacks cgroup grouping, growth history and PSI.
44
+ * `systemd-cgtop` — per-cgroup view; no proportional memory or leak tracking.
45
+
46
+ For per-mapped-file attribution, use `smem -m` or `pmap`.
50
47
 
51
48
  ## Installation Options
52
49
  * `pmemstat` requires **Python 3.10 or later**.
@@ -81,8 +78,8 @@ options:
81
78
  dflt=20]
82
79
  -P, --psi show PSI (system pressure in header + memPSI% column)
83
80
  [dflt=off]
84
- --theme NAME initial colour theme (see --list-themes); "mono"
85
- disables colour (it is also the last entry in the T
81
+ --theme NAME initial color theme (see --list-themes); "mono"
82
+ disables color (it is also the last entry in the T
86
83
  picker).
87
84
  --list-themes list the available themes and exit
88
85
  -g, --groupby {exe,cmd,pid,cgroup,cgroupCharge}
@@ -137,7 +134,7 @@ Explanation of some options and arguments:
137
134
 
138
135
 
139
136
  ## Grouping by cgroup v2
140
- With `-g cgroup` (or cycling `g` in window mode) `pmemstat` groups processes by their **cgroup v2** path (read from `/proc/<pid>/cgroup`), which corresponds to systemd services/scopes and to container sandboxes. Each row is labelled with the cgroup's leaf unit name (e.g. `foo.service`), and a trailing `+` marks a cgroup that also contains descendant cgroups listed on their own rows. If the leaf name matches none of the row's member executables — common with launcher-created app scopes (e.g. niri's `app-niri-fuzzel-*.scope`, which actually host the launched app) — the row is labelled with the dominant member executable instead; the full cgroup path stays searchable with `/`.
137
+ With `-g cgroup` (or cycling `g` in window mode) `pmemstat` groups processes by their **cgroup v2** path (read from `/proc/<pid>/cgroup`), which corresponds to systemd services/scopes and to container sandboxes. Each row is labeled with the cgroup's leaf unit name (e.g. `foo.service`), and a trailing `+` marks a cgroup that also contains descendant cgroups listed on their own rows. If the leaf name matches none of the row's member executables — common with launcher-created app scopes (e.g. niri's `app-niri-fuzzel-*.scope`, which actually host the launched app) — the row is labeled with the dominant member executable instead; the full cgroup path stays searchable with `/`.
141
138
 
142
139
  There are two cgroup memory views:
143
140
  * `kcharge` - what the kernel charges, and what `memory.max` / the OOM killer act on; the number `systemd-cgtop`/`docker stats` show.
@@ -158,7 +155,7 @@ The kernel columns, read from `/sys/fs/cgroup/<path>/` in the `-u` units, decomp
158
155
 
159
156
  These columns appear only in the cgroup groupings (`-g cgroup` / `-g cgroupCharge`), and are omitted entirely when the kernel exposes no cgroup v2 data (e.g. a cgroup v1 host).
160
157
 
161
- cgroup v2 accounting is **hierarchical**: each cgroup's figures include its descendants, so a row with separately listed descendants (marked `+`) has their figures **subtracted** and shows only its own share; rows therefore add up to `TOTALS`. The unified root (`/`, labelled `(root)`) is everyone's ancestor, so a process living directly in it — as inside a container, where it may be the only cgroup visible — makes the `(root)+` row count every other row as a descendant. `memPSI%` is not totalled (`n/a` in `TOTALS` and `---- OTHERS ----`).
158
+ cgroup v2 accounting is **hierarchical**: each cgroup's figures include its descendants, so a row with separately listed descendants (marked `+`) has their figures **subtracted** and shows only its own share; rows therefore add up to `TOTALS`. The unified root (`/`, labeled `(root)`) is everyone's ancestor, so a process living directly in it — as inside a container, where it may be the only cgroup visible — makes the `(root)+` row count every other row as a descendant. `memPSI%` is not totaled (`n/a` in `TOTALS` and `---- OTHERS ----`).
162
159
 
163
160
  Reading `/proc/<pid>/cgroup` and `/sys/fs/cgroup` needs no root, so the grouping works unprivileged too (the PSS columns still reflect only the processes you can read).
164
161
 
@@ -220,107 +217,52 @@ In the default window loop we see
220
217
  * **growth** - inline growth annotation for top-N growers (e.g. `3.5G 2h3m`); only when growth mode is not `off`
221
218
  * **key/info** - **{num}x**, the number of processes in the grouping (e.g. `24x browser`), plus the grouping key; `pid` grouping rows show `1x`, the pid and the command line.
222
219
 
223
- ## Colour and Themes
224
- In window mode colour highlights titles and values that are changing; it is
225
- decoration only, so a terminal without colour (or `TERM=dumb`) still shows the
226
- full report in plain text.
220
+ ## Color and Themes
221
+ In window mode color highlights titles and values that are changing; it is decoration only, so a terminal without color (or `TERM=dumb`) still shows the full report in plain text.
227
222
 
228
- `t` opens console-window's theme picker (`ESC` returns) and `t` there cycles the
229
- appearance: the palettes, then `mono`, which turns colour off and wraps back to
230
- the first palette. A pick is applied immediately and remembered per user.
223
+ `t` opens console-window's theme picker (`ESC` returns) and `t` there cycles the appearance: the palettes, then `mono`, which turns color off and wraps back to the first palette. A pick is applied immediately and remembered per user.
231
224
 
232
- `--theme` selects a theme and `--list-themes` prints the available names.
233
- `--theme mono`, or the standard `NO_COLOR` convention, turns colour off; `mono`
234
- is the last entry in the `t` picker cycle, and there is no separate colour flag.
225
+ `--theme` selects a theme and `--list-themes` prints the available names. `--theme mono`, or the standard `NO_COLOR` convention, turns color off; `mono` is the last entry in the `t` picker cycle, and there is no separate color flag.
235
226
 
236
227
  ## Memory growth (leak) detection
237
228
 
238
- With `--growth-style` (or the `G` key in window mode) `pmemstat` annotates the
239
- groups that are growing, making slow leaks visible without scrolling history:
229
+ With `--growth-style` (or the `G` key in window mode) `pmemstat` annotates the groups that are growing, making slow leaks visible without scrolling history:
240
230
 
241
231
  ```
242
232
  5.9 270 32 291 593 3.5G 2h3m 1x firefox
243
233
  ```
244
234
 
245
- * The annotation is `{human growth} {interval}` (e.g. `3.5G 2h3m`); `rate` adds
246
- a per-day projection (`3.5G/d`) once the baseline spans at least a minute, and
247
- `growth` shows just the size.
248
- * The column's `growth` label sits on the **TOTALS** row, directly above the
249
- annotations it titles; the TOTALS row's `T` marker is dropped there (its info
250
- already reads TOTALS) and returns when growth is `off`.
251
- * Changing the grouping (`g`/`o`) rebuilds every row, which would mark them all
252
- new for one refresh. With growth `off` that `A` flash is kept (it explains the
253
- reshuffle), but in a growth mode the annotations are shown instead, from the
254
- per-view history that survives the change; a key that genuinely appears later
255
- still gets its `A`.
256
- * Growth is measured from the group's **first observation this boot** (possibly
257
- an earlier run), not merely since this invocation; a reboot resets it. This
258
- history is system-wide and **root-only**: a non-root run (`-U`) measures only
259
- from this run's start. Opt out with `--no-growth-history`,
260
- `--dont-save-growth-history`, or `PMEMSTAT_NO_HISTORY` (both).
261
- * Startup bursts age out, and growth is clamped at zero, so shrinking is not
262
- reported.
263
- * A row is annotated only if its growth (KB) is at least `-k` **and** it is
264
- among the top-N growers (`--growth-top`, default `all`; `p` cycles `all`/`10`).
265
- `-s growth` sorts by the displayed metric.
266
- * With a cgroup grouping the metric is the grouping's total (`footprt` for
267
- `-g cgroup`, `kcharge` for `-g cgroupCharge`) rather than proportional PSS.
268
- * A system-wide line beneath the leader closes the identity
269
- `ΔUsed = ΔTOTALS(ptotal) + Δ(Sh+Tmp) + ΔOth`; as **root** the residual splits
270
- into `ΔOthK`/`ΔOthU`, so kernel/driver growth is separable from userspace and
271
- tmpfs, while a non-root run shows a single `ΔOth`. The shared baseline interval
272
- trails as `[1h58m]` in every growth mode.
235
+ * The annotation is `{human growth} {interval}` (e.g. `3.5G 2h3m`); `rate` adds a per-day projection (`3.5G/d`) once the baseline spans at least a minute, and `growth` shows just the size.
236
+ * The column's `growth` label sits on the **TOTALS** row, directly above the annotations it titles; the TOTALS row's `T` marker is dropped there (its info already reads TOTALS) and returns when growth is `off`.
237
+ * Changing the grouping (`g`/`o`) rebuilds every row, which would mark them all new for one refresh. With growth `off` that `A` flash is kept (it explains the reshuffle), but in a growth mode the annotations are shown instead, from the per-view history that survives the change; a key that genuinely appears later still gets its `A`.
238
+ * Growth is measured from the group's **first observation this boot** (possibly an earlier run), not merely since this invocation; a reboot resets it. This history is system-wide and **root-only**: a non-root run (`-U`) measures only from this run's start. Opt out with `--no-growth-history`, `--dont-save-growth-history`, or `PMEMSTAT_NO_HISTORY` (both).
239
+ * Startup bursts age out, and growth is clamped at zero, so shrinking is not reported.
240
+ * A row is annotated only if its growth (KB) is at least `-k` **and** it is among the top-N growers (`--growth-top`, default `all`; `p` cycles `all`/`10`). `-s growth` sorts by the displayed metric.
241
+ * With a cgroup grouping the metric is the grouping's total (`footprt` for `-g cgroup`, `kcharge` for `-g cgroupCharge`) rather than proportional PSS.
242
+ * A system-wide line beneath the leader closes the identity `ΔUsed = ΔTOTALS(ptotal) + Δ(Sh+Tmp) + ΔOth`; as **root** the residual splits into `ΔOthK`/`ΔOthU`, so kernel/driver growth is separable from userspace and tmpfs, while a non-root run shows a single `ΔOth`. The shared baseline interval trails as `[1h58m]` in every growth mode.
273
243
 
274
244
  ## Updating History from Cron / Startup
275
- `pmemstat --save-history-now` performs one silent scan, saves the current
276
- history and exits (`0` on success, `1` on failure with a message on stderr). It
277
- runs as root (elevating via `sudo` if needed) and ignores all other options and
278
- `PMEMSTAT_ARGS`, so it is safe from cron or a startup unit. Run it as the user
279
- whose history you want to update.
280
-
281
- `pmemstat --reset-history-now` scans the same way but **replaces** the saved
282
- history rather than merging: current values become the new baseline, as if the
283
- tool had first run just after boot. It likewise runs as root and ignores other
284
- options. Inside the window, `z` performs the same reset (only as root while the
285
- growth annotation is on), asking for `y`/`Y` confirmation first; `ESC` or 10
286
- seconds declines.
245
+ `pmemstat --save-history-now` performs one silent scan, saves the current history and exits (`0` on success, `1` on failure with a message on stderr). It runs as root (elevating via `sudo` if needed) and ignores all other options and `PMEMSTAT_ARGS`, so it is safe from cron or a startup unit. Run it as the user whose history you want to update.
246
+
247
+ `pmemstat --reset-history-now` scans the same way but **replaces** the saved history rather than merging: current values become the new baseline, as if the tool had first run just after boot. It likewise runs as root and ignores other options. Inside the window, `z` performs the same reset (only as root while the growth annotation is on), asking for `y`/`Y` confirmation first; `ESC` or 10 seconds declines.
287
248
 
288
249
  ## Key Legend (Window Mode)
289
- The top line of the header is an always-visible key legend with the live search
290
- field appended, so the available keys are in evidence without opening the help
291
- screen:
250
+ The top line of the header is an always-visible key legend with the live search field appended, so the available keys are in evidence without opening the help screen:
292
251
 
293
252
  ?:help group units sort cpu Kill PSI Growth /{regex}
294
253
 
295
- `?` opens the complete list of keys plus the navigation keys (press it again, or
296
- `ESC`, to return). `zap` is appended for a root run while the growth annotation
297
- is showing, since resetting the baseline has no visible effect otherwise.
254
+ `?` opens the complete list of keys plus the navigation keys (press it again, or `ESC`, to return). `zap` is appended for a root run while the growth annotation is showing, since resetting the baseline has no visible effect otherwise.
298
255
 
299
256
  ## Help Screen (in Window Mode, Press '?')
300
- In window mode, `?` opens the help screen (and closes it again); **ESC** also
301
- closes it. The navigation legend is at the top and, below the line, the option
302
- keys for the screen you came from with their possible values (the current choice
303
- is highlighted). Typing an option key (e.g. `c`) advances to the next value,
304
- applied on the next loop; the option keys also work directly on the main screen
305
- without opening the help screen. `t` opens the theme picker (where `t` cycles
306
- the appearance), and `K` on this screen toggles **demo mode**, which shows the
307
- last key pressed — handy for screencasts. **ENTER** closes nothing here — it
308
- stays reserved for kill mode's row selection.
309
-
310
- The first help page of a run also carries a **Fonts** section: the named
311
- one-cell symbols and the emoji are drawn as fixed-width blocks, so a terminal
312
- missing a glyph or shifting a wide character shows up as a visibly broken row
313
- rather than a silently misaligned report.
257
+ In window mode, `?` opens the help screen (and closes it again); **ESC** also closes it. The navigation legend is at the top and, below the line, the option keys for the screen you came from with their possible values (the current choice is highlighted). Typing an option key (e.g. `c`) advances to the next value, applied on the next loop; the option keys also work directly on the main screen without opening the help screen. `t` opens the theme picker (where `t` cycles the appearance), and `K` on this screen toggles **demo mode**, which shows the last key pressed — handy for screencasts. **ENTER** closes nothing here — it stays reserved for kill mode's row selection.
258
+
259
+ The first help page of a run also carries a **Fonts** section: the named one-cell symbols and the emoji are drawn as fixed-width blocks, so a terminal missing a glyph or shifting a wide character shows up as a visibly broken row rather than a silently misaligned report.
314
260
 
315
261
  ## Inline Search (Window Mode)
316
- Press `/` to activate inline search mode; the live search field is the trailing
317
- `/{regex}` on the first header line. The display filters in real-time,
318
- case-insensitively, matching any part of the process info. **Enter** commits the
319
- search; **ESC** cancels and clears it.
262
+ Press `/` to activate inline search mode; the live search field is the trailing `/{regex}` on the first header line. The display filters in real-time, case-insensitively, matching any part of the process info. **Enter** commits the search; **ESC** cancels and clears it.
320
263
 
321
264
  ## Kill Mode (Window Mode)
322
- Press `K` (on the report; on the Help screen `K` is demo mode instead) to enter
323
- "Kill Mode" where you can select and kill processes:
265
+ Press `K` (on the report; on the Help screen `K` is demo mode instead) to enter "Kill Mode" where you can select and kill processes:
324
266
  1. Use the navigation keys to highlight a row and press **Enter**
325
267
  2. An inline confirmation prompt names the process and its PID count; press **`y`** to kill the process(es) or **ESC** to cancel
326
268
  3. A brief flash message reports the result
@@ -331,10 +273,7 @@ Press `K` (on the report; on the Help screen `K` is demo mode instead) to enter
331
273
  Sometimes, the horizontal line between the header and scrollable region has a reverse video block (under the "351" in this case):
332
274
  ![scroll-pos example](https://github.com/joedefen/pmemstat/blob/main/images/scroll-pos.png?raw=true)
333
275
 
334
- Its position and length indicate how far through the document you are and how
335
- much of it is visible; with no block, the document does not overflow. Press `f`
336
- to fit the document to the screen with a "rollup" line summarizing the lines
337
- that would not fit.
276
+ Its position and length indicate how far through the document you are and how much of it is visible; with no block, the document does not overflow. Press `f` to fit the document to the screen with a "rollup" line summarizing the lines that would not fit.
338
277
 
339
278
  ## Quirks and Details
340
279
  * **pswap** comes only from `smaps_rollup`, so it may be slightly out of sync with the `smaps` data.
@@ -1,24 +1,12 @@
1
1
  #!/usr/bin/env python3
2
- """Read authoritative Linux cgroup v2 accounting.
3
-
4
- This module is intentionally dependency-free (standard library only) so that it
5
- can be imported and unit-tested without the curses UI or the pinned
6
- ``console-window`` package.
7
-
8
- Two independent capabilities are provided:
9
-
2
+ """Read cgroup v2 accounting.
10
3
  1. Parsing a process's membership from ``/proc/<pid>/cgroup``
11
- (:func:`parse_cgroup_lines` and :func:`cgroup_leaf`).
12
- 2. Reading the kernel's authoritative accounting for a cgroup directory
13
- (:class:`CGroup`): ``memory.current``, ``memory.stat`` and
14
- ``memory.pressure``.
15
-
16
- The numbers from ``memory.current``/``memory.stat`` are *not* proportional
17
- (PSS). They are the kernel's own per-cgroup accounting and are displayed
18
- alongside pmemstat's proportional PSS numbers so the two can be compared.
4
+ 2. Reading the kernel's accounting for a cgroup directory
5
+ ``memory.stat`` and ``memory.pressure``.
6
+
7
+ The numbers from ``memory.current``/``memory.stat`` are *not* proportional (PSS),
8
+ but they are displayed alongside PSS numbers for comparison.
19
9
  """
20
- # CamelCase module name matches the package style (CpuSmooth, KillThem).
21
- # pylint: disable=invalid-name
22
10
 
23
11
  import os
24
12
  import re
@@ -29,12 +17,9 @@ from pmemstat.Pressure import parse_pressure
29
17
  def parse_cgroup_lines(lines):
30
18
  """Return the cgroup v2 (unified) path for a process.
31
19
 
32
- ``lines`` is the content of ``/proc/<pid>/cgroup`` split into lines, each
33
- of the form ``<hierarchy>:<controllers>:<path>``.
34
-
35
- The cgroup v2 unified hierarchy is identified by a ``0::`` prefix (no
36
- controllers). ``None`` is returned when no unified line is present, which
37
- is the case on a cgroup v1-only system.
20
+ ``lines`` is ``/proc/<pid>/cgroup`` split ``<hierarchy>:<controllers>:<path>``.
21
+ The cgroup v2 identified by a ``0::`` prefix (no controllers).
22
+ ``None`` is returned when not v2.
38
23
  """
39
24
  for line in lines:
40
25
  parts = line.split(':', 2)
@@ -53,9 +38,8 @@ _XESCAPE_PAT = re.compile(r'\\x([0-9a-fA-F]{2})')
53
38
  def decode_cgroup_name(name):
54
39
  """Decode the ``\\xNN`` escaping systemd applies to cgroup names.
55
40
 
56
- systemd escapes characters such as ``-`` as ``\\x2d`` inside cgroup paths
57
- (e.g. ``app-foo\\x2dbar.service``). Decoding affects only the *displayed*
58
- label; grouping always uses the raw, unambiguous path.
41
+ - systemd escapes chars such as ``-`` as ``\\x2d`` inside cgroup paths
42
+ - Decoding beautifies the *displayed* label; grouping uses the raw path.
59
43
  """
60
44
  if not name:
61
45
  return name
@@ -63,12 +47,7 @@ def decode_cgroup_name(name):
63
47
 
64
48
 
65
49
  def cgroup_leaf(path):
66
- """Return a short, human-friendly label for a cgroup path.
67
-
68
- The label is the final path component, which for systemd is the unit name
69
- (e.g. ``foo.service``). The unified root ``/`` is reported as ``(root)``
70
- and systemd's ``\\xNN`` escapes are decoded for readability.
71
- """
50
+ """Return a short, human-friendly label for a cgroup path (last path component)."""
72
51
  if not path or path == '/':
73
52
  return '(root)'
74
53
  leaf = path.rstrip('/').rsplit('/', 1)[-1]
@@ -98,14 +77,7 @@ def parse_memory_stat(lines):
98
77
 
99
78
 
100
79
  def parse_memory_pressure(lines):
101
- """Parse ``memory.pressure`` into ``{'some': {...}, 'full': {...}}``.
102
-
103
- ``avg*`` values are floats (percent) and ``total`` is an int
104
- (microseconds).
105
-
106
- All PSI files share one grammar, so this is a thin compatibility wrapper
107
- around :func:`pmemstat.Pressure.parse_pressure`.
108
- """
80
+ """Parse ``memory.pressure`` into ``{'some': {...}, 'full': {...}}``."""
109
81
  return parse_pressure(lines)
110
82
 
111
83
 
@@ -121,14 +93,7 @@ def has_descendant(keys, key):
121
93
 
122
94
 
123
95
  def local_values(raw_by_key, columns):
124
- """Convert hierarchical (raw) per-key values into per-key local values.
125
-
126
- ``raw_by_key`` maps a cgroup key to a dict of column values, as read from
127
- the kernel (each value already includes descendant cgroups). A key's
128
- *local* value for a column is its raw value minus the raw values of its
129
- descendant keys, i.e. that cgroup's own share. Returns
130
- ``{key: {column: local}}`` for the keys given.
131
- """
96
+ """Convert hierarchical (raw) per-key values into per-key local values."""
132
97
  keys = list(raw_by_key)
133
98
  result = {}
134
99
  for key in keys:
@@ -145,12 +110,10 @@ def local_values(raw_by_key, columns):
145
110
 
146
111
 
147
112
  class CGroup:
148
- """Authoritative cgroup v2 memory accounting for one cgroup path.
113
+ """Kernel cgroup v2 memory accounting for one cgroup path.
149
114
 
150
- ``path`` is the unified-hierarchy path as reported by
151
- :func:`parse_cgroup_lines` (e.g. ``/system.slice/foo.service``). The
152
- :attr:`root` attribute is the cgroup v2 mount point and is overridable,
153
- which makes the class trivial to unit-test against a temporary directory.
115
+ - ``path`` is that by :func:`parse_cgroup_lines`;e.g. ``/system.slice/foo.service``
116
+ - The :attr:`root` attribute is the cgroup v2 mount point and is overridable.
154
117
  """
155
118
 
156
119
  root = '/sys/fs/cgroup'
@@ -195,9 +158,7 @@ class CGroup:
195
158
  def read(self):
196
159
  """Read all supported files at once.
197
160
 
198
- Returns a dict with keys ``current``, ``stat`` and ``pressure``. Any
199
- of them may be ``None``/empty when the underlying file is
200
- unavailable (older kernel, cgroup v1, or insufficient permission).
161
+ Returns dict of ``current``, ``stat`` and ``pressure`` (each possibly None)
201
162
  """
202
163
  return {
203
164
  'current': self.read_current(),