host-pressure 0.1.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.
- host_pressure-0.1.1/LICENSE +21 -0
- host_pressure-0.1.1/PKG-INFO +203 -0
- host_pressure-0.1.1/README.md +177 -0
- host_pressure-0.1.1/pyproject.toml +53 -0
- host_pressure-0.1.1/rust/Cargo.lock +16 -0
- host_pressure-0.1.1/rust/Cargo.toml +13 -0
- host_pressure-0.1.1/rust/normalize_json.py +23 -0
- host_pressure-0.1.1/rust/parity.sh +128 -0
- host_pressure-0.1.1/rust/src/core.rs +1529 -0
- host_pressure-0.1.1/rust/src/formatting.rs +692 -0
- host_pressure-0.1.1/rust/src/lib.rs +4 -0
- host_pressure-0.1.1/rust/src/main.rs +1070 -0
- host_pressure-0.1.1/rust/src/verdict.rs +512 -0
- host_pressure-0.1.1/rust/src/win.rs +212 -0
- host_pressure-0.1.1/src/host_pressure/__init__.py +53 -0
- host_pressure-0.1.1/src/host_pressure/__main__.py +6 -0
- host_pressure-0.1.1/src/host_pressure/_core.py +921 -0
- host_pressure-0.1.1/src/host_pressure/cli.py +268 -0
- host_pressure-0.1.1/src/host_pressure/formatting.py +104 -0
- host_pressure-0.1.1/src/host_pressure/verdict.py +202 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 El Fenomeno
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: host-pressure
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Classifier: Development Status :: 4 - Beta
|
|
5
|
+
Classifier: Environment :: Console
|
|
6
|
+
Classifier: Intended Audience :: Developers
|
|
7
|
+
Classifier: Intended Audience :: System Administrators
|
|
8
|
+
Classifier: Operating System :: MacOS
|
|
9
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
10
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Topic :: System :: Monitoring
|
|
14
|
+
Classifier: Topic :: System :: Systems Administration
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Summary: A command-line resource check that tells you whether your machine has room for another job.
|
|
17
|
+
Keywords: cpu,memory,swap,pressure,psi,load,monitoring,health-check,cli,macos,linux,windows
|
|
18
|
+
Author: El Fenomeno
|
|
19
|
+
License-Expression: MIT
|
|
20
|
+
Requires-Python: >=3.9
|
|
21
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
22
|
+
Project-URL: Homepage, https://github.com/elfenomenokim/host-pressure
|
|
23
|
+
Project-URL: Issues, https://github.com/elfenomenokim/host-pressure/issues
|
|
24
|
+
Project-URL: Repository, https://github.com/elfenomenokim/host-pressure
|
|
25
|
+
|
|
26
|
+
# host-pressure
|
|
27
|
+
[한국어](README.ko.md)
|
|
28
|
+
|
|
29
|
+
A command-line resource check that tells you whether your machine has room for another job.
|
|
30
|
+
|
|
31
|
+
<picture>
|
|
32
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/dark.gif">
|
|
33
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/light.gif" alt="A resource line, an ok verdict, and repeated readings from the labeled demo fixture" width="1200">
|
|
34
|
+
</picture>
|
|
35
|
+
|
|
36
|
+
The recording runs the Python CLI with [synthetic readings](docs/demo/fixture.py). It shows formatting and verdicts, not a measurement of a real host.
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
pipx install host-pressure
|
|
42
|
+
uv tool install host-pressure
|
|
43
|
+
pip install host-pressure
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Python 3.9+. Wheels install the Rust command and the importable Python package. A source install needs Rust.
|
|
47
|
+
|
|
48
|
+
| Platform | Observed runs |
|
|
49
|
+
|---|---|
|
|
50
|
+
| macOS arm64 | Rust command and Python library |
|
|
51
|
+
| Linux arm64 | Rust command and Python library on Ubuntu 24.04 |
|
|
52
|
+
| Windows x64 | Both commands on Windows 11 |
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
You can read one line, check whether to start work, or choose fields for a status bar. These outputs were captured from the demo fixture; your readings will differ.
|
|
57
|
+
|
|
58
|
+
```console
|
|
59
|
+
$ host-pressure
|
|
60
|
+
CPU 16% MEM 72% SWAP 1.5G pressure normal
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```console
|
|
64
|
+
$ host-pressure check
|
|
65
|
+
ok
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
```console
|
|
69
|
+
$ host-pressure --format '{level} | CPU {cpu} | MEM {mem}'
|
|
70
|
+
ok | CPU 16% | MEM 72%
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```console
|
|
74
|
+
$ host-pressure check --memory-busy 60
|
|
75
|
+
busy: memory 72% >= 60%
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`check` exits **0** for `ok`, **1** for `busy`, and **2** for `overloaded`. The last command exits 1 because it lowers the memory threshold to 60%.
|
|
79
|
+
|
|
80
|
+
## Why
|
|
81
|
+
|
|
82
|
+
Before you start another build, a memory percentage alone leaves you guessing. `host-pressure check` combines CPU, memory, load per core, disk usage, and the pressure signals your operating system exposes. You get a verdict and the readings that caused it.
|
|
83
|
+
|
|
84
|
+
Use `top` or `htop` when you need to find the process using resources. Use `psutil` when you need a general process-management library. Use this command when a script needs an exit code, a status bar needs one line, or you need macOS memory pressure and Linux PSI alongside ordinary usage figures.
|
|
85
|
+
|
|
86
|
+
## Measurements
|
|
87
|
+
|
|
88
|
+
### Repeated calls without waiting
|
|
89
|
+
|
|
90
|
+
For a status bar or a script that must return immediately, use `--no-sample`. It still reads and updates the CPU baseline; if counters have not advanced, CPU prints `n/a` instead of waiting. These are the same flag and 3-warmup/30-run method on all three hosts, measured 2026-11-17. Peak RSS comes from separate `/usr/bin/time` calls.
|
|
91
|
+
|
|
92
|
+
| Host / CPU | Command | Mean (ms) | Peak RSS (MiB) |
|
|
93
|
+
|---|---|---:|---:|
|
|
94
|
+
| macOS / Apple M5 Pro | `python3 -m host_pressure --no-sample` | 52.5 | 20.8 |
|
|
95
|
+
| macOS / Apple M5 Pro | Rust `host-pressure --no-sample` | 5.2 | 9.7 |
|
|
96
|
+
| OCI A1 / aarch64¹ | `python -m host_pressure --no-sample` | 70.0 | 15.3 |
|
|
97
|
+
| OCI A1 / aarch64¹ | Rust `host-pressure --no-sample` | 1.6 | 2.1 |
|
|
98
|
+
| Windows 11 / Ryzen 7 PRO 6850U | `python -m host_pressure --no-sample` | 166.2 | —² |
|
|
99
|
+
| Windows 11 / Ryzen 7 PRO 6850U | Rust `host-pressure.exe --no-sample` | 22.4 | —² |
|
|
100
|
+
|
|
101
|
+
¹ The A1 architecture was observed; its CPU model was not verified in this run. ² Windows timings include the venv launcher. Its peak working set excludes the Python child, so those memory readings are not comparable and are omitted.
|
|
102
|
+
|
|
103
|
+
<picture>
|
|
104
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-dark.svg">
|
|
105
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-light.svg" alt="Mean --no-sample call times from the saved 30-run measurements" width="880">
|
|
106
|
+
</picture>
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
# macOS: from the source checkout; no CPU sampling wait
|
|
110
|
+
PYTHONPATH=src hyperfine --warmup 3 --runs 30 \
|
|
111
|
+
--export-json docs/bench/m5-no-sample.json \
|
|
112
|
+
'python3 -m host_pressure --no-sample' \
|
|
113
|
+
'./rust/target/release/host-pressure --no-sample'
|
|
114
|
+
PYTHONPATH=src /usr/bin/time -l python3 -m host_pressure --no-sample
|
|
115
|
+
/usr/bin/time -l ./rust/target/release/host-pressure --no-sample
|
|
116
|
+
# A1: installed Python package and Rust binary
|
|
117
|
+
python3 docs/bench/a1-no-sample-bench.py
|
|
118
|
+
# Windows: silent temporary venv, removed when finished
|
|
119
|
+
powershell -NoProfile -File docs/bench/windows-bench.ps1 -NoSample
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
M5 uses Hyperfine 2.0.0, A1 uses a `perf_counter` subprocess loop, and Windows uses PowerShell `Measure-Command`. The saved [runners and raw outputs](docs/bench/) describe each launch method. These are running machines, not isolated CPU benchmarks.
|
|
123
|
+
|
|
124
|
+
### Default command, including sampling waits
|
|
125
|
+
|
|
126
|
+
With no flag, both editions fall back to a 0.3-second CPU sample when no usable baseline delta exists. A short sample can extend by up to one second while waiting for counters. The earlier default-command runs include those waits:
|
|
127
|
+
|
|
128
|
+
| Host | Python mean (ms) | Rust mean (ms) |
|
|
129
|
+
|---|---:|---:|
|
|
130
|
+
| M5 | 179.7 | 177.5 |
|
|
131
|
+
| A1 | 72.1 | 122.4 |
|
|
132
|
+
| Windows | 164.2 | 22.2 |
|
|
133
|
+
|
|
134
|
+
This is a different workload from `--no-sample`, not a startup-speed comparison. Exact default commands and raw runs are retained in [docs/bench](docs/bench/).
|
|
135
|
+
|
|
136
|
+
On A1, a follow-up run with separate baseline directories explained the reversal: 11 of 30 rapid Rust calls saw **zero new ticks** and used the sample fallback. All 30 Python calls saw a new baseline delta. With **50 ms between Rust calls**, all 30 used the baseline and averaged **2.36 ms per call**, excluding the pause. The source logic uses the same 0.3-second fallback and baseline rules in both editions; no sampling-interval difference was found. See the [recorded diagnosis](docs/bench/a1-default-diagnosis.json).
|
|
137
|
+
|
|
138
|
+
<picture>
|
|
139
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-dark.svg">
|
|
140
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-light.svg" alt="Without new CPU ticks, --no-sample returns n/a while the default command samples" width="880">
|
|
141
|
+
</picture>
|
|
142
|
+
|
|
143
|
+
## Reference
|
|
144
|
+
|
|
145
|
+
| Command or flag | Result |
|
|
146
|
+
|---|---|
|
|
147
|
+
| `host-pressure --all` | Add load, disk, thermal, battery and PSI where available |
|
|
148
|
+
| `host-pressure --json` | Full reading and verdict as JSON |
|
|
149
|
+
| `host-pressure check --json` | Verdict and reasons as JSON |
|
|
150
|
+
| `host-pressure --watch 2` | Repeat every two seconds; Ctrl+C stops it |
|
|
151
|
+
| `host-pressure wait --until ok --timeout 120` | Wait for room; exit 75 on timeout |
|
|
152
|
+
| `--format TEMPLATE` / `--format-help` | Select fields; values already include units |
|
|
153
|
+
| `--disk MOUNT` | Read a mount; repeat for more than one |
|
|
154
|
+
| `--sample 0.5` | Take a CPU sample in this call |
|
|
155
|
+
| `--no-sample` | Never wait for CPU counters |
|
|
156
|
+
| `--consumer ID` / `--state-dir DIR` | Select the CPU baseline and storage directory |
|
|
157
|
+
|
|
158
|
+
`--watch --json` writes one object per line. Without `--watch`, JSON is formatted across multiple lines. Parse JSON rather than the human-readable line.
|
|
159
|
+
|
|
160
|
+
### Thresholds
|
|
161
|
+
|
|
162
|
+
| Threshold flags | Busy / overloaded defaults |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `--cpu-busy`, `--cpu-overloaded` | 80 / 95 percent |
|
|
165
|
+
| `--memory-busy`, `--memory-overloaded` | 85 / 95 percent |
|
|
166
|
+
| `--load-busy`, `--load-overloaded` | 1 / 2 load per CPU core |
|
|
167
|
+
| `--disk-busy`, `--disk-overloaded` | 90 / 97 percent |
|
|
168
|
+
| `--swap-busy-gb`, `--swap-overloaded-gb` | Disabled |
|
|
169
|
+
|
|
170
|
+
Use `--config FILE`, `HOST_PRESSURE_CONFIG`, or `$XDG_CONFIG_HOME/host-pressure/config.json` for persistent thresholds. Keys use snake case, such as `memory_busy`; unknown keys are errors. Environment overrides use `HOST_PRESSURE_MEMORY_BUSY=80`. Command-line values win over environment values, which win over the file.
|
|
171
|
+
|
|
172
|
+
Config and environment also accept `psi_cpu_busy`, `psi_cpu_overloaded`, `psi_memory_busy`, `psi_memory_overloaded`, `psi_io_busy`, and `psi_io_overloaded`. macOS kernel pressure and thermal states have fixed verdict mappings.
|
|
173
|
+
|
|
174
|
+
CPU baselines live under `$XDG_STATE_HOME/host-pressure`; `HOST_PRESSURE_STATE_DIR` overrides that directory. Give separate callers their own `--consumer` value. The baseline interval is the time between calls, not a fixed sampling window. Rust and Python share its format.
|
|
175
|
+
|
|
176
|
+
### Python
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
import host_pressure
|
|
180
|
+
|
|
181
|
+
reading = host_pressure.read(consumer_id="my-tool")
|
|
182
|
+
result = host_pressure.verdict(reading)
|
|
183
|
+
print(result["level"], result["reasons"])
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`read(sample=0.5)` takes an explicit CPU sample. `verdict()` without a reading samples for 0.2 seconds by default; use `verdict(reading)` to classify an existing reading without waiting. The library uses only the Python standard library.
|
|
187
|
+
|
|
188
|
+
## Limits
|
|
189
|
+
|
|
190
|
+
- Missing readings stay `null` in JSON and `n/a` in text. A missing CPU number does not mean 0% usage.
|
|
191
|
+
- Windows has no load-average or thermal reading. Its pressure verdict comes from memory load.
|
|
192
|
+
- Battery-present readings were not exercised in these runs. Linux virtual machines may expose no thermal zone.
|
|
193
|
+
- A short CPU sample can stretch by up to one second while waiting for counters to move. The first default call may also sample.
|
|
194
|
+
- macOS swap can remain allocated after pressure falls, so swap thresholds are off by default.
|
|
195
|
+
- `--watch` repeats readings; it stores no history and sends no alerts. One `ok` does not describe the machine over time.
|
|
196
|
+
- macOS/Linux x86_64 wheels exist, but those backends were not run here.
|
|
197
|
+
|
|
198
|
+
## Contributing
|
|
199
|
+
|
|
200
|
+
Issues and platform reports are welcome; run `bash rust/parity.sh` from the source checkout. See [AGENTS.md](AGENTS.md) for the code layout and safety rules.
|
|
201
|
+
|
|
202
|
+
License: [MIT](LICENSE).
|
|
203
|
+
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# host-pressure
|
|
2
|
+
[한국어](README.ko.md)
|
|
3
|
+
|
|
4
|
+
A command-line resource check that tells you whether your machine has room for another job.
|
|
5
|
+
|
|
6
|
+
<picture>
|
|
7
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/dark.gif">
|
|
8
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/demo/light.gif" alt="A resource line, an ok verdict, and repeated readings from the labeled demo fixture" width="1200">
|
|
9
|
+
</picture>
|
|
10
|
+
|
|
11
|
+
The recording runs the Python CLI with [synthetic readings](docs/demo/fixture.py). It shows formatting and verdicts, not a measurement of a real host.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pipx install host-pressure
|
|
17
|
+
uv tool install host-pressure
|
|
18
|
+
pip install host-pressure
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Python 3.9+. Wheels install the Rust command and the importable Python package. A source install needs Rust.
|
|
22
|
+
|
|
23
|
+
| Platform | Observed runs |
|
|
24
|
+
|---|---|
|
|
25
|
+
| macOS arm64 | Rust command and Python library |
|
|
26
|
+
| Linux arm64 | Rust command and Python library on Ubuntu 24.04 |
|
|
27
|
+
| Windows x64 | Both commands on Windows 11 |
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
30
|
+
|
|
31
|
+
You can read one line, check whether to start work, or choose fields for a status bar. These outputs were captured from the demo fixture; your readings will differ.
|
|
32
|
+
|
|
33
|
+
```console
|
|
34
|
+
$ host-pressure
|
|
35
|
+
CPU 16% MEM 72% SWAP 1.5G pressure normal
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```console
|
|
39
|
+
$ host-pressure check
|
|
40
|
+
ok
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
```console
|
|
44
|
+
$ host-pressure --format '{level} | CPU {cpu} | MEM {mem}'
|
|
45
|
+
ok | CPU 16% | MEM 72%
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```console
|
|
49
|
+
$ host-pressure check --memory-busy 60
|
|
50
|
+
busy: memory 72% >= 60%
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`check` exits **0** for `ok`, **1** for `busy`, and **2** for `overloaded`. The last command exits 1 because it lowers the memory threshold to 60%.
|
|
54
|
+
|
|
55
|
+
## Why
|
|
56
|
+
|
|
57
|
+
Before you start another build, a memory percentage alone leaves you guessing. `host-pressure check` combines CPU, memory, load per core, disk usage, and the pressure signals your operating system exposes. You get a verdict and the readings that caused it.
|
|
58
|
+
|
|
59
|
+
Use `top` or `htop` when you need to find the process using resources. Use `psutil` when you need a general process-management library. Use this command when a script needs an exit code, a status bar needs one line, or you need macOS memory pressure and Linux PSI alongside ordinary usage figures.
|
|
60
|
+
|
|
61
|
+
## Measurements
|
|
62
|
+
|
|
63
|
+
### Repeated calls without waiting
|
|
64
|
+
|
|
65
|
+
For a status bar or a script that must return immediately, use `--no-sample`. It still reads and updates the CPU baseline; if counters have not advanced, CPU prints `n/a` instead of waiting. These are the same flag and 3-warmup/30-run method on all three hosts, measured 2026-11-17. Peak RSS comes from separate `/usr/bin/time` calls.
|
|
66
|
+
|
|
67
|
+
| Host / CPU | Command | Mean (ms) | Peak RSS (MiB) |
|
|
68
|
+
|---|---|---:|---:|
|
|
69
|
+
| macOS / Apple M5 Pro | `python3 -m host_pressure --no-sample` | 52.5 | 20.8 |
|
|
70
|
+
| macOS / Apple M5 Pro | Rust `host-pressure --no-sample` | 5.2 | 9.7 |
|
|
71
|
+
| OCI A1 / aarch64¹ | `python -m host_pressure --no-sample` | 70.0 | 15.3 |
|
|
72
|
+
| OCI A1 / aarch64¹ | Rust `host-pressure --no-sample` | 1.6 | 2.1 |
|
|
73
|
+
| Windows 11 / Ryzen 7 PRO 6850U | `python -m host_pressure --no-sample` | 166.2 | —² |
|
|
74
|
+
| Windows 11 / Ryzen 7 PRO 6850U | Rust `host-pressure.exe --no-sample` | 22.4 | —² |
|
|
75
|
+
|
|
76
|
+
¹ The A1 architecture was observed; its CPU model was not verified in this run. ² Windows timings include the venv launcher. Its peak working set excludes the Python child, so those memory readings are not comparable and are omitted.
|
|
77
|
+
|
|
78
|
+
<picture>
|
|
79
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-dark.svg">
|
|
80
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/no-sample-light.svg" alt="Mean --no-sample call times from the saved 30-run measurements" width="880">
|
|
81
|
+
</picture>
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
# macOS: from the source checkout; no CPU sampling wait
|
|
85
|
+
PYTHONPATH=src hyperfine --warmup 3 --runs 30 \
|
|
86
|
+
--export-json docs/bench/m5-no-sample.json \
|
|
87
|
+
'python3 -m host_pressure --no-sample' \
|
|
88
|
+
'./rust/target/release/host-pressure --no-sample'
|
|
89
|
+
PYTHONPATH=src /usr/bin/time -l python3 -m host_pressure --no-sample
|
|
90
|
+
/usr/bin/time -l ./rust/target/release/host-pressure --no-sample
|
|
91
|
+
# A1: installed Python package and Rust binary
|
|
92
|
+
python3 docs/bench/a1-no-sample-bench.py
|
|
93
|
+
# Windows: silent temporary venv, removed when finished
|
|
94
|
+
powershell -NoProfile -File docs/bench/windows-bench.ps1 -NoSample
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
M5 uses Hyperfine 2.0.0, A1 uses a `perf_counter` subprocess loop, and Windows uses PowerShell `Measure-Command`. The saved [runners and raw outputs](docs/bench/) describe each launch method. These are running machines, not isolated CPU benchmarks.
|
|
98
|
+
|
|
99
|
+
### Default command, including sampling waits
|
|
100
|
+
|
|
101
|
+
With no flag, both editions fall back to a 0.3-second CPU sample when no usable baseline delta exists. A short sample can extend by up to one second while waiting for counters. The earlier default-command runs include those waits:
|
|
102
|
+
|
|
103
|
+
| Host | Python mean (ms) | Rust mean (ms) |
|
|
104
|
+
|---|---:|---:|
|
|
105
|
+
| M5 | 179.7 | 177.5 |
|
|
106
|
+
| A1 | 72.1 | 122.4 |
|
|
107
|
+
| Windows | 164.2 | 22.2 |
|
|
108
|
+
|
|
109
|
+
This is a different workload from `--no-sample`, not a startup-speed comparison. Exact default commands and raw runs are retained in [docs/bench](docs/bench/).
|
|
110
|
+
|
|
111
|
+
On A1, a follow-up run with separate baseline directories explained the reversal: 11 of 30 rapid Rust calls saw **zero new ticks** and used the sample fallback. All 30 Python calls saw a new baseline delta. With **50 ms between Rust calls**, all 30 used the baseline and averaged **2.36 ms per call**, excluding the pause. The source logic uses the same 0.3-second fallback and baseline rules in both editions; no sampling-interval difference was found. See the [recorded diagnosis](docs/bench/a1-default-diagnosis.json).
|
|
112
|
+
|
|
113
|
+
<picture>
|
|
114
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-dark.svg">
|
|
115
|
+
<img src="https://raw.githubusercontent.com/elfenomenokim/host-pressure/main/docs/diagrams/cpu-flow-light.svg" alt="Without new CPU ticks, --no-sample returns n/a while the default command samples" width="880">
|
|
116
|
+
</picture>
|
|
117
|
+
|
|
118
|
+
## Reference
|
|
119
|
+
|
|
120
|
+
| Command or flag | Result |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `host-pressure --all` | Add load, disk, thermal, battery and PSI where available |
|
|
123
|
+
| `host-pressure --json` | Full reading and verdict as JSON |
|
|
124
|
+
| `host-pressure check --json` | Verdict and reasons as JSON |
|
|
125
|
+
| `host-pressure --watch 2` | Repeat every two seconds; Ctrl+C stops it |
|
|
126
|
+
| `host-pressure wait --until ok --timeout 120` | Wait for room; exit 75 on timeout |
|
|
127
|
+
| `--format TEMPLATE` / `--format-help` | Select fields; values already include units |
|
|
128
|
+
| `--disk MOUNT` | Read a mount; repeat for more than one |
|
|
129
|
+
| `--sample 0.5` | Take a CPU sample in this call |
|
|
130
|
+
| `--no-sample` | Never wait for CPU counters |
|
|
131
|
+
| `--consumer ID` / `--state-dir DIR` | Select the CPU baseline and storage directory |
|
|
132
|
+
|
|
133
|
+
`--watch --json` writes one object per line. Without `--watch`, JSON is formatted across multiple lines. Parse JSON rather than the human-readable line.
|
|
134
|
+
|
|
135
|
+
### Thresholds
|
|
136
|
+
|
|
137
|
+
| Threshold flags | Busy / overloaded defaults |
|
|
138
|
+
|---|---|
|
|
139
|
+
| `--cpu-busy`, `--cpu-overloaded` | 80 / 95 percent |
|
|
140
|
+
| `--memory-busy`, `--memory-overloaded` | 85 / 95 percent |
|
|
141
|
+
| `--load-busy`, `--load-overloaded` | 1 / 2 load per CPU core |
|
|
142
|
+
| `--disk-busy`, `--disk-overloaded` | 90 / 97 percent |
|
|
143
|
+
| `--swap-busy-gb`, `--swap-overloaded-gb` | Disabled |
|
|
144
|
+
|
|
145
|
+
Use `--config FILE`, `HOST_PRESSURE_CONFIG`, or `$XDG_CONFIG_HOME/host-pressure/config.json` for persistent thresholds. Keys use snake case, such as `memory_busy`; unknown keys are errors. Environment overrides use `HOST_PRESSURE_MEMORY_BUSY=80`. Command-line values win over environment values, which win over the file.
|
|
146
|
+
|
|
147
|
+
Config and environment also accept `psi_cpu_busy`, `psi_cpu_overloaded`, `psi_memory_busy`, `psi_memory_overloaded`, `psi_io_busy`, and `psi_io_overloaded`. macOS kernel pressure and thermal states have fixed verdict mappings.
|
|
148
|
+
|
|
149
|
+
CPU baselines live under `$XDG_STATE_HOME/host-pressure`; `HOST_PRESSURE_STATE_DIR` overrides that directory. Give separate callers their own `--consumer` value. The baseline interval is the time between calls, not a fixed sampling window. Rust and Python share its format.
|
|
150
|
+
|
|
151
|
+
### Python
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
import host_pressure
|
|
155
|
+
|
|
156
|
+
reading = host_pressure.read(consumer_id="my-tool")
|
|
157
|
+
result = host_pressure.verdict(reading)
|
|
158
|
+
print(result["level"], result["reasons"])
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
`read(sample=0.5)` takes an explicit CPU sample. `verdict()` without a reading samples for 0.2 seconds by default; use `verdict(reading)` to classify an existing reading without waiting. The library uses only the Python standard library.
|
|
162
|
+
|
|
163
|
+
## Limits
|
|
164
|
+
|
|
165
|
+
- Missing readings stay `null` in JSON and `n/a` in text. A missing CPU number does not mean 0% usage.
|
|
166
|
+
- Windows has no load-average or thermal reading. Its pressure verdict comes from memory load.
|
|
167
|
+
- Battery-present readings were not exercised in these runs. Linux virtual machines may expose no thermal zone.
|
|
168
|
+
- A short CPU sample can stretch by up to one second while waiting for counters to move. The first default call may also sample.
|
|
169
|
+
- macOS swap can remain allocated after pressure falls, so swap thresholds are off by default.
|
|
170
|
+
- `--watch` repeats readings; it stores no history and sends no alerts. One `ok` does not describe the machine over time.
|
|
171
|
+
- macOS/Linux x86_64 wheels exist, but those backends were not run here.
|
|
172
|
+
|
|
173
|
+
## Contributing
|
|
174
|
+
|
|
175
|
+
Issues and platform reports are welcome; run `bash rust/parity.sh` from the source checkout. See [AGENTS.md](AGENTS.md) for the code layout and safety rules.
|
|
176
|
+
|
|
177
|
+
License: [MIT](LICENSE).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["maturin>=1.0,<2.0"]
|
|
3
|
+
build-backend = "maturin"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "host-pressure"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
description = "A command-line resource check that tells you whether your machine has room for another job."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "El Fenomeno" }]
|
|
14
|
+
keywords = [
|
|
15
|
+
"cpu",
|
|
16
|
+
"memory",
|
|
17
|
+
"swap",
|
|
18
|
+
"pressure",
|
|
19
|
+
"psi",
|
|
20
|
+
"load",
|
|
21
|
+
"monitoring",
|
|
22
|
+
"health-check",
|
|
23
|
+
"cli",
|
|
24
|
+
"macos",
|
|
25
|
+
"linux",
|
|
26
|
+
"windows",
|
|
27
|
+
]
|
|
28
|
+
classifiers = [
|
|
29
|
+
"Development Status :: 4 - Beta",
|
|
30
|
+
"Environment :: Console",
|
|
31
|
+
"Intended Audience :: Developers",
|
|
32
|
+
"Intended Audience :: System Administrators",
|
|
33
|
+
"Operating System :: MacOS",
|
|
34
|
+
"Operating System :: Microsoft :: Windows",
|
|
35
|
+
"Operating System :: POSIX :: Linux",
|
|
36
|
+
"Programming Language :: Python :: 3",
|
|
37
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
38
|
+
"Topic :: System :: Monitoring",
|
|
39
|
+
"Topic :: System :: Systems Administration",
|
|
40
|
+
]
|
|
41
|
+
dependencies = []
|
|
42
|
+
|
|
43
|
+
[project.urls]
|
|
44
|
+
Homepage = "https://github.com/elfenomenokim/host-pressure"
|
|
45
|
+
Repository = "https://github.com/elfenomenokim/host-pressure"
|
|
46
|
+
Issues = "https://github.com/elfenomenokim/host-pressure/issues"
|
|
47
|
+
|
|
48
|
+
[tool.maturin]
|
|
49
|
+
bindings = "bin"
|
|
50
|
+
manifest-path = "rust/Cargo.toml"
|
|
51
|
+
python-source = "src"
|
|
52
|
+
module-name = "host_pressure"
|
|
53
|
+
strip = true
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# This file is automatically @generated by Cargo.
|
|
2
|
+
# It is not intended for manual editing.
|
|
3
|
+
version = 4
|
|
4
|
+
|
|
5
|
+
[[package]]
|
|
6
|
+
name = "host-pressure"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
dependencies = [
|
|
9
|
+
"libc",
|
|
10
|
+
]
|
|
11
|
+
|
|
12
|
+
[[package]]
|
|
13
|
+
name = "libc"
|
|
14
|
+
version = "0.2.191"
|
|
15
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
16
|
+
checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
[package]
|
|
2
|
+
name = "host-pressure"
|
|
3
|
+
version = "0.1.1"
|
|
4
|
+
edition = "2021"
|
|
5
|
+
description = "Read CPU, memory, swap, disk, thermal, battery and pressure stall time on macOS, Linux and Windows, and turn them into one verdict: ok, busy or overloaded. No subprocess."
|
|
6
|
+
license = "MIT"
|
|
7
|
+
|
|
8
|
+
[[bin]]
|
|
9
|
+
name = "host-pressure"
|
|
10
|
+
path = "src/main.rs"
|
|
11
|
+
|
|
12
|
+
[target.'cfg(unix)'.dependencies]
|
|
13
|
+
libc = "0.2"
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import json, sys
|
|
2
|
+
d = json.load(sys.stdin)
|
|
3
|
+
def norm(v):
|
|
4
|
+
if isinstance(v, dict):
|
|
5
|
+
return {k: norm(x) for k, x in sorted(v.items())}
|
|
6
|
+
if isinstance(v, list):
|
|
7
|
+
return [norm(x) for x in v]
|
|
8
|
+
if v is None:
|
|
9
|
+
return None
|
|
10
|
+
if isinstance(v, bool):
|
|
11
|
+
return v
|
|
12
|
+
if isinstance(v, (int, float)):
|
|
13
|
+
return "<num>"
|
|
14
|
+
return "<str>"
|
|
15
|
+
for k in ("observedAt","cpuPercent","memoryPercent","memoryUsedBytes","loadavg","uptime","uptimeSeconds"):
|
|
16
|
+
if k in d:
|
|
17
|
+
d[k] = f"<{type(d[k]).__name__}>"
|
|
18
|
+
if "disks" in d and isinstance(d["disks"], list):
|
|
19
|
+
for disk in d["disks"]:
|
|
20
|
+
for kk in ("usedBytes","freeBytes","percent"):
|
|
21
|
+
if kk in disk:
|
|
22
|
+
disk[kk] = f"<{type(disk[kk]).__name__ if disk[kk] is not None else 'None'}>"
|
|
23
|
+
print(json.dumps(norm(d), sort_keys=True, indent=2))
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# parity.sh — compare Python and Rust host-pressure editions with the same flags.
|
|
3
|
+
# Volatile numbers (CPU %, memory %, timestamps, load) differ between two instants,
|
|
4
|
+
# so they are compared by presence/type, not value. Stable output (keys, formats,
|
|
5
|
+
# exit codes, error messages) must match exactly.
|
|
6
|
+
set -uo pipefail
|
|
7
|
+
|
|
8
|
+
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
9
|
+
ROOT="$HERE/.."
|
|
10
|
+
PY="PYTHONPATH=$ROOT/src python3 -m host_pressure"
|
|
11
|
+
RS_BIN="${RS_BIN:-$HERE/target/debug/host-pressure}"
|
|
12
|
+
|
|
13
|
+
if [ ! -x "$RS_BIN" ]; then
|
|
14
|
+
# fall back to release build
|
|
15
|
+
if [ -x "$HERE/target/release/host-pressure" ]; then
|
|
16
|
+
RS_BIN="$HERE/target/release/host-pressure"
|
|
17
|
+
else
|
|
18
|
+
echo "parity: missing Rust binary ($RS_BIN)" >&2
|
|
19
|
+
exit 1
|
|
20
|
+
fi
|
|
21
|
+
fi
|
|
22
|
+
|
|
23
|
+
pass=0
|
|
24
|
+
fail=0
|
|
25
|
+
|
|
26
|
+
ok() { pass=$((pass+1)); echo "ok: $1"; }
|
|
27
|
+
bad() { fail=$((fail+1)); echo "FAIL: $1"; echo "$2" | head -n 20; }
|
|
28
|
+
|
|
29
|
+
# 1. --format-help must be byte-identical.
|
|
30
|
+
if diff -u <(PYTHONPATH="$ROOT/src" python3 -m host_pressure --format-help) <("$RS_BIN" --format-help) > /tmp/hp-parity-help.diff; then
|
|
31
|
+
ok "--format-help identical"
|
|
32
|
+
else
|
|
33
|
+
bad "--format-help differs" "$(cat /tmp/hp-parity-help.diff)"
|
|
34
|
+
fi
|
|
35
|
+
|
|
36
|
+
# 2. --json keys and value shapes (normalize volatile values to types).
|
|
37
|
+
normalize() {
|
|
38
|
+
python3 "$HERE/normalize_json.py"
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
for flags in "--sample 0.1" "--sample 0.1 --all" "--sample 0.1 --disk / --disk /tmp --all"; do
|
|
42
|
+
# shellcheck disable=SC2086
|
|
43
|
+
if diff -u <(PYTHONPATH="$ROOT/src" python3 -m host_pressure --json $flags | normalize) <("$RS_BIN" --json $flags | normalize) > /tmp/hp-parity-json.diff; then
|
|
44
|
+
ok "--json $flags (normalised)"
|
|
45
|
+
else
|
|
46
|
+
bad "--json $flags (normalised)" "$(cat /tmp/hp-parity-json.diff)"
|
|
47
|
+
fi
|
|
48
|
+
done
|
|
49
|
+
|
|
50
|
+
# 3. one-line shape: CPU x% MEM y% SWAP z pressure w (values may differ, shape must hold).
|
|
51
|
+
shape='^CPU (n/a|[0-9]+%) MEM (n/a|[0-9]+%) SWAP (n/a|[0-9.]+[KMGTB]) pressure (normal|warning|critical|unknown)( LOAD .*| DISK .*| THERM .*| BAT .*| PSI .*)*$'
|
|
52
|
+
for flags in "--sample 0.1" "--sample 0.1 --all"; do
|
|
53
|
+
# shellcheck disable=SC2086
|
|
54
|
+
py_line=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure $flags)
|
|
55
|
+
# shellcheck disable=SC2086
|
|
56
|
+
rs_line=$("$RS_BIN" $flags)
|
|
57
|
+
if [[ "$py_line" =~ $shape ]] && [[ "$rs_line" =~ $shape ]]; then
|
|
58
|
+
ok "one-line shape $flags"
|
|
59
|
+
else
|
|
60
|
+
bad "one-line shape $flags" "py: $py_line
|
|
61
|
+
rs: $rs_line"
|
|
62
|
+
fi
|
|
63
|
+
done
|
|
64
|
+
|
|
65
|
+
# 4. check semantics: exit codes 0/1/2 and reason shape.
|
|
66
|
+
# shellcheck disable=SC2086
|
|
67
|
+
PYTHONPATH="$ROOT/src" python3 -m host_pressure check --sample 0.1 >/dev/null; py_code=$?
|
|
68
|
+
"$RS_BIN" check --sample 0.1 >/dev/null; rs_code=$?
|
|
69
|
+
if [ "$py_code" = "$rs_code" ]; then
|
|
70
|
+
ok "check exit code ($py_code)"
|
|
71
|
+
else
|
|
72
|
+
bad "check exit code" "py=$py_code rs=$rs_code"
|
|
73
|
+
fi
|
|
74
|
+
|
|
75
|
+
# forced busy must exit 1 with same reason shape
|
|
76
|
+
py_out=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure check --memory-busy 10 --sample 0.1; echo "exit:$?")
|
|
77
|
+
rs_out=$("$RS_BIN" check --memory-busy 10 --sample 0.1; echo "exit:$?")
|
|
78
|
+
py_reason=$(echo "$py_out" | head -n 1)
|
|
79
|
+
rs_reason=$(echo "$rs_out" | head -n 1)
|
|
80
|
+
if [[ "$py_reason" =~ ^busy:\ memory\ [0-9.]+%\ \>=\ 10%$ ]] && [[ "$rs_reason" =~ ^busy:\ memory\ [0-9.]+%\ \>=\ 10%$ ]]; then
|
|
81
|
+
ok "check busy reason shape"
|
|
82
|
+
else
|
|
83
|
+
bad "check busy reason shape" "py: $py_reason
|
|
84
|
+
rs: $rs_reason"
|
|
85
|
+
fi
|
|
86
|
+
|
|
87
|
+
# 5. error paths: unknown placeholder, unknown key, bad env (exit 64, same message).
|
|
88
|
+
py_err=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure --format 'CPU {bogus}' --sample 0.1 2>&1; echo "exit:$?")
|
|
89
|
+
rs_err=$("$RS_BIN" --format 'CPU {bogus}' --sample 0.1 2>&1; echo "exit:$?")
|
|
90
|
+
if [ "$(echo "$py_err" | tail -n 1)" = "exit:64" ] && [ "$(echo "$rs_err" | tail -n 1)" = "exit:64" ] \
|
|
91
|
+
&& [ "$(echo "$py_err" | head -n 1)" = "$(echo "$rs_err" | head -n 1)" ]; then
|
|
92
|
+
ok "unknown placeholder error"
|
|
93
|
+
else
|
|
94
|
+
bad "unknown placeholder error" "py: $py_err
|
|
95
|
+
rs: $rs_err"
|
|
96
|
+
fi
|
|
97
|
+
|
|
98
|
+
tmp_cfg=$(mktemp)
|
|
99
|
+
echo '{"bogus_key": 1}' > "$tmp_cfg"
|
|
100
|
+
py_err=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure --config "$tmp_cfg" --sample 0.1 2>&1; echo "exit:$?")
|
|
101
|
+
rs_err=$("$RS_BIN" --config "$tmp_cfg" --sample 0.1 2>&1; echo "exit:$?")
|
|
102
|
+
rm -f "$tmp_cfg"
|
|
103
|
+
if [ "$(echo "$py_err" | tail -n 1)" = "exit:64" ] && [ "$(echo "$rs_err" | tail -n 1)" = "exit:64" ]; then
|
|
104
|
+
# compare after normalising the config path (same path given, so must match)
|
|
105
|
+
if [ "$(echo "$py_err" | head -n 1)" = "$(echo "$rs_err" | head -n 1)" ]; then
|
|
106
|
+
ok "config unknown key error"
|
|
107
|
+
else
|
|
108
|
+
bad "config unknown key error" "py: $py_err
|
|
109
|
+
rs: $rs_err"
|
|
110
|
+
fi
|
|
111
|
+
else
|
|
112
|
+
bad "config unknown key exit" "py: $py_err
|
|
113
|
+
rs: $rs_err"
|
|
114
|
+
fi
|
|
115
|
+
|
|
116
|
+
# 6. wait timeout semantics: exit 75 with same stderr shape.
|
|
117
|
+
py_err=$(PYTHONPATH="$ROOT/src" python3 -m host_pressure wait --until ok --timeout 0.5 --interval 0.2 --sample 0.1 --memory-busy 1 --memory-overloaded 2 2>&1; echo "exit:$?")
|
|
118
|
+
rs_err=$("$RS_BIN" wait --until ok --timeout 0.5 --interval 0.2 --sample 0.1 --memory-busy 1 --memory-overloaded 2 2>&1; echo "exit:$?")
|
|
119
|
+
if [ "$(echo "$py_err" | tail -n 1)" = "exit:75" ] && [ "$(echo "$rs_err" | tail -n 1)" = "exit:75" ]; then
|
|
120
|
+
ok "wait timeout exit 75"
|
|
121
|
+
else
|
|
122
|
+
bad "wait timeout exit" "py: $py_err
|
|
123
|
+
rs: $rs_err"
|
|
124
|
+
fi
|
|
125
|
+
|
|
126
|
+
echo "---"
|
|
127
|
+
echo "pass=$pass fail=$fail"
|
|
128
|
+
[ "$fail" -eq 0 ]
|