gpu-usage-audit 1.1.0__tar.gz → 1.2.0__tar.gz

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpu-usage-audit
-Version: 1.1.0
+Version: 1.2.0
 Summary: Single-host daemon that surfaces 'idle-held' NVIDIA GPU memory — the embarrassing category conventional dashboards miss.
 Project-URL: Homepage, https://github.com/AI-Ocean/gpu-usage-audit
 Project-URL: Issues, https://github.com/AI-Ocean/gpu-usage-audit/issues

gpu_usage_audit-1.2.0/docs/work-specs/0002-daemon-cloud-mode.ko.md

@@ -0,0 +1,43 @@
+# 0002 Daemon Cloud Mode (continuous push)
+
+상태: draft
+관련: 0001 (enroll + sync-once)
+목표: `gua daemon --cloud` — 데몬이 매 틱 local DB 에 기록한 뒤 latest snapshot 을 GUA Board 로 push 한다. 일회성 `sync-once` 를 연속 운영으로 확장(없으면 보드가 stale).
+
+## 배경
+
+0001 에서 enroll + sync-once(1회 수집→local write→push)가 생겼다. 보드가 살아있으려면 호스트가 주기적으로 latest 를 올려야 한다. 기존 `gua daemon` 루프(anti-drift, 시그널 종료, local-write-first)를 재사용해 cloud push 를 얹는다.
+
+## 범위
+
+포함:
+
+- `daemon` 에 `--cloud` + `--config` 플래그(두 CLI 파서 모두: `gua`, `gpu-usage-audit`).
+- `daemon.run_daemon`/`_tick` 에 optional `on_tick(snap, ts)` 후크. **daemon 모듈은 cloud 를 import 하지 않는다** — CLI 가 콜백 주입(결합도 분리). 후크는 local write *이후* 호출, 실패해도 로그만 남기고 다음 틱 계속(local-write-first 불변식).
+- `_cmd_daemon`: `--cloud` 면 NVML 열기 *전에* `load_cloud_config` 검증(미enroll → exit 2). push 콜백 = `build_observation_payload` + `post_observation`(0001 재사용).
+- `gua daemon --cloud`(백그라운드)면 spawn 커맨드에 `--cloud --config` 전파.
+
+제외:
+
+- pull/명령 채널, 재시도 백오프 정교화, 오프라인 큐잉(실패 틱은 다음 틱이 latest 로 덮음 — replay 안 함).
+- systemd 유닛 패키징(설치 UX 별도).
+
+## Acceptance
+
+- `gua daemon --cloud`(enrolled): 매 틱 local 기록 + latest push, 보드에 호스트/GPU 표시.
+- push 실패(네트워크/CloudError/payload ValueError)는 데몬을 멈추지 않고 local 기록도 보존.
+- `--cloud` + 미enroll → exit 2(NVML 열기 전).
+- `--cloud` 없으면 기존 동작 그대로(push 없음).
+- 백그라운드 `gua daemon --cloud` 가 자식 프로세스로 옵션 전파.
+
+## Verification
+
+- `tests/test_daemon.py`: `on_tick` 매 틱 local write 이후 호출 + raise 해도 데몬 계속·local 보존.
+- `tests/test_cloud_cli.py`: `--cloud` 미enroll → exit 2(`run \`gua enroll\``); 백그라운드 spawn 커맨드에 `--cloud/--config` 포함.
+- 전체 `pytest` 163 passed, `ruff` clean.
+
+## Implementation Notes
+
+- on_tick 후크 타입 `OnTick = Callable[[Snapshot, datetime], None]` (daemon.py).
+- 실패 처리: `_tick` 이 on_tick 을 try/except 로 감싸 `logger.exception` 후 계속(틱 자체는 성공으로 간주).
+- "push latest only, no replay" — 실패 틱을 재전송하지 않고 다음 틱 latest 가 보드를 갱신.

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gpu-usage-audit"
-version = "1.1.0"
+version = "1.2.0"
 description = "Single-host daemon that surfaces 'idle-held' NVIDIA GPU memory — the embarrassing category conventional dashboards miss."
 readme = "README.md"
 license = { file = "LICENSE" }

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/src/gpu_usage_audit/__main__.py

