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/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())