statblk 1.45__tar.gz → 1.52__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.
- {statblk-1.45 → statblk-1.52}/PKG-INFO +32 -7
- {statblk-1.45 → statblk-1.52}/README.md +31 -6
- {statblk-1.45 → statblk-1.52}/statblk.egg-info/PKG-INFO +32 -7
- {statblk-1.45 → statblk-1.52}/statblk.egg-info/SOURCES.txt +3 -1
- {statblk-1.45 → statblk-1.52}/statblk.py +228 -68
- statblk-1.52/tests/test_check.py +166 -0
- {statblk-1.45 → statblk-1.52}/tests/test_cli.py +21 -5
- {statblk-1.45 → statblk-1.52}/tests/test_drives_info.py +101 -1
- {statblk-1.45 → statblk-1.52}/tests/test_macos.py +19 -0
- {statblk-1.45 → statblk-1.52}/tests/test_parse.py +18 -0
- statblk-1.52/tests/test_watch.py +92 -0
- {statblk-1.45 → statblk-1.52}/setup.cfg +0 -0
- {statblk-1.45 → statblk-1.52}/setup.py +0 -0
- {statblk-1.45 → statblk-1.52}/statblk.egg-info/dependency_links.txt +0 -0
- {statblk-1.45 → statblk-1.52}/statblk.egg-info/entry_points.txt +0 -0
- {statblk-1.45 → statblk-1.52}/statblk.egg-info/requires.txt +0 -0
- {statblk-1.45 → statblk-1.52}/statblk.egg-info/top_level.txt +0 -0
- {statblk-1.45 → statblk-1.52}/tests/test_doctest_module.py +0 -0
- {statblk-1.45 → statblk-1.52}/tests/test_fsuse.py +0 -0
- {statblk-1.45 → statblk-1.52}/tests/test_live.py +0 -0
- {statblk-1.45 → statblk-1.52}/tests/test_multicmd_import.py +0 -0
- {statblk-1.45 → statblk-1.52}/tests/test_sysfs_helpers.py +0 -0
- {statblk-1.45 → statblk-1.52}/tests/test_throughput.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: statblk
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.52
|
|
4
4
|
Summary: Gather essential disk and partition info for block devices and print it in a nice table
|
|
5
5
|
Home-page: https://github.com/yufei-pan/statblk
|
|
6
6
|
Author: Yufei Pan
|
|
@@ -77,7 +77,7 @@ By default every column that has data is shown (a column that is empty for every
|
|
|
77
77
|
| `SIZE` | Device or filesystem size |
|
|
78
78
|
| `FSUSE%` | Filesystem space used (mounted entries); `TIMEOUT` for a mount that didn't answer (e.g. dead NFS server) |
|
|
79
79
|
| `MOUNTPOINT` | Mount path |
|
|
80
|
-
| `SMART` | SMART health
|
|
80
|
+
| `SMART` | SMART health: `OK`, `STANDBY` (spun-down drive, not woken), a failure such as `FAILED!`, `TIMEOUT` (smartctl stuck), or why it couldn't be read (`NO SMARTCTL`, `DENIED`, `UNKNOWN`). Blank for devices without SMART (loop, dm, md, zram, nbd) |
|
|
81
81
|
| `LABEL` | Volume label |
|
|
82
82
|
| `UUID` | Filesystem UUID |
|
|
83
83
|
| `MODEL` | Drive model (from udev via `lsblk`, sysfs fallback) |
|
|
@@ -116,29 +116,35 @@ Use `-o` / `--output` to select columns (comma-separated) or `-x` / `--exclude`
|
|
|
116
116
|
| `-A`, `-ao`, `--active_only` | Only devices with read/write activity |
|
|
117
117
|
| `-P`, `--pseudo` | Include pseudo filesystems (tmpfs, nfs, cifs, …) |
|
|
118
118
|
| `--show_zero_size_devices` | Include zero-size devices |
|
|
119
|
+
| `--show_squashfs` | Include squashfs images on loop devices (snaps, AppImages), hidden by default |
|
|
119
120
|
|
|
120
121
|
### Runtime
|
|
121
122
|
|
|
122
123
|
| Flag | Description |
|
|
123
124
|
|------|-------------|
|
|
124
|
-
| `-t`, `--timeout` | Time budget per refresh in seconds for `lsblk`, `smartctl` and `statvfs` (default: 2) |
|
|
125
|
-
| `-w`, `--watch SECONDS` | Repeat output every SECONDS (watch mode) |
|
|
125
|
+
| `-t`, `--timeout` | Time budget per refresh in seconds for `lsblk`, `smartctl` and `statvfs` (default: 2; fractions allowed) |
|
|
126
|
+
| `-w`, `--watch SECONDS` | Repeat output every SECONDS (watch mode; fractions allowed, e.g. `0.5`) |
|
|
127
|
+
| `--check` | Health check: print only problem rows and exit 1, or print nothing and exit 0 (see [Health check](#health-check)) |
|
|
128
|
+
| `--max_use PCT` | FSUSE% at or above which `--check` reports a filesystem (default: 90) |
|
|
126
129
|
| `--sudo` | Run external commands via `sudo` (needed for SMART on many systems). `smartctl` is also looked up in `/usr/sbin`, `/sbin`, `/usr/local/sbin` when it isn't on `PATH` |
|
|
127
130
|
| `--debug` | Print suppressed exceptions to stderr |
|
|
128
131
|
| `-V`, `--version` | Show version and exit |
|
|
129
132
|
|
|
130
133
|
### Watch mode
|
|
131
134
|
|
|
132
|
-
Prefer `-w` / `--watch
|
|
135
|
+
Prefer `-w` / `--watch`, which also takes fractions. A trailing integer positional still works the same as before (whole seconds only, so a pattern like `0.5` stays a filter):
|
|
133
136
|
|
|
134
137
|
```bash
|
|
135
138
|
statblk -w 5 # update every 5 seconds
|
|
139
|
+
statblk -w 0.5 # twice a second
|
|
136
140
|
statblk 5 # same (trailing integer)
|
|
137
141
|
statblk sda 3 # filter to sda, refresh every 3 seconds
|
|
138
142
|
statblk -w 3 sda # same with explicit flag (flag wins if both are given)
|
|
139
143
|
```
|
|
140
144
|
|
|
141
|
-
|
|
145
|
+
Each table refresh starts with a `watch(1)`-style header, `Every 2s on <hostname>: <date time>`. On a terminal the screen is redrawn in place; when output is piped or redirected every refresh is kept, so the log reads top to bottom. With `-j` / `-J`, watch mode prints one compact JSON document per line (NDJSON) so a reader can parse each refresh as it arrives; single-run JSON stays indented.
|
|
146
|
+
|
|
147
|
+
After the first refresh, `--active_only` is enabled automatically on Linux so only busy devices are shown, unless you gave filter patterns: devices you named stay on screen even while idle (not on macOS, where throughput isn't available; `-A` still forces it). Each refresh re-reads mounts, labels, UUIDs, sizes, and per-drive sysfs info such as model/serial, so hot-swapped drives show up correctly (throughput iterators stay live across refreshes). Press Ctrl-C to stop (exit status 130).
|
|
142
148
|
|
|
143
149
|
If a filter pattern looks like a number, append `0` so it is not treated as the refresh interval (or use `-w` and keep the number as a filter):
|
|
144
150
|
|
|
@@ -147,13 +153,32 @@ statblk nvme0 0 # match nvme0, single run (no watch)
|
|
|
147
153
|
statblk -w 0 nvme0 # same via flag
|
|
148
154
|
```
|
|
149
155
|
|
|
156
|
+
### Health check
|
|
157
|
+
|
|
158
|
+
`--check` runs once and prints only the rows that need attention; when everything is healthy it prints nothing, so cron only mails on trouble. Exit status:
|
|
159
|
+
|
|
160
|
+
| Exit | Meaning |
|
|
161
|
+
|------|---------|
|
|
162
|
+
| `0` | Healthy (nothing printed). A `STANDBY` drive counts as healthy: it is checked on the next run that finds it awake |
|
|
163
|
+
| `1` | Problem: `FSUSE%` at or above `--max_use` (default 90) or `TIMEOUT` (hung mount), or `SMART` reporting a failure — `FAILED!`, a vendor failure string, or `TIMEOUT` (smartctl stuck on the disk) |
|
|
164
|
+
| `3` | Unknown: no problem found, but SMART couldn't be read on a disk — `NO SMARTCTL` (install smartmontools), `DENIED` (run as root or with `--sudo`) or `UNKNOWN` (no verdict, e.g. a disk behind a RAID controller) |
|
|
165
|
+
|
|
166
|
+
A problem beats an unknown, and both kinds of rows are listed. Exit `3` exists so that "not checked" never looks like "healthy" in a sweep. For a space-only check use `-x SMART`; to skip a device that has no SMART at all (an SD card, a USB stick) filter it out, e.g. `statblk --check -D -v mmcblk`. `FSUSE%` and `SMART` are always added to the shown columns so you can see why a row failed; excluding one with `-x` turns that check off. Filters (`-M`, `-B`, patterns) and JSON output (`-j` / `-J`) work as usual, but filters narrow what is checked: `-M` and patterns skip disks with no mount of their own (md/LVM/ZFS/Ceph members, extra btrfs pool devices), so cluster sweeps should run plain `--check`. `--check` can't be combined with watch mode.
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
statblk --check || mail -s "disk alert on $(hostname)" ops@example.com # cron
|
|
170
|
+
statblk --check -x SMART --max_use 80 # space only
|
|
171
|
+
mssh 'nodes[1-64]' 'statblk --check' # whole cluster via multiSSH3
|
|
172
|
+
```
|
|
173
|
+
|
|
150
174
|
## Platform notes
|
|
151
175
|
|
|
152
176
|
### Linux
|
|
153
177
|
|
|
154
178
|
Uses sysfs, `/proc/self/mountinfo`, `lsblk`, and optionally `smartctl`.
|
|
155
179
|
|
|
156
|
-
- **SMART** requires `smartctl` (smartmontools). Use `--sudo` if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd).
|
|
180
|
+
- **SMART** requires `smartctl` (smartmontools). Use `--sudo` if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd). smartctl runs with `-n standby`, so spun-down drives are not woken (not even by watch mode); they show `STANDBY` until they're next awake. This is verified for SATA drives on the kernel's libata driver; drives behind USB enclosures or some RAID/SAS controllers may still spin up, because smartctl's device-type probe goes through the bridge. On a hardware disk where SMART can't be read the column says why (`NO SMARTCTL`, `DENIED`, `UNKNOWN`); it is blank for virtual devices.
|
|
181
|
+
- **squashfs on loop devices** (snap packages, AppImages) is hidden by default: these images are read-only and always 100% full. Use `--show_squashfs` to list them. Other loop devices, such as a mounted disk image, are always shown.
|
|
157
182
|
- **autofs** trigger mounts are ignored (stat-ing them would trigger the automount); the real filesystem appears once mounted.
|
|
158
183
|
- **READ / WRITE** throughput comes from `/sys/class/block/*/stat` (always 512-byte sector units).
|
|
159
184
|
- On a single-shot run (and the first row of watch mode), READ/WRITE are a lifetime busy-time average (bytes / time spent in I/O since boot). In watch mode, later refreshes are interval rates over the sleep period (Δbytes / wall clock).
|
|
@@ -48,7 +48,7 @@ By default every column that has data is shown (a column that is empty for every
|
|
|
48
48
|
| `SIZE` | Device or filesystem size |
|
|
49
49
|
| `FSUSE%` | Filesystem space used (mounted entries); `TIMEOUT` for a mount that didn't answer (e.g. dead NFS server) |
|
|
50
50
|
| `MOUNTPOINT` | Mount path |
|
|
51
|
-
| `SMART` | SMART health
|
|
51
|
+
| `SMART` | SMART health: `OK`, `STANDBY` (spun-down drive, not woken), a failure such as `FAILED!`, `TIMEOUT` (smartctl stuck), or why it couldn't be read (`NO SMARTCTL`, `DENIED`, `UNKNOWN`). Blank for devices without SMART (loop, dm, md, zram, nbd) |
|
|
52
52
|
| `LABEL` | Volume label |
|
|
53
53
|
| `UUID` | Filesystem UUID |
|
|
54
54
|
| `MODEL` | Drive model (from udev via `lsblk`, sysfs fallback) |
|
|
@@ -87,29 +87,35 @@ Use `-o` / `--output` to select columns (comma-separated) or `-x` / `--exclude`
|
|
|
87
87
|
| `-A`, `-ao`, `--active_only` | Only devices with read/write activity |
|
|
88
88
|
| `-P`, `--pseudo` | Include pseudo filesystems (tmpfs, nfs, cifs, …) |
|
|
89
89
|
| `--show_zero_size_devices` | Include zero-size devices |
|
|
90
|
+
| `--show_squashfs` | Include squashfs images on loop devices (snaps, AppImages), hidden by default |
|
|
90
91
|
|
|
91
92
|
### Runtime
|
|
92
93
|
|
|
93
94
|
| Flag | Description |
|
|
94
95
|
|------|-------------|
|
|
95
|
-
| `-t`, `--timeout` | Time budget per refresh in seconds for `lsblk`, `smartctl` and `statvfs` (default: 2) |
|
|
96
|
-
| `-w`, `--watch SECONDS` | Repeat output every SECONDS (watch mode) |
|
|
96
|
+
| `-t`, `--timeout` | Time budget per refresh in seconds for `lsblk`, `smartctl` and `statvfs` (default: 2; fractions allowed) |
|
|
97
|
+
| `-w`, `--watch SECONDS` | Repeat output every SECONDS (watch mode; fractions allowed, e.g. `0.5`) |
|
|
98
|
+
| `--check` | Health check: print only problem rows and exit 1, or print nothing and exit 0 (see [Health check](#health-check)) |
|
|
99
|
+
| `--max_use PCT` | FSUSE% at or above which `--check` reports a filesystem (default: 90) |
|
|
97
100
|
| `--sudo` | Run external commands via `sudo` (needed for SMART on many systems). `smartctl` is also looked up in `/usr/sbin`, `/sbin`, `/usr/local/sbin` when it isn't on `PATH` |
|
|
98
101
|
| `--debug` | Print suppressed exceptions to stderr |
|
|
99
102
|
| `-V`, `--version` | Show version and exit |
|
|
100
103
|
|
|
101
104
|
### Watch mode
|
|
102
105
|
|
|
103
|
-
Prefer `-w` / `--watch
|
|
106
|
+
Prefer `-w` / `--watch`, which also takes fractions. A trailing integer positional still works the same as before (whole seconds only, so a pattern like `0.5` stays a filter):
|
|
104
107
|
|
|
105
108
|
```bash
|
|
106
109
|
statblk -w 5 # update every 5 seconds
|
|
110
|
+
statblk -w 0.5 # twice a second
|
|
107
111
|
statblk 5 # same (trailing integer)
|
|
108
112
|
statblk sda 3 # filter to sda, refresh every 3 seconds
|
|
109
113
|
statblk -w 3 sda # same with explicit flag (flag wins if both are given)
|
|
110
114
|
```
|
|
111
115
|
|
|
112
|
-
|
|
116
|
+
Each table refresh starts with a `watch(1)`-style header, `Every 2s on <hostname>: <date time>`. On a terminal the screen is redrawn in place; when output is piped or redirected every refresh is kept, so the log reads top to bottom. With `-j` / `-J`, watch mode prints one compact JSON document per line (NDJSON) so a reader can parse each refresh as it arrives; single-run JSON stays indented.
|
|
117
|
+
|
|
118
|
+
After the first refresh, `--active_only` is enabled automatically on Linux so only busy devices are shown, unless you gave filter patterns: devices you named stay on screen even while idle (not on macOS, where throughput isn't available; `-A` still forces it). Each refresh re-reads mounts, labels, UUIDs, sizes, and per-drive sysfs info such as model/serial, so hot-swapped drives show up correctly (throughput iterators stay live across refreshes). Press Ctrl-C to stop (exit status 130).
|
|
113
119
|
|
|
114
120
|
If a filter pattern looks like a number, append `0` so it is not treated as the refresh interval (or use `-w` and keep the number as a filter):
|
|
115
121
|
|
|
@@ -118,13 +124,32 @@ statblk nvme0 0 # match nvme0, single run (no watch)
|
|
|
118
124
|
statblk -w 0 nvme0 # same via flag
|
|
119
125
|
```
|
|
120
126
|
|
|
127
|
+
### Health check
|
|
128
|
+
|
|
129
|
+
`--check` runs once and prints only the rows that need attention; when everything is healthy it prints nothing, so cron only mails on trouble. Exit status:
|
|
130
|
+
|
|
131
|
+
| Exit | Meaning |
|
|
132
|
+
|------|---------|
|
|
133
|
+
| `0` | Healthy (nothing printed). A `STANDBY` drive counts as healthy: it is checked on the next run that finds it awake |
|
|
134
|
+
| `1` | Problem: `FSUSE%` at or above `--max_use` (default 90) or `TIMEOUT` (hung mount), or `SMART` reporting a failure — `FAILED!`, a vendor failure string, or `TIMEOUT` (smartctl stuck on the disk) |
|
|
135
|
+
| `3` | Unknown: no problem found, but SMART couldn't be read on a disk — `NO SMARTCTL` (install smartmontools), `DENIED` (run as root or with `--sudo`) or `UNKNOWN` (no verdict, e.g. a disk behind a RAID controller) |
|
|
136
|
+
|
|
137
|
+
A problem beats an unknown, and both kinds of rows are listed. Exit `3` exists so that "not checked" never looks like "healthy" in a sweep. For a space-only check use `-x SMART`; to skip a device that has no SMART at all (an SD card, a USB stick) filter it out, e.g. `statblk --check -D -v mmcblk`. `FSUSE%` and `SMART` are always added to the shown columns so you can see why a row failed; excluding one with `-x` turns that check off. Filters (`-M`, `-B`, patterns) and JSON output (`-j` / `-J`) work as usual, but filters narrow what is checked: `-M` and patterns skip disks with no mount of their own (md/LVM/ZFS/Ceph members, extra btrfs pool devices), so cluster sweeps should run plain `--check`. `--check` can't be combined with watch mode.
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
statblk --check || mail -s "disk alert on $(hostname)" ops@example.com # cron
|
|
141
|
+
statblk --check -x SMART --max_use 80 # space only
|
|
142
|
+
mssh 'nodes[1-64]' 'statblk --check' # whole cluster via multiSSH3
|
|
143
|
+
```
|
|
144
|
+
|
|
121
145
|
## Platform notes
|
|
122
146
|
|
|
123
147
|
### Linux
|
|
124
148
|
|
|
125
149
|
Uses sysfs, `/proc/self/mountinfo`, `lsblk`, and optionally `smartctl`.
|
|
126
150
|
|
|
127
|
-
- **SMART** requires `smartctl` (smartmontools). Use `--sudo` if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd).
|
|
151
|
+
- **SMART** requires `smartctl` (smartmontools). Use `--sudo` if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd). smartctl runs with `-n standby`, so spun-down drives are not woken (not even by watch mode); they show `STANDBY` until they're next awake. This is verified for SATA drives on the kernel's libata driver; drives behind USB enclosures or some RAID/SAS controllers may still spin up, because smartctl's device-type probe goes through the bridge. On a hardware disk where SMART can't be read the column says why (`NO SMARTCTL`, `DENIED`, `UNKNOWN`); it is blank for virtual devices.
|
|
152
|
+
- **squashfs on loop devices** (snap packages, AppImages) is hidden by default: these images are read-only and always 100% full. Use `--show_squashfs` to list them. Other loop devices, such as a mounted disk image, are always shown.
|
|
128
153
|
- **autofs** trigger mounts are ignored (stat-ing them would trigger the automount); the real filesystem appears once mounted.
|
|
129
154
|
- **READ / WRITE** throughput comes from `/sys/class/block/*/stat` (always 512-byte sector units).
|
|
130
155
|
- On a single-shot run (and the first row of watch mode), READ/WRITE are a lifetime busy-time average (bytes / time spent in I/O since boot). In watch mode, later refreshes are interval rates over the sleep period (Δbytes / wall clock).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: statblk
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.52
|
|
4
4
|
Summary: Gather essential disk and partition info for block devices and print it in a nice table
|
|
5
5
|
Home-page: https://github.com/yufei-pan/statblk
|
|
6
6
|
Author: Yufei Pan
|
|
@@ -77,7 +77,7 @@ By default every column that has data is shown (a column that is empty for every
|
|
|
77
77
|
| `SIZE` | Device or filesystem size |
|
|
78
78
|
| `FSUSE%` | Filesystem space used (mounted entries); `TIMEOUT` for a mount that didn't answer (e.g. dead NFS server) |
|
|
79
79
|
| `MOUNTPOINT` | Mount path |
|
|
80
|
-
| `SMART` | SMART health
|
|
80
|
+
| `SMART` | SMART health: `OK`, `STANDBY` (spun-down drive, not woken), a failure such as `FAILED!`, `TIMEOUT` (smartctl stuck), or why it couldn't be read (`NO SMARTCTL`, `DENIED`, `UNKNOWN`). Blank for devices without SMART (loop, dm, md, zram, nbd) |
|
|
81
81
|
| `LABEL` | Volume label |
|
|
82
82
|
| `UUID` | Filesystem UUID |
|
|
83
83
|
| `MODEL` | Drive model (from udev via `lsblk`, sysfs fallback) |
|
|
@@ -116,29 +116,35 @@ Use `-o` / `--output` to select columns (comma-separated) or `-x` / `--exclude`
|
|
|
116
116
|
| `-A`, `-ao`, `--active_only` | Only devices with read/write activity |
|
|
117
117
|
| `-P`, `--pseudo` | Include pseudo filesystems (tmpfs, nfs, cifs, …) |
|
|
118
118
|
| `--show_zero_size_devices` | Include zero-size devices |
|
|
119
|
+
| `--show_squashfs` | Include squashfs images on loop devices (snaps, AppImages), hidden by default |
|
|
119
120
|
|
|
120
121
|
### Runtime
|
|
121
122
|
|
|
122
123
|
| Flag | Description |
|
|
123
124
|
|------|-------------|
|
|
124
|
-
| `-t`, `--timeout` | Time budget per refresh in seconds for `lsblk`, `smartctl` and `statvfs` (default: 2) |
|
|
125
|
-
| `-w`, `--watch SECONDS` | Repeat output every SECONDS (watch mode) |
|
|
125
|
+
| `-t`, `--timeout` | Time budget per refresh in seconds for `lsblk`, `smartctl` and `statvfs` (default: 2; fractions allowed) |
|
|
126
|
+
| `-w`, `--watch SECONDS` | Repeat output every SECONDS (watch mode; fractions allowed, e.g. `0.5`) |
|
|
127
|
+
| `--check` | Health check: print only problem rows and exit 1, or print nothing and exit 0 (see [Health check](#health-check)) |
|
|
128
|
+
| `--max_use PCT` | FSUSE% at or above which `--check` reports a filesystem (default: 90) |
|
|
126
129
|
| `--sudo` | Run external commands via `sudo` (needed for SMART on many systems). `smartctl` is also looked up in `/usr/sbin`, `/sbin`, `/usr/local/sbin` when it isn't on `PATH` |
|
|
127
130
|
| `--debug` | Print suppressed exceptions to stderr |
|
|
128
131
|
| `-V`, `--version` | Show version and exit |
|
|
129
132
|
|
|
130
133
|
### Watch mode
|
|
131
134
|
|
|
132
|
-
Prefer `-w` / `--watch
|
|
135
|
+
Prefer `-w` / `--watch`, which also takes fractions. A trailing integer positional still works the same as before (whole seconds only, so a pattern like `0.5` stays a filter):
|
|
133
136
|
|
|
134
137
|
```bash
|
|
135
138
|
statblk -w 5 # update every 5 seconds
|
|
139
|
+
statblk -w 0.5 # twice a second
|
|
136
140
|
statblk 5 # same (trailing integer)
|
|
137
141
|
statblk sda 3 # filter to sda, refresh every 3 seconds
|
|
138
142
|
statblk -w 3 sda # same with explicit flag (flag wins if both are given)
|
|
139
143
|
```
|
|
140
144
|
|
|
141
|
-
|
|
145
|
+
Each table refresh starts with a `watch(1)`-style header, `Every 2s on <hostname>: <date time>`. On a terminal the screen is redrawn in place; when output is piped or redirected every refresh is kept, so the log reads top to bottom. With `-j` / `-J`, watch mode prints one compact JSON document per line (NDJSON) so a reader can parse each refresh as it arrives; single-run JSON stays indented.
|
|
146
|
+
|
|
147
|
+
After the first refresh, `--active_only` is enabled automatically on Linux so only busy devices are shown, unless you gave filter patterns: devices you named stay on screen even while idle (not on macOS, where throughput isn't available; `-A` still forces it). Each refresh re-reads mounts, labels, UUIDs, sizes, and per-drive sysfs info such as model/serial, so hot-swapped drives show up correctly (throughput iterators stay live across refreshes). Press Ctrl-C to stop (exit status 130).
|
|
142
148
|
|
|
143
149
|
If a filter pattern looks like a number, append `0` so it is not treated as the refresh interval (or use `-w` and keep the number as a filter):
|
|
144
150
|
|
|
@@ -147,13 +153,32 @@ statblk nvme0 0 # match nvme0, single run (no watch)
|
|
|
147
153
|
statblk -w 0 nvme0 # same via flag
|
|
148
154
|
```
|
|
149
155
|
|
|
156
|
+
### Health check
|
|
157
|
+
|
|
158
|
+
`--check` runs once and prints only the rows that need attention; when everything is healthy it prints nothing, so cron only mails on trouble. Exit status:
|
|
159
|
+
|
|
160
|
+
| Exit | Meaning |
|
|
161
|
+
|------|---------|
|
|
162
|
+
| `0` | Healthy (nothing printed). A `STANDBY` drive counts as healthy: it is checked on the next run that finds it awake |
|
|
163
|
+
| `1` | Problem: `FSUSE%` at or above `--max_use` (default 90) or `TIMEOUT` (hung mount), or `SMART` reporting a failure — `FAILED!`, a vendor failure string, or `TIMEOUT` (smartctl stuck on the disk) |
|
|
164
|
+
| `3` | Unknown: no problem found, but SMART couldn't be read on a disk — `NO SMARTCTL` (install smartmontools), `DENIED` (run as root or with `--sudo`) or `UNKNOWN` (no verdict, e.g. a disk behind a RAID controller) |
|
|
165
|
+
|
|
166
|
+
A problem beats an unknown, and both kinds of rows are listed. Exit `3` exists so that "not checked" never looks like "healthy" in a sweep. For a space-only check use `-x SMART`; to skip a device that has no SMART at all (an SD card, a USB stick) filter it out, e.g. `statblk --check -D -v mmcblk`. `FSUSE%` and `SMART` are always added to the shown columns so you can see why a row failed; excluding one with `-x` turns that check off. Filters (`-M`, `-B`, patterns) and JSON output (`-j` / `-J`) work as usual, but filters narrow what is checked: `-M` and patterns skip disks with no mount of their own (md/LVM/ZFS/Ceph members, extra btrfs pool devices), so cluster sweeps should run plain `--check`. `--check` can't be combined with watch mode.
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
statblk --check || mail -s "disk alert on $(hostname)" ops@example.com # cron
|
|
170
|
+
statblk --check -x SMART --max_use 80 # space only
|
|
171
|
+
mssh 'nodes[1-64]' 'statblk --check' # whole cluster via multiSSH3
|
|
172
|
+
```
|
|
173
|
+
|
|
150
174
|
## Platform notes
|
|
151
175
|
|
|
152
176
|
### Linux
|
|
153
177
|
|
|
154
178
|
Uses sysfs, `/proc/self/mountinfo`, `lsblk`, and optionally `smartctl`.
|
|
155
179
|
|
|
156
|
-
- **SMART** requires `smartctl` (smartmontools). Use `--sudo` if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd).
|
|
180
|
+
- **SMART** requires `smartctl` (smartmontools). Use `--sudo` if permission is denied. It only runs against hardware-backed disks (not loop, dm, md, zram, nbd). smartctl runs with `-n standby`, so spun-down drives are not woken (not even by watch mode); they show `STANDBY` until they're next awake. This is verified for SATA drives on the kernel's libata driver; drives behind USB enclosures or some RAID/SAS controllers may still spin up, because smartctl's device-type probe goes through the bridge. On a hardware disk where SMART can't be read the column says why (`NO SMARTCTL`, `DENIED`, `UNKNOWN`); it is blank for virtual devices.
|
|
181
|
+
- **squashfs on loop devices** (snap packages, AppImages) is hidden by default: these images are read-only and always 100% full. Use `--show_squashfs` to list them. Other loop devices, such as a mounted disk image, are always shown.
|
|
157
182
|
- **autofs** trigger mounts are ignored (stat-ing them would trigger the automount); the real filesystem appears once mounted.
|
|
158
183
|
- **READ / WRITE** throughput comes from `/sys/class/block/*/stat` (always 512-byte sector units).
|
|
159
184
|
- On a single-shot run (and the first row of watch mode), READ/WRITE are a lifetime busy-time average (bytes / time spent in I/O since boot). In watch mode, later refreshes are interval rates over the sleep period (Δbytes / wall clock).
|
|
@@ -7,6 +7,7 @@ statblk.egg-info/dependency_links.txt
|
|
|
7
7
|
statblk.egg-info/entry_points.txt
|
|
8
8
|
statblk.egg-info/requires.txt
|
|
9
9
|
statblk.egg-info/top_level.txt
|
|
10
|
+
tests/test_check.py
|
|
10
11
|
tests/test_cli.py
|
|
11
12
|
tests/test_doctest_module.py
|
|
12
13
|
tests/test_drives_info.py
|
|
@@ -16,4 +17,5 @@ tests/test_macos.py
|
|
|
16
17
|
tests/test_multicmd_import.py
|
|
17
18
|
tests/test_parse.py
|
|
18
19
|
tests/test_sysfs_helpers.py
|
|
19
|
-
tests/test_throughput.py
|
|
20
|
+
tests/test_throughput.py
|
|
21
|
+
tests/test_watch.py
|