@@ -43,7 +43,7 @@ from .daemon import install_signal_handlers, resolve_proc_identities, run_daemon
 from .db import open_db, write_snapshot
 from .doctor import build_doctor_report, doctor_report_to_dict, render_doctor
 from .identity import system_process_name_lookup, system_user_lookup
-from .model import HostMeta
+from .model import HostMeta, Snapshot
 from .nvml import NVMLNotAvailableError, NVMLTier
 from .paths import (
     DEFAULT_CLOUD_CONFIG_PATH,
@@ -121,6 +121,7 @@ def build_parser() -> argparse.ArgumentParser:
         default=timedelta(seconds=30),
         help="Tick interval (e.g. 30s, 1m, 200ms) [default: 30s]",
     )
+    _add_cloud_args(p_daemon)
     p_daemon.set_defaults(func=_cmd_daemon)
 
     p_report = sub.add_parser(
@@ -198,6 +199,19 @@ def _add_daemon_args(parser: argparse.ArgumentParser) -> None:
     )
 
 
+def _add_cloud_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--cloud",
+        action="store_true",
+        help="After each tick, push the latest snapshot to GUA Board (requires `gua enroll`)",
+    )
+    parser.add_argument(
+        "--config",
+        default=str(DEFAULT_CLOUD_CONFIG_PATH),
+        help=f"Cloud config path (used with --cloud) [default: {DEFAULT_CLOUD_CONFIG_PATH}]",
+    )
+
+
 def _add_report_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--db",
@@ -294,6 +308,7 @@ def build_gua_parser() -> argparse.ArgumentParser:
     )
     _add_daemon_args(p_daemon)
     _add_runtime_file_args(p_daemon)
+    _add_cloud_args(p_daemon)
     p_daemon.add_argument(
         "--foreground",
         action="store_true",
@@ -307,6 +322,7 @@ def build_gua_parser() -> argparse.ArgumentParser:
     )
     _add_daemon_args(p_start)
     _add_runtime_file_args(p_start)
+    _add_cloud_args(p_start)
     p_start.set_defaults(func=_cmd_gua_start)
 
     p_status = sub.add_parser(
@@ -598,6 +614,9 @@ def _cmd_gua_start(args: argparse.Namespace) -> int:
         "--interval",
         _duration_cli_value(args.interval),
     ]
+    # cloud sync 옵션을 백그라운드 프로세스로 전파한다.
+    if getattr(args, "cloud", False):
+        command += ["--cloud", "--config", str(args.config)]
     env = os.environ.copy()
     env[DISPLAY_COMMAND_ENV] = "gua daemon --foreground"
     with log_path.open("ab") as log:
@@ -712,6 +731,16 @@ def _cmd_daemon(args: argparse.Namespace) -> int:
         return 2
     if is_default_db_path(db_path):
         db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # cloud sync 가 켜졌으면 enroll 설정을 *먼저* 검증한다(미enroll 이면 NVML 열기 전에 중단).
+    cloud_config = None
+    if getattr(args, "cloud", False):
+        try:
+            cloud_config = load_cloud_config(args.config)
+        except CloudConfigError as exc:
+            print(f"{display_command}: {exc}", file=sys.stderr)
+            return 2
+
     tier = NVMLTier()
     try:
         try:
@@ -721,12 +750,37 @@ def _cmd_daemon(args: argparse.Namespace) -> int:
             return 1
         conn = open_db(db_path)
         try:
+            hostname = socket.gethostname() or "unknown"
             host = HostMeta(
-                hostname=socket.gethostname() or "unknown",
+                hostname=hostname,
                 env_kind=LOCAL_ENV_KIND,
                 driver_version=driver,
                 first_seen=datetime.now(UTC),
             )
+
+            # cloud on_tick 후크: local write 이후 latest snapshot 을 board 로 push.
+            # 빌드/푸시 실패는 daemon._tick 이 잡아 로그만 남기고 다음 틱을 계속한다.
+            on_tick = None
+            if cloud_config is not None:
+
+                def push_snapshot(snap: Snapshot, ts: datetime) -> None:
+                    payload = build_observation_payload(
+                        snapshot=snap,
+                        hostname=hostname,
+                        driver_version=driver,
+                        agent_version=__version__,
+                        observed_at=ts,
+                        host_id=cloud_config.host_id,
+                        display_name=cloud_config.display_name,
+                    )
+                    post_observation(cloud_config, payload)
+
+                on_tick = push_snapshot
+                print(
+                    f"{display_command}: cloud sync enabled -> "
+                    f"{cloud_config.display_name} ({cloud_config.server_url})"
+                )
+
             stop = threading.Event()
             install_signal_handlers(stop)
             run_daemon(
@@ -737,6 +791,7 @@ def _cmd_daemon(args: argparse.Namespace) -> int:
                 lookup=system_user_lookup,
                 name_lookup=system_process_name_lookup,
                 stop=stop,
+                on_tick=on_tick,
             )
             total = conn.execute("SELECT COUNT(*) FROM gpu_sample").fetchone()[0]
             print(f"\n{args.db}: {total} total gpu_sample rows")

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/src/gpu_usage_audit/daemon.py

@@ -22,13 +22,16 @@ from datetime import UTC, datetime, timedelta
 from typing import TextIO
 
 from .db import start_daemon_run, write_snapshot
-from .model import HostMeta, ProcSample
+from .model import HostMeta, ProcSample, Snapshot
 from .summarize import summarize
 from .tier import Tier
 
 logger = logging.getLogger(__name__)
 
 UserLookup = Callable[[int], str | None]
+# 틱 후크: local write *이후* 의 부가 작업(예: cloud push). 데몬 모듈은 cloud 를
+# 모르고, CLI 가 콜백을 주입한다 — 결합도 분리.
+OnTick = Callable[[Snapshot, datetime], None]
 
 
 def _noop_lookup(_pid: int) -> str | None:
@@ -78,8 +81,13 @@ def _tick(
     n: int,
     out: TextIO,
     run_id: int,
+    on_tick: OnTick | None = None,
 ) -> None:
-    """한 틱: tier.collect → loginuid/process_name 해석 → 적재 → 한 줄 로그."""
+    """한 틱: tier.collect → loginuid/process_name 해석 → 적재 → 한 줄 로그.
+
+    on_tick 이 있으면 local write *이후* 호출한다(예: cloud push). 후크 실패는
+    이미 커밋된 local write 와 다음 틱을 막지 않는다 — 로그만 남기고 계속.
+    """
     snap = tier.collect(ts)
     # ProcSample 이 mutable slots — *제자리* 갱신.
     resolve_proc_identities(snap.procs, lookup, name_lookup)
@@ -89,6 +97,12 @@ def _tick(
     ts_short = ts.strftime("%H:%M:%S.") + f"{ts.microsecond // 1000:03d}"
     print(f"Tick {n}  ts={ts_short}  {classes}", file=out)
 
+    if on_tick is not None:
+        try:
+            on_tick(snap, ts)
+        except Exception:
+            logger.exception("tick %d on_tick hook failed; continuing", n)
+
 
 def run_daemon(
     *,
@@ -101,6 +115,7 @@ def run_daemon(
     stop: threading.Event | None = None,
     max_ticks: int | None = None,
     out: TextIO | None = None,
+    on_tick: OnTick | None = None,
 ) -> int:
     """ctx 캔슬까지 interval 간격으로 한 틱씩 반복. 적재한 틱 총 수 반환.
 
@@ -135,7 +150,7 @@ def run_daemon(
             run_id = start_daemon_run(db, datetime.now(UTC), interval)
 
         try:
-            _tick(tier, db, host, lookup, name_lookup, datetime.now(UTC), n, out, run_id)
+            _tick(tier, db, host, lookup, name_lookup, datetime.now(UTC), n, out, run_id, on_tick)
         except Exception:
             logger.exception("tick %d failed; continuing", n)
         n += 1

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/tests/test_cloud_cli.py

@@ -273,3 +273,66 @@ def test_sync_once_without_enrollment_exits_2(
     )
     assert rc == 2
     assert "run `gua enroll`" in capsys.readouterr().err
+
+
+# ── daemon --cloud ───────────────────────────────────────────────
+
+
+def test_daemon_cloud_without_enrollment_exits_2(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    # --cloud 인데 enroll 안 됨 → NVML 열기 *전에* 설정 검증 실패로 종료.
+    rc = gua_main(
+        [
+            "daemon",
+            "--foreground",
+            "--cloud",
+            "--db",
+            str(tmp_path / "gua.db"),
+            "--config",
+            str(tmp_path / "absent.json"),
+        ]
+    )
+    assert rc == 2
+    assert "run `gua enroll`" in capsys.readouterr().err
+
+
+def test_daemon_start_propagates_cloud_flags_to_background(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    # 백그라운드 spawn 커맨드에 --cloud/--config 가 실려야 데몬이 push 한다.
+    captured: dict[str, Any] = {}
+
+    class FakePopen:
+        def __init__(self, command: list[str], **_kwargs: Any) -> None:
+            captured["command"] = command
+            self.pid = 4242
+
+        def poll(self) -> int | None:
+            return None
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.subprocess.Popen", FakePopen)
+    monkeypatch.setattr("gpu_usage_audit.__main__.time.sleep", lambda *_a, **_k: None)
+
+    config_path = tmp_path / "cloud.json"
+    rc = gua_main(
+        [
+            "daemon",
+            "--cloud",
+            "--db",
+            str(tmp_path / "gua.db"),
+            "--config",
+            str(config_path),
+            "--pid-file",
+            str(tmp_path / "daemon.pid"),
+            "--log-file",
+            str(tmp_path / "daemon.log"),
+        ]
+    )
+    assert rc == 0
+    command = captured["command"]
+    assert "--cloud" in command
+    assert "--config" in command
+    assert str(config_path) in command

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/tests/test_daemon.py

@@ -13,7 +13,7 @@ import pytest
 
 from gpu_usage_audit.daemon import run_daemon
 from gpu_usage_audit.db import open_db
-from gpu_usage_audit.model import HostMeta
+from gpu_usage_audit.model import HostMeta, Snapshot
 from gpu_usage_audit.tier import FakeTier
 
 INTERVAL = timedelta(milliseconds=20)
@@ -110,3 +110,51 @@ def test_run_daemon_lookup_resolves_loginuid(db: sqlite3.Connection, host: HostM
     assert 1234 not in lookup_calls
     assert 5678 not in lookup_calls
     assert 9999 in lookup_calls
+
+
+def test_run_daemon_invokes_on_tick_after_local_write(
+    db: sqlite3.Connection, host: HostMeta
+) -> None:
+    # on_tick 은 매 틱 local write *이후* 호출된다(cloud push 가 얹히는 자리).
+    calls: list[int] = []
+
+    def on_tick(snap: Snapshot, _ts: datetime) -> None:
+        # 콜백 시점엔 이미 이번 틱이 DB 에 기록돼 있어야 한다.
+        calls.append(db.execute("SELECT COUNT(*) FROM gpu_sample").fetchone()[0])
+        assert len(snap.gpus) == 3  # FakeTier 의 스냅샷이 그대로 전달된다.
+
+    n = run_daemon(
+        tier=FakeTier(),
+        db=db,
+        host=host,
+        interval=INTERVAL,
+        max_ticks=3,
+        out=io.StringIO(),
+        on_tick=on_tick,
+    )
+    assert n == 3
+    # 매 틱 호출되고, 호출 시점의 누적 행 수는 3, 6, 9 (틱당 3 GPU).
+    assert calls == [3, 6, 9]
+
+
+def test_run_daemon_continues_when_on_tick_raises(db: sqlite3.Connection, host: HostMeta) -> None:
+    # on_tick(예: cloud push) 실패는 local write 와 다음 틱을 막지 않는다.
+    attempts: list[int] = []
+
+    def boom(_snap: Snapshot, _ts: datetime) -> None:
+        attempts.append(1)
+        raise RuntimeError("cloud push failed")
+
+    n = run_daemon(
+        tier=FakeTier(),
+        db=db,
+        host=host,
+        interval=INTERVAL,
+        max_ticks=3,
+        out=io.StringIO(),
+        on_tick=boom,
+    )
+    assert n == 3
+    assert len(attempts) == 3  # 매 틱 호출(예외에도 멈추지 않음).
+    # local write 는 전부 보존: 3 틱 * 3 GPU = 9 행.
+    assert db.execute("SELECT COUNT(*) FROM gpu_sample").fetchone()[0] == 9

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.2.0}/uv.lock

@@ -139,7 +139,7 @@ wheels = [
 
 [[package]]
 name = "gpu-usage-audit"
-version = "1.1.0"
+version = "1.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "nvidia-ml-py" },