Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Show job IDs and watch checkpoint progress

Cinna Davised5e1b404ca1
diff --git a/README.md b/README.md
index 5aebab6..a76de55 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,11 @@ Use a new output directory for each experiment. Automatic CI checks installation
This scans the complete recording and saves an inspectable job. To permit historical search, add `--start-utc` and `--end-utc` for a defensible recording-start window, `--time-source` describing its evidence, and `--online` for public data acquisition. Missing clock evidence returns `needs_input`. Initial acquisition can take hours and tens of gigabytes; [the workflow guide](docs/PRODUCT.md) covers caching, runtime limits and resuming stopped jobs.
+The command prints a job ID when queued. In another terminal, run
+`.venv/bin/dopplergeist job JOB_ID --jobs jobs --watch` to follow local
+checkpoint pieces and their recent rate. Piece sizes vary, so the rate is not an
+estimate of the remaining time.
+
### Discover events in a recording
Automatic discovery scans an entire recording for moving acoustic frequency patterns **without hand-selecting event windows or frequency bands**. Replace `path/to/recording.mp3` with your real recording; this step needs no flight-data download or data-service credentials:
diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md
index 9498917..e6a1c0f 100644
--- a/docs/PRODUCT.md
+++ b/docs/PRODUCT.md
@@ -48,9 +48,17 @@ dopplergeist analyze recording.mp3 --jobs jobs --online --max-runtime 14400 \
--start-utc "$RECORDING_START_UTC_MIN" --end-utc "$RECORDING_START_UTC_MAX" \
--time-source 'Your evidence for this recording time'
dopplergeist job JOB_ID --jobs jobs
+dopplergeist job JOB_ID --jobs jobs --watch --interval 10
dopplergeist resume JOB_ID --jobs jobs
```
+`analyze` prints the job ID and a monitor command to standard error as soon as
+the upload is queued. `job --watch` reports the number and recent rate of local
+checkpoint pieces on standard error, then writes the final job JSON to standard
+output. Pieces can have different sizes and costs, so their rate is not an ETA;
+remotely staged work appears after it is imported. Pressing Ctrl-C stops the
+watcher without cancelling the analysis.
+
The UTC window bounds the recording start, not the event occurrence or upload.
Missing time is a required-input result. Scores are ranking statistics, not
probabilities. Sensitivity radii must not be described as calibrated confidence.
diff --git a/src/dopplergeist/cli.py b/src/dopplergeist/cli.py
index c807c2f..ad46a76 100644
--- a/src/dopplergeist/cli.py
+++ b/src/dopplergeist/cli.py
@@ -1,6 +1,9 @@
import argparse
import json
import math
+import shlex
+import sys
+import time
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
import uuid
@@ -68,6 +71,8 @@ def main():
job=sub.add_parser("job",help="Read a persisted job result without rerunning it")
job.add_argument("job_id",type=job_identifier)
job.add_argument("--jobs",default="jobs")
+ job.add_argument("--watch",action="store_true",help="Watch local checkpoints until the job stops")
+ job.add_argument("--interval",type=positive_runtime,default=10,help="Watch interval in seconds")
resume=sub.add_parser("resume",help="Resume a stopped job after completed audio discovery")
resume.add_argument("job_id",type=job_identifier)
resume.add_argument("--jobs",default="jobs")
@@ -109,15 +114,37 @@ def main():
try:
with audio.open("rb") as source:
queued=manager.submit(request,source,audio.stat().st_size,suffix=audio.suffix)
+ print(f"Job {queued['job_id']} started. Monitor: dopplergeist job {queued['job_id']} "
+ f"--jobs {shlex.quote(str(args.jobs))} --watch",file=sys.stderr,flush=True)
print(json.dumps(manager.wait(queued["job_id"]),indent=2))
finally:
manager.close()
elif args.command=="job":
from .jobs import read_json
+ directory=Path(args.jobs)/args.job_id
+ previous_count=previous_time=None
try:
- value = read_json(Path(args.jobs)/args.job_id/"result.json")
- except (OSError, ValueError) as exc:
- parser.error(f"Could not read job {args.job_id}: {exc}")
+ while True:
+ try:
+ value = read_json(directory/"result.json")
+ except (OSError, ValueError) as exc:
+ parser.error(f"Could not read job {args.job_id}: {exc}")
+ if not args.watch:
+ break
+ count=sum(1 for path in (directory/"search").glob("tile-*.json") if not path.name.endswith(".error.json"))
+ now=time.monotonic()
+ rate=""
+ if previous_count is not None and count >= previous_count and now > previous_time:
+ rate=f", {(count-previous_count)*60/(now-previous_time):.1f} pieces/min since last check"
+ print(f"{value['status']} ({value.get('stage', 'no stage')}): "
+ f"{count} local checkpoint pieces{rate}",file=sys.stderr,flush=True)
+ if value["status"] in {"needs_input", "succeeded", "inconclusive", "failed", "cancelled"}:
+ break
+ previous_count,previous_time=count,now
+ time.sleep(args.interval)
+ except KeyboardInterrupt:
+ print("Stopped watching; the job continues.",file=sys.stderr)
+ raise SystemExit(130)
print(json.dumps(value,indent=2))
elif args.command=="resume":
from .jobs import JobManager
diff --git a/tests/test_real_cli_watch.py b/tests/test_real_cli_watch.py
new file mode 100644
index 0000000..ed0d858
--- /dev/null
+++ b/tests/test_real_cli_watch.py
@@ -0,0 +1,37 @@
+"""CLI monitoring against an existing real upload job, without cancelling it."""
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import time
+
+import pytest
+
+
+def test_watch_real_job_and_interrupt_only_the_watcher():
+ source = os.environ.get('DOPPLERGEIST_REAL_JOB_ROOT')
+ if not source:
+ pytest.skip('set DOPPLERGEIST_REAL_JOB_ROOT to a running real upload')
+ job = Path(source)
+ if json.loads((job / 'result.json').read_text())['status'] != 'running':
+ pytest.skip('the real upload is not currently running')
+ base = [sys.executable, '-m', 'dopplergeist.cli', 'job', job.name, '--jobs', str(job.parent)]
+ once = subprocess.run(base, check=True, capture_output=True, text=True)
+ assert json.loads(once.stdout)['job_id'] == job.name
+ watcher = subprocess.Popen(base + ['--watch', '--interval', '1'], stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, text=True)
+ try:
+ time.sleep(2.5)
+ assert watcher.poll() is None
+ watcher.send_signal(signal.SIGINT)
+ stdout, stderr = watcher.communicate(timeout=15)
+ finally:
+ if watcher.poll() is None:
+ watcher.kill()
+ watcher.wait()
+ assert watcher.returncode == 130 and stdout == ''
+ assert 'local checkpoint pieces' in stderr and 'pieces/min since last check' in stderr
+ assert 'Stopped watching; the job continues.' in stderr
+ assert json.loads((job / 'result.json').read_text())['status'] == 'running'