pingerplot 1.6.0__py3-none-any.whl
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.
- pingerplot/__init__.py +8 -0
- pingerplot/__main__.py +5 -0
- pingerplot/appicon.py +144 -0
- pingerplot/compare.py +257 -0
- pingerplot/ed25519.py +145 -0
- pingerplot/geoip.py +337 -0
- pingerplot/gfx.py +203 -0
- pingerplot/gui.py +1792 -0
- pingerplot/gui_charts.py +409 -0
- pingerplot/gui_history.py +684 -0
- pingerplot/gui_hopinfo.py +125 -0
- pingerplot/gui_recording.py +176 -0
- pingerplot/gui_settings.py +322 -0
- pingerplot/gui_updates.py +270 -0
- pingerplot/gui_widgets.py +248 -0
- pingerplot/headless.py +661 -0
- pingerplot/history.py +823 -0
- pingerplot/icmp.py +305 -0
- pingerplot/icmp_posix.py +456 -0
- pingerplot/investigate.py +205 -0
- pingerplot/launch.py +37 -0
- pingerplot/locating.py +248 -0
- pingerplot/model.py +410 -0
- pingerplot/monitor.py +1404 -0
- pingerplot/places.py +259 -0
- pingerplot/routes.py +112 -0
- pingerplot/selfcheck.py +97 -0
- pingerplot/selftest.py +76 -0
- pingerplot/settings.py +98 -0
- pingerplot/tcpudp.py +479 -0
- pingerplot/theme.py +576 -0
- pingerplot/tkthreads.py +68 -0
- pingerplot/tray.py +373 -0
- pingerplot/trouble.py +129 -0
- pingerplot/update_key.py +8 -0
- pingerplot/updater.py +499 -0
- pingerplot/winplatform.py +366 -0
- pingerplot/worldmap.py +141 -0
- pingerplot/xdg.py +198 -0
- pingerplot-1.6.0.dist-info/METADATA +583 -0
- pingerplot-1.6.0.dist-info/RECORD +45 -0
- pingerplot-1.6.0.dist-info/WHEEL +5 -0
- pingerplot-1.6.0.dist-info/entry_points.txt +5 -0
- pingerplot-1.6.0.dist-info/licenses/LICENSE +21 -0
- pingerplot-1.6.0.dist-info/top_level.txt +1 -0
pingerplot/headless.py
ADDED
|
@@ -0,0 +1,661 @@
|
|
|
1
|
+
"""Headless / service mode — run monitors from a config file, no GUI.
|
|
2
|
+
|
|
3
|
+
For unattended monitoring on a box with no desktop session (a server, a VLAN
|
|
4
|
+
probe host). Drives the same engine as the GUI; each target logs to its own
|
|
5
|
+
crash-safe, size-capped CSV. Runs until Ctrl-C / SIGTERM, then stops cleanly —
|
|
6
|
+
designed to sit behind Windows Task Scheduler.
|
|
7
|
+
|
|
8
|
+
python -m pingerplot.headless --init monitor.json # write a starter config
|
|
9
|
+
python -m pingerplot.headless monitor.json # run it (Ctrl-C to stop)
|
|
10
|
+
|
|
11
|
+
Pure standard library (json + argparse + signal), like the rest of the app.
|
|
12
|
+
"""
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import argparse
|
|
16
|
+
import csv
|
|
17
|
+
import json
|
|
18
|
+
import os
|
|
19
|
+
import signal
|
|
20
|
+
import sys
|
|
21
|
+
import threading
|
|
22
|
+
import time
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
from typing import Callable, List, Optional, Tuple
|
|
25
|
+
|
|
26
|
+
from . import __version__, compare as _compare, history, icmp
|
|
27
|
+
from .model import csv_safe, mos, mos_label
|
|
28
|
+
from .monitor import Monitor, per_target_log_path
|
|
29
|
+
|
|
30
|
+
RESTART_DELAY_S = 30.0 # wait this long before restarting a stopped target
|
|
31
|
+
RESTART_DELAY_MAX_S = 300.0 # ...doubling to this ceiling while it keeps failing
|
|
32
|
+
|
|
33
|
+
SAMPLE_CONFIG = {
|
|
34
|
+
"status_interval": 60,
|
|
35
|
+
"defaults": {
|
|
36
|
+
"interval": 2.5,
|
|
37
|
+
"timeout_ms": 1000,
|
|
38
|
+
"max_hops": 30,
|
|
39
|
+
"packet_type": "icmp",
|
|
40
|
+
"dscp": 0,
|
|
41
|
+
"source_ip": "",
|
|
42
|
+
"resolve_names": True,
|
|
43
|
+
"final_hop_only": False,
|
|
44
|
+
"alert_loss_pct": 20,
|
|
45
|
+
"alert_latency_ms": 250,
|
|
46
|
+
"alert_window": 20,
|
|
47
|
+
"alert_mos": 0,
|
|
48
|
+
"webhook_url": "",
|
|
49
|
+
},
|
|
50
|
+
"targets": [
|
|
51
|
+
{"target": "8.8.8.8", "log_path": "logs/google-dns.csv"},
|
|
52
|
+
{"target": "1.1.1.1", "log_path": "logs/cloudflare.csv", "final_hop_only": True},
|
|
53
|
+
],
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
# An Event rather than a bare global: the old flag was set by the signal
|
|
57
|
+
# handler and never cleared, so a second main() in the same process returned
|
|
58
|
+
# immediately. It also lets the run loop wait on it and exit the moment Ctrl-C
|
|
59
|
+
# lands instead of up to a quarter second later.
|
|
60
|
+
_STOP = threading.Event()
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def request_stop() -> None:
|
|
64
|
+
_STOP.set()
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def reset_stop() -> None:
|
|
68
|
+
_STOP.clear()
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def should_stop() -> bool:
|
|
72
|
+
return _STOP.is_set()
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _flag(opts: dict, key: str, default: bool) -> bool:
|
|
76
|
+
"""A true/false setting. bool("false") is True, so a quoted "false"
|
|
77
|
+
turned the option on (2026-11 review): only JSON's true and false (and 0
|
|
78
|
+
or 1) are taken; anything else skips the target with a reason."""
|
|
79
|
+
value = opts.get(key, default)
|
|
80
|
+
if isinstance(value, bool):
|
|
81
|
+
return value
|
|
82
|
+
if isinstance(value, int) and value in (0, 1):
|
|
83
|
+
return bool(value)
|
|
84
|
+
raise ValueError(f"{key} must be true or false (no quotes), not {value!r}")
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _target_options(defaults: dict, target_cfg: dict) -> Tuple[str, dict]:
|
|
88
|
+
"""Merge ``defaults`` with a target's overrides and return
|
|
89
|
+
``(target, start_kwargs)``. Unknown keys are ignored; ``alert_sound`` is
|
|
90
|
+
always off (no point beeping a headless box)."""
|
|
91
|
+
opts = dict(defaults)
|
|
92
|
+
opts.update(target_cfg)
|
|
93
|
+
target = str(opts.get("target", "")).strip()
|
|
94
|
+
kwargs = dict(
|
|
95
|
+
interval=float(opts.get("interval", 2.5)),
|
|
96
|
+
timeout_ms=int(opts.get("timeout_ms", 1000)),
|
|
97
|
+
max_hops=int(opts.get("max_hops", 30)),
|
|
98
|
+
resolve_names=_flag(opts, "resolve_names", True),
|
|
99
|
+
packet_size=int(opts.get("packet_size", 32)),
|
|
100
|
+
send_delay_ms=int(opts.get("send_delay_ms", 0)),
|
|
101
|
+
final_hop_only=_flag(opts, "final_hop_only", False),
|
|
102
|
+
packet_type=str(opts.get("packet_type", "icmp")),
|
|
103
|
+
port=int(opts.get("port", 443)),
|
|
104
|
+
dscp=int(opts.get("dscp", 0)),
|
|
105
|
+
source_ip=str(opts.get("source_ip", "")),
|
|
106
|
+
log_path=str(opts.get("log_path", "")),
|
|
107
|
+
alert_enabled=_flag(opts, "alert_enabled", True),
|
|
108
|
+
alert_loss_pct=float(opts.get("alert_loss_pct", 20)),
|
|
109
|
+
alert_latency_ms=float(opts.get("alert_latency_ms", 250)),
|
|
110
|
+
alert_window=int(opts.get("alert_window", 20)),
|
|
111
|
+
alert_mos=float(opts.get("alert_mos", 0)),
|
|
112
|
+
alert_sound=False,
|
|
113
|
+
webhook_url=str(opts.get("webhook_url", "")),
|
|
114
|
+
)
|
|
115
|
+
return target, kwargs
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class Target:
|
|
119
|
+
"""A configured target, its Monitor, and what is needed to restart it.
|
|
120
|
+
|
|
121
|
+
The options are kept because a restart must reproduce the configured run --
|
|
122
|
+
starting again with defaults would silently drop the log path, the alert
|
|
123
|
+
thresholds and the probe mode from the config file.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
__slots__ = ("name", "monitor", "kwargs", "retry_at", "retry_delay", "restarts",
|
|
127
|
+
"last_event")
|
|
128
|
+
|
|
129
|
+
def __init__(self, name: str, monitor: Monitor, kwargs: dict) -> None:
|
|
130
|
+
self.name = name
|
|
131
|
+
self.monitor = monitor
|
|
132
|
+
self.kwargs = kwargs
|
|
133
|
+
self.retry_at = 0.0 # 0 == not currently scheduled for a retry
|
|
134
|
+
self.retry_delay = RESTART_DELAY_S
|
|
135
|
+
self.restarts = 0
|
|
136
|
+
self.last_event = -1 # newest event id already printed
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def supervise(targets: List[Target], now: float,
|
|
140
|
+
log: Callable[[str], None] = print) -> None:
|
|
141
|
+
"""Restart any target whose monitor has stopped.
|
|
142
|
+
|
|
143
|
+
Monitor._run exits with running = False on a name it cannot resolve, or on
|
|
144
|
+
a TCP/UDP traceroute refused for want of Administrator. Nothing used to
|
|
145
|
+
look at that, so a target whose DNS failed at start-up stayed dead for the
|
|
146
|
+
life of the process -- which is the *normal* case for the documented
|
|
147
|
+
deployment, a Task Scheduler job at logon or boot that routinely starts
|
|
148
|
+
before DNS is up. An unattended monitor that silently monitors nothing is
|
|
149
|
+
worse than one that never started: the CSV it should be filling just stays
|
|
150
|
+
empty until somebody goes looking for the data.
|
|
151
|
+
|
|
152
|
+
A stopped target is not restarted the instant it is noticed. The first pass
|
|
153
|
+
schedules the retry, the next one past that time performs it, and the delay
|
|
154
|
+
doubles up to RESTART_DELAY_MAX_S while it keeps failing -- so a genuinely
|
|
155
|
+
bad hostname settles into a five-minute poll instead of resolving twice a
|
|
156
|
+
minute forever.
|
|
157
|
+
"""
|
|
158
|
+
for t in targets:
|
|
159
|
+
mon = t.monitor
|
|
160
|
+
if mon.running and mon.route_len > 0:
|
|
161
|
+
# Actually monitoring: any earlier backoff is history. Resetting on
|
|
162
|
+
# `running` alone would be wrong, since start() sets it before the
|
|
163
|
+
# trace has had a chance to fail.
|
|
164
|
+
t.retry_at = 0.0
|
|
165
|
+
t.retry_delay = RESTART_DELAY_S
|
|
166
|
+
continue
|
|
167
|
+
if mon.running:
|
|
168
|
+
continue # started, still tracing -- give it time
|
|
169
|
+
if t.retry_at == 0.0:
|
|
170
|
+
log(f" {t.name}: stopped ({mon.status}); "
|
|
171
|
+
f"retrying in {t.retry_delay:.0f}s")
|
|
172
|
+
t.retry_at = now + t.retry_delay
|
|
173
|
+
continue
|
|
174
|
+
if now < t.retry_at:
|
|
175
|
+
continue
|
|
176
|
+
t.restarts += 1
|
|
177
|
+
log(f" {t.name}: restarting (attempt {t.restarts})")
|
|
178
|
+
# start() clears the event log and numbers from 0 again; a cursor left
|
|
179
|
+
# at the old run's last id would hide the new run's events.
|
|
180
|
+
t.last_event = -1
|
|
181
|
+
try:
|
|
182
|
+
mon.start(t.name, **t.kwargs)
|
|
183
|
+
except (OSError, ValueError, TypeError) as exc:
|
|
184
|
+
# One bad target must never take the others down with it.
|
|
185
|
+
log(f" {t.name}: restart failed: {exc}")
|
|
186
|
+
t.retry_delay = min(t.retry_delay * 2, RESTART_DELAY_MAX_S)
|
|
187
|
+
t.retry_at = now + t.retry_delay
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def _build_monitors(cfg: dict, base_dir: Path,
|
|
191
|
+
recorder: "Optional[history.Recorder]" = None) -> List[Target]:
|
|
192
|
+
"""Start a Monitor per configured target. Relative ``log_path``s resolve
|
|
193
|
+
next to the config file (so it works regardless of the working directory).
|
|
194
|
+
A malformed target is skipped with a warning rather than killing the run."""
|
|
195
|
+
defaults = cfg.get("defaults", {}) or {}
|
|
196
|
+
parsed = []
|
|
197
|
+
for tcfg in cfg.get("targets", []):
|
|
198
|
+
try:
|
|
199
|
+
target, kwargs = _target_options(defaults, tcfg)
|
|
200
|
+
except (ValueError, TypeError, AttributeError) as exc:
|
|
201
|
+
print(f"Skipping target {tcfg!r}: {exc}", file=sys.stderr)
|
|
202
|
+
continue
|
|
203
|
+
if not target:
|
|
204
|
+
continue
|
|
205
|
+
lp = kwargs.get("log_path", "")
|
|
206
|
+
if lp and not os.path.isabs(lp):
|
|
207
|
+
kwargs["log_path"] = str(base_dir / lp)
|
|
208
|
+
parsed.append((tcfg, target, kwargs))
|
|
209
|
+
|
|
210
|
+
# A log_path in `defaults` puts every target on one file. The probe CSV
|
|
211
|
+
# has no target column, so those rows could not be told apart, and the
|
|
212
|
+
# monitors would roll the file over underneath each other. Split only the
|
|
213
|
+
# paths that are actually shared: a per-target path is left as written.
|
|
214
|
+
def _key(path: str) -> str:
|
|
215
|
+
return os.path.normcase(os.path.abspath(path))
|
|
216
|
+
|
|
217
|
+
uses: dict = {}
|
|
218
|
+
for _tcfg, _target, kwargs in parsed:
|
|
219
|
+
if kwargs["log_path"]:
|
|
220
|
+
uses[_key(kwargs["log_path"])] = uses.get(_key(kwargs["log_path"]), 0) + 1
|
|
221
|
+
for _tcfg, target, kwargs in parsed:
|
|
222
|
+
lp = kwargs["log_path"]
|
|
223
|
+
if lp and uses[_key(lp)] > 1:
|
|
224
|
+
kwargs["log_path"] = per_target_log_path(lp, target)
|
|
225
|
+
print(f" {target}: log_path is shared with other targets; "
|
|
226
|
+
f"logging to {kwargs['log_path']}")
|
|
227
|
+
|
|
228
|
+
targets: List[Target] = []
|
|
229
|
+
for tcfg, target, kwargs in parsed:
|
|
230
|
+
try:
|
|
231
|
+
if kwargs["log_path"]:
|
|
232
|
+
# The makedirs covers absolute paths too. It used to sit inside
|
|
233
|
+
# the relative branch, so an absolute log_path under a
|
|
234
|
+
# directory that did not exist failed to open and logged
|
|
235
|
+
# nothing -- which, until now, said nothing either.
|
|
236
|
+
os.makedirs(os.path.dirname(kwargs["log_path"]) or ".", exist_ok=True)
|
|
237
|
+
m = Monitor(recorder=recorder)
|
|
238
|
+
m.start(target, **kwargs)
|
|
239
|
+
targets.append(Target(target, m, kwargs))
|
|
240
|
+
except (ValueError, TypeError, OSError) as exc:
|
|
241
|
+
print(f"Skipping target {tcfg!r}: {exc}", file=sys.stderr)
|
|
242
|
+
return targets
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def print_status(targets: List[Target], log: Callable[[str], None] = print) -> None:
|
|
246
|
+
"""One console line per target - reuses the cheap Monitor.summary()."""
|
|
247
|
+
log(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] {len(targets)} target(s):")
|
|
248
|
+
for t in targets:
|
|
249
|
+
m = t.monitor
|
|
250
|
+
n_hops, loss, avg, jitter, reached = m.summary()
|
|
251
|
+
score = mos(avg, jitter, loss) if (n_hops and reached) else None
|
|
252
|
+
loss_s = f"{loss:.0f}%" if loss is not None else "-"
|
|
253
|
+
avg_s = f"{avg:.0f}ms" if avg is not None else "-"
|
|
254
|
+
mos_s = f"{score:.1f}" if score is not None else "-"
|
|
255
|
+
if not m.running:
|
|
256
|
+
tail = f" (stopped: {m.status})"
|
|
257
|
+
elif not reached:
|
|
258
|
+
tail = " (no reply yet)"
|
|
259
|
+
else:
|
|
260
|
+
tail = f" (restarted {t.restarts}x)" if t.restarts else ""
|
|
261
|
+
log(f" {t.name:<24} hops={n_hops:<3} loss={loss_s:<5} "
|
|
262
|
+
f"avg={avg_s:<8} MOS={mos_s}{tail}")
|
|
263
|
+
_flush()
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def _flush() -> None:
|
|
267
|
+
"""Under pythonw.exe (the README's Task Scheduler line) there is no
|
|
268
|
+
stdout at all: sys.stdout is None, and flushing it raised AttributeError
|
|
269
|
+
out of the run loop at the first status line or event."""
|
|
270
|
+
if sys.stdout is not None:
|
|
271
|
+
sys.stdout.flush()
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def _tolerant_streams() -> None:
|
|
275
|
+
"""Redirected to a file, stdout is cp1252 in strict mode: a hostname,
|
|
276
|
+
target or status it can't encode would raise out of print_status,
|
|
277
|
+
supervise or a report. Replace the character instead."""
|
|
278
|
+
for stream in (sys.stdout, sys.stderr):
|
|
279
|
+
if stream is not None and hasattr(stream, "reconfigure"):
|
|
280
|
+
try:
|
|
281
|
+
stream.reconfigure(errors="backslashreplace")
|
|
282
|
+
except (ValueError, OSError):
|
|
283
|
+
pass
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def _console(line: str) -> None:
|
|
287
|
+
"""print(), minus the one way it can kill the service. Event text carries
|
|
288
|
+
reverse-DNS names, which are whatever a PTR record says, and a Windows
|
|
289
|
+
console is still cp1252/cp437: an unencodable character would raise out of
|
|
290
|
+
the run loop and stop every monitor."""
|
|
291
|
+
enc = getattr(sys.stdout, "encoding", None) or "ascii"
|
|
292
|
+
print(line.encode(enc, "replace").decode(enc, "replace"))
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def print_events(targets: List[Target], log: Optional[Callable[[str], None]] = None) -> None:
|
|
296
|
+
"""Print each target's events not printed yet: alerts and clears, route
|
|
297
|
+
changes, and the warnings (probe log could not be opened or rolled over,
|
|
298
|
+
webhook not delivered) that the GUI shows in its Events tab. Without this
|
|
299
|
+
a headless box -- the one nobody is watching -- reported none of them."""
|
|
300
|
+
out = log or _console
|
|
301
|
+
printed = False
|
|
302
|
+
for t in targets:
|
|
303
|
+
new, last = t.monitor.events_after(t.last_event)
|
|
304
|
+
t.last_event = last
|
|
305
|
+
for e in new:
|
|
306
|
+
ts = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(e.t))
|
|
307
|
+
out(f"[{ts}] {t.name}: {e.kind.upper():<5} {e.text}")
|
|
308
|
+
printed = True
|
|
309
|
+
if printed:
|
|
310
|
+
_flush()
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def shutdown_all(targets: List[Target]) -> None:
|
|
314
|
+
"""Stop every target, signalling them all before waiting on any. A
|
|
315
|
+
monitor mid-round takes up to a reply timeout to wind down; one at a time,
|
|
316
|
+
Ctrl-C on a many-target config waited for the sum of them."""
|
|
317
|
+
for t in targets:
|
|
318
|
+
t.monitor.request_stop()
|
|
319
|
+
for t in targets:
|
|
320
|
+
t.monitor.shutdown()
|
|
321
|
+
# Then their shared history, so the last minutes they measured are saved.
|
|
322
|
+
recorders = {id(t.monitor.recorder): t.monitor.recorder for t in targets
|
|
323
|
+
if t.monitor.recorder is not None}
|
|
324
|
+
for rec in recorders.values():
|
|
325
|
+
rec.close()
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def report_rows(monitor: Monitor) -> List[dict]:
|
|
329
|
+
"""The per-hop summary a report prints, as plain data.
|
|
330
|
+
|
|
331
|
+
Kept separate from the formatting so the same numbers feed the console
|
|
332
|
+
table, the CSV, and the tests, instead of each growing its own version.
|
|
333
|
+
"""
|
|
334
|
+
views, _status, _ip, _in = monitor.snapshot()
|
|
335
|
+
last_ttl = views[-1].ttl if views else None
|
|
336
|
+
rows = []
|
|
337
|
+
for v in views:
|
|
338
|
+
rows.append({
|
|
339
|
+
"hop": v.ttl,
|
|
340
|
+
"ip": v.address or "*",
|
|
341
|
+
"hostname": v.hostname or "",
|
|
342
|
+
"loss_pct": v.loss_pct,
|
|
343
|
+
"sent": v.sent,
|
|
344
|
+
"last": v.current,
|
|
345
|
+
"avg": v.avg,
|
|
346
|
+
"best": v.best,
|
|
347
|
+
"worst": v.worst,
|
|
348
|
+
"jitter": v.jitter,
|
|
349
|
+
# MOS describes the end-to-end path. On an intermediate router it
|
|
350
|
+
# would be measuring how eagerly that box answers ICMP, not how
|
|
351
|
+
# the path performs, so only the destination gets one.
|
|
352
|
+
"mos": mos(v.avg, v.jitter, v.loss_pct) if v.ttl == last_ttl else None,
|
|
353
|
+
"is_dest": v.ttl == last_ttl,
|
|
354
|
+
})
|
|
355
|
+
return rows
|
|
356
|
+
|
|
357
|
+
|
|
358
|
+
def _num(v, width=6, places=1) -> str:
|
|
359
|
+
return f"{'-':>{width}}" if v is None else f"{v:>{width}.{places}f}"
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
def format_report(name: str, monitor: Monitor) -> List[str]:
|
|
363
|
+
"""An MTR-style table for one target, ready to print or paste in a ticket."""
|
|
364
|
+
rows = report_rows(monitor)
|
|
365
|
+
head = f"{name} [{monitor.target_ip or '?'}]"
|
|
366
|
+
proto = monitor.packet_type.upper()
|
|
367
|
+
if monitor.packet_type != "icmp":
|
|
368
|
+
proto += f":{monitor.port}"
|
|
369
|
+
# A marked or interface-pinned run measured a different thing from a plain
|
|
370
|
+
# one; the header has to say so or two reports cannot be compared.
|
|
371
|
+
if monitor.dscp:
|
|
372
|
+
proto += f", DSCP {monitor.dscp}"
|
|
373
|
+
if monitor.source_ip:
|
|
374
|
+
proto += f", from {monitor.source_ip}"
|
|
375
|
+
lines = [
|
|
376
|
+
"",
|
|
377
|
+
head,
|
|
378
|
+
f" {proto}, {monitor.interval:g}s interval, {monitor.timeout_ms}ms timeout"
|
|
379
|
+
f"{'' if monitor.reached_target else ' *** destination never answered ***'}",
|
|
380
|
+
f" {'Hop':>3} {'Address':<16} {'Loss':>6} {'Sent':>5} {'Last':>6} "
|
|
381
|
+
f"{'Avg':>6} {'Best':>6} {'Wrst':>6} {'Jitr':>6} Hostname",
|
|
382
|
+
" " + "-" * 92,
|
|
383
|
+
]
|
|
384
|
+
for r in rows:
|
|
385
|
+
marker = "*" if r["is_dest"] else " "
|
|
386
|
+
lines.append(
|
|
387
|
+
f" {marker}{r['hop']:>3} {r['ip']:<16} {r['loss_pct']:>5.1f}% "
|
|
388
|
+
f"{r['sent']:>5} {_num(r['last'])} {_num(r['avg'])} {_num(r['best'])} "
|
|
389
|
+
f"{_num(r['worst'])} {_num(r['jitter'])} {r['hostname']}"
|
|
390
|
+
)
|
|
391
|
+
dest = rows[-1] if rows else None
|
|
392
|
+
if dest and dest["mos"] is not None:
|
|
393
|
+
lines.append(f" destination MOS {dest['mos']:.2f} ({mos_label(dest['mos'])})")
|
|
394
|
+
elif not rows:
|
|
395
|
+
lines.append(" (no hops - nothing answered)")
|
|
396
|
+
return lines
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
def write_report_csv(path: str, targets: List[Target]) -> None:
|
|
400
|
+
"""All targets' rows in one CSV, with a target column so several runs can
|
|
401
|
+
be concatenated and filtered."""
|
|
402
|
+
with open(path, "w", newline="", encoding="utf-8") as fh:
|
|
403
|
+
w = csv.writer(fh)
|
|
404
|
+
w.writerow(["target", "target_ip", "hop", "ip", "hostname", "loss_pct",
|
|
405
|
+
"sent", "last_ms", "avg_ms", "best_ms", "worst_ms",
|
|
406
|
+
"jitter_ms", "mos"])
|
|
407
|
+
for t in targets:
|
|
408
|
+
for r in report_rows(t.monitor):
|
|
409
|
+
w.writerow([
|
|
410
|
+
csv_safe(t.name), t.monitor.target_ip or "",
|
|
411
|
+
r["hop"], csv_safe(r["ip"]), csv_safe(r["hostname"]),
|
|
412
|
+
f"{r['loss_pct']:.1f}", r["sent"],
|
|
413
|
+
*[("" if r[k] is None else f"{r[k]:.1f}")
|
|
414
|
+
for k in ("last", "avg", "best", "worst", "jitter")],
|
|
415
|
+
"" if r["mos"] is None else f"{r['mos']:.2f}",
|
|
416
|
+
])
|
|
417
|
+
|
|
418
|
+
|
|
419
|
+
def run_report(targets: List[Target], rounds: int, log: Callable[[str], None] = print,
|
|
420
|
+
poll: float = 0.25, deadline: float = 0.0) -> int:
|
|
421
|
+
"""Collect ``rounds`` monitoring rounds, print a table per target, exit.
|
|
422
|
+
|
|
423
|
+
The counterpart to the run-forever loop: something a scheduled job or a
|
|
424
|
+
person writing up a ticket can invoke, get a fixed amount of evidence from,
|
|
425
|
+
and have exit. Returns 0 only if every target reached its destination, so a
|
|
426
|
+
script can branch on it.
|
|
427
|
+
|
|
428
|
+
The deadline exists because a target that cannot resolve never advances a
|
|
429
|
+
round at all; without one, a single bad hostname would hang the report
|
|
430
|
+
forever. Anything collected by then is still reported.
|
|
431
|
+
"""
|
|
432
|
+
for t in targets:
|
|
433
|
+
t.monitor._round = 0
|
|
434
|
+
if deadline <= 0.0:
|
|
435
|
+
slowest = max((t.monitor.interval for t in targets), default=1.0)
|
|
436
|
+
longest = max((t.monitor.timeout_ms for t in targets), default=1000) / 1000.0
|
|
437
|
+
deadline = rounds * (slowest + longest) + longest * 2 + 15.0
|
|
438
|
+
log(f"Collecting {rounds} round(s) from {len(targets)} target(s)...")
|
|
439
|
+
|
|
440
|
+
end = time.monotonic() + deadline
|
|
441
|
+
while not should_stop() and time.monotonic() < end:
|
|
442
|
+
print_events(targets, None if log is print else log)
|
|
443
|
+
if all(t.monitor._round >= rounds or not t.monitor.running for t in targets):
|
|
444
|
+
break
|
|
445
|
+
_STOP.wait(poll)
|
|
446
|
+
|
|
447
|
+
incomplete = [t.name for t in targets if t.monitor._round < rounds]
|
|
448
|
+
if incomplete:
|
|
449
|
+
log(f" (short of {rounds} rounds: {', '.join(incomplete)})")
|
|
450
|
+
for t in targets:
|
|
451
|
+
for line in format_report(t.name, t.monitor):
|
|
452
|
+
log(line)
|
|
453
|
+
return 0 if all(t.monitor.reached_target for t in targets) else 1
|
|
454
|
+
|
|
455
|
+
|
|
456
|
+
def print_comparison(targets: List[Target], baseline_path: str,
|
|
457
|
+
log: Callable[[str], None] = print) -> None:
|
|
458
|
+
"""Diff each target against a saved session.
|
|
459
|
+
|
|
460
|
+
One baseline file against several targets is deliberate: the usual shape is
|
|
461
|
+
one saved session per path, so a mismatch is normal and quiet -- a target
|
|
462
|
+
with nothing to compare against simply says so instead of erroring the run.
|
|
463
|
+
"""
|
|
464
|
+
try:
|
|
465
|
+
with open(baseline_path, encoding="utf-8-sig") as fh:
|
|
466
|
+
data = json.load(fh)
|
|
467
|
+
except (OSError, ValueError) as exc:
|
|
468
|
+
log(f"Cannot read baseline {baseline_path}: {exc}")
|
|
469
|
+
return
|
|
470
|
+
if not isinstance(data, dict):
|
|
471
|
+
# main() only catches OSError around the report, so anything raised
|
|
472
|
+
# here died as a traceback after the tables had already printed.
|
|
473
|
+
log(f"Cannot read baseline {baseline_path}: not a PingerPlot session")
|
|
474
|
+
return
|
|
475
|
+
base_stats = _compare.stats_from_session(data)
|
|
476
|
+
base_name = str(data.get("target_input") or baseline_path)
|
|
477
|
+
if not base_stats:
|
|
478
|
+
log(f"Baseline {baseline_path} has no hop data to compare against.")
|
|
479
|
+
return
|
|
480
|
+
for t in targets:
|
|
481
|
+
# Through snapshot(), not _hops: run_report stops waiting when the
|
|
482
|
+
# round count is reached but does not stop the monitors, so the probe
|
|
483
|
+
# thread is still appending here. Reaching into the private list and
|
|
484
|
+
# iterating a live hop's deque raises "deque mutated during iteration"
|
|
485
|
+
# -- a RuntimeError, which main()'s `except OSError` does not catch, so
|
|
486
|
+
# the process died with a traceback AFTER printing the report and never
|
|
487
|
+
# wrote --report-csv.
|
|
488
|
+
views, _status, _ip, _input = t.monitor.snapshot()
|
|
489
|
+
now = _compare.stats_from_views(views)
|
|
490
|
+
if not now:
|
|
491
|
+
log("")
|
|
492
|
+
log(f"{t.name}: nothing to compare (no hops yet)")
|
|
493
|
+
continue
|
|
494
|
+
cmp_ = _compare.compare(base_stats, now, target=t.name)
|
|
495
|
+
for line in _compare.format_comparison(cmp_, base_name):
|
|
496
|
+
log(line)
|
|
497
|
+
|
|
498
|
+
|
|
499
|
+
def _warn_if_icmp_unusable(targets: List[Target], out=None) -> bool:
|
|
500
|
+
"""Say so when ICMP targets are configured and the backend cannot probe.
|
|
501
|
+
|
|
502
|
+
The GUI puts this in a dialog. A headless box is where it matters more,
|
|
503
|
+
because nobody is watching one -- every probe raises inside icmp.ping, gets
|
|
504
|
+
swallowed by _gather_range and is recorded as a timeout, so the operator
|
|
505
|
+
gets a clean-looking report saying the destination never answered and an
|
|
506
|
+
exit status of 1. That points them at the network when the actual fix, on
|
|
507
|
+
Linux, is one sysctl.
|
|
508
|
+
|
|
509
|
+
Only fires when a target actually needs the backend: TCP and UDP modes do
|
|
510
|
+
not use it, and warning a TCP-only config would be noise.
|
|
511
|
+
"""
|
|
512
|
+
if icmp.is_available():
|
|
513
|
+
return False
|
|
514
|
+
using = [t.name for t in targets if t.monitor.packet_type == "icmp"]
|
|
515
|
+
if not using:
|
|
516
|
+
return False
|
|
517
|
+
out = out if out is not None else sys.stderr
|
|
518
|
+
print(f"WARNING: ICMP backend unavailable - {icmp.unavailable_reason()}",
|
|
519
|
+
file=out)
|
|
520
|
+
print(f" {len(using)} ICMP target(s) will report no replies: "
|
|
521
|
+
f"{', '.join(using)}", file=out)
|
|
522
|
+
print(" TCP and UDP probe modes do not use this backend.", file=out)
|
|
523
|
+
return True
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
def _install_signal_handlers() -> None:
|
|
527
|
+
def _handle(_signum, _frame):
|
|
528
|
+
request_stop()
|
|
529
|
+
signal.signal(signal.SIGINT, _handle)
|
|
530
|
+
try:
|
|
531
|
+
signal.signal(signal.SIGTERM, _handle) # not deliverable on every platform
|
|
532
|
+
except (ValueError, AttributeError, OSError):
|
|
533
|
+
pass
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def main(argv=None) -> int:
|
|
537
|
+
_tolerant_streams()
|
|
538
|
+
ap = argparse.ArgumentParser(
|
|
539
|
+
prog="pingerplot.headless",
|
|
540
|
+
description="Run PingerPlot monitors from a config file, no GUI.")
|
|
541
|
+
ap.add_argument("config", nargs="?", help="path to a JSON config file")
|
|
542
|
+
ap.add_argument("--version", action="store_true",
|
|
543
|
+
help="print the version and how this copy runs, then exit")
|
|
544
|
+
ap.add_argument("--init", action="store_true",
|
|
545
|
+
help="write a starter config to CONFIG and exit")
|
|
546
|
+
ap.add_argument("--status-interval", type=float, default=None,
|
|
547
|
+
help="seconds between status lines (overrides config; 0 = silent)")
|
|
548
|
+
ap.add_argument("--report", type=int, metavar="N", default=None,
|
|
549
|
+
help="collect N rounds, print a summary table per target, then "
|
|
550
|
+
"exit. Exit status is 0 only if every target reached its "
|
|
551
|
+
"destination, so a script can branch on it.")
|
|
552
|
+
ap.add_argument("--report-csv", metavar="PATH", default=None,
|
|
553
|
+
help="with --report, also write the tables to a CSV file")
|
|
554
|
+
ap.add_argument("--baseline", metavar="PATH", default=None,
|
|
555
|
+
help="with --report, also diff each target against a saved "
|
|
556
|
+
"session file (File > Save session in the GUI). Answers "
|
|
557
|
+
"'is this path worse than it was' rather than only "
|
|
558
|
+
"'what does it look like now'.")
|
|
559
|
+
args = ap.parse_args(argv)
|
|
560
|
+
if args.version:
|
|
561
|
+
frozen = "Windows executable" if getattr(sys, "frozen", False) else "from source"
|
|
562
|
+
print(f"PingerPlot {__version__} headless ({frozen}, Python {sys.version.split()[0]})")
|
|
563
|
+
print(f"ICMP backend: {'available' if icmp.is_available() else icmp.unavailable_reason()}")
|
|
564
|
+
return 0
|
|
565
|
+
if not args.config:
|
|
566
|
+
ap.error("the config file is required (or --init CONFIG to write one)")
|
|
567
|
+
cfg_path = Path(args.config)
|
|
568
|
+
|
|
569
|
+
if args.init:
|
|
570
|
+
if cfg_path.exists():
|
|
571
|
+
print(f"Refusing to overwrite existing {cfg_path}", file=sys.stderr)
|
|
572
|
+
return 1
|
|
573
|
+
cfg_path.write_text(json.dumps(SAMPLE_CONFIG, indent=2), encoding="utf-8")
|
|
574
|
+
print(f"Wrote starter config to {cfg_path} - edit it, then run without --init.")
|
|
575
|
+
return 0
|
|
576
|
+
|
|
577
|
+
try:
|
|
578
|
+
# utf-8-sig, not utf-8: this file is hand-authored on Windows, where
|
|
579
|
+
# PowerShell 5.1's `Set-Content -Encoding utf8` and a number of editors
|
|
580
|
+
# write a byte-order mark. Plain utf-8 rejects it outright, so the
|
|
581
|
+
# service refused to start on a config that looks perfectly fine in
|
|
582
|
+
# every editor that produced it. Reading as utf-8-sig strips a BOM if
|
|
583
|
+
# present and is identical to utf-8 otherwise.
|
|
584
|
+
cfg = json.loads(cfg_path.read_text(encoding="utf-8-sig"))
|
|
585
|
+
except (OSError, ValueError) as exc:
|
|
586
|
+
print(f"Cannot read config {cfg_path}: {exc}", file=sys.stderr)
|
|
587
|
+
return 1
|
|
588
|
+
if not isinstance(cfg, dict) or not cfg.get("targets"):
|
|
589
|
+
print("Config must be a JSON object with a non-empty 'targets' list.", file=sys.stderr)
|
|
590
|
+
return 1
|
|
591
|
+
|
|
592
|
+
try:
|
|
593
|
+
status_interval = (args.status_interval if args.status_interval is not None
|
|
594
|
+
else float(cfg.get("status_interval", 60)))
|
|
595
|
+
except (TypeError, ValueError) as exc:
|
|
596
|
+
# It was outside any handler: a traceback instead of a reason.
|
|
597
|
+
print(f"Config: status_interval must be a number of seconds ({exc}).", file=sys.stderr)
|
|
598
|
+
return 1
|
|
599
|
+
|
|
600
|
+
print(f"PingerPlot {__version__} headless - starting "
|
|
601
|
+
f"{len(cfg['targets'])} target(s). Ctrl-C to stop.")
|
|
602
|
+
# The same history database the window uses, so its History view shows
|
|
603
|
+
# what this runner recorded. A "recording" object in the config tunes it.
|
|
604
|
+
recorder = history.open_recorder(cfg, "headless")
|
|
605
|
+
if recorder is None:
|
|
606
|
+
print("History recording is off (\"recording\": {\"enabled\": false}).")
|
|
607
|
+
else:
|
|
608
|
+
print(f"Recording history to {recorder.path}")
|
|
609
|
+
targets = _build_monitors(cfg, cfg_path.resolve().parent, recorder)
|
|
610
|
+
if not targets:
|
|
611
|
+
print("No valid targets to monitor.", file=sys.stderr)
|
|
612
|
+
if recorder is not None:
|
|
613
|
+
recorder.close()
|
|
614
|
+
return 1
|
|
615
|
+
_warn_if_icmp_unusable(targets)
|
|
616
|
+
|
|
617
|
+
reset_stop() # a previous run in this process must not linger
|
|
618
|
+
_install_signal_handlers()
|
|
619
|
+
|
|
620
|
+
if args.report is not None:
|
|
621
|
+
if args.report < 1:
|
|
622
|
+
print("--report needs a round count of at least 1", file=sys.stderr)
|
|
623
|
+
shutdown_all(targets)
|
|
624
|
+
return 2
|
|
625
|
+
try:
|
|
626
|
+
rc = run_report(targets, args.report)
|
|
627
|
+
if args.baseline:
|
|
628
|
+
print_comparison(targets, args.baseline)
|
|
629
|
+
if args.report_csv:
|
|
630
|
+
write_report_csv(args.report_csv, targets)
|
|
631
|
+
print(f"\nWrote {args.report_csv}")
|
|
632
|
+
except OSError as exc:
|
|
633
|
+
print(f"Report failed: {exc}", file=sys.stderr)
|
|
634
|
+
rc = 1
|
|
635
|
+
finally:
|
|
636
|
+
shutdown_all(targets)
|
|
637
|
+
return rc
|
|
638
|
+
|
|
639
|
+
last_status = 0.0
|
|
640
|
+
try:
|
|
641
|
+
while not should_stop():
|
|
642
|
+
now = time.monotonic()
|
|
643
|
+
# Bring back anything that stopped -- a target whose name did not
|
|
644
|
+
# resolve at boot would otherwise stay dead for the whole run.
|
|
645
|
+
supervise(targets, now)
|
|
646
|
+
print_events(targets)
|
|
647
|
+
if status_interval > 0 and now - last_status >= status_interval:
|
|
648
|
+
print_status(targets)
|
|
649
|
+
last_status = now
|
|
650
|
+
_STOP.wait(0.25) # exits the moment Ctrl-C lands
|
|
651
|
+
except KeyboardInterrupt:
|
|
652
|
+
pass
|
|
653
|
+
finally:
|
|
654
|
+
print("Stopping...")
|
|
655
|
+
shutdown_all(targets)
|
|
656
|
+
print("Stopped.")
|
|
657
|
+
return 0
|
|
658
|
+
|
|
659
|
+
|
|
660
|
+
if __name__ == "__main__":
|
|
661
|
+
raise SystemExit(main())
|