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

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.3.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.3.0 - 2026-06-18
+
+- Cloud sync now emits a real `collectionStatus` instead of always reporting
+  `ok`. When core GPU metrics are collected but one or more cards' per-process
+  list is unavailable (permissions or transient NVML errors), `gua sync-once`
+  and `gua daemon --cloud` push `partial` with a `process_list_unavailable`
+  error while still sending the GPU data. When NVML initialization fails
+  entirely, `gua sync-once` now pushes an `error` heartbeat
+  (`nvml_init_failed`, empty GPU inventory) so a host that lost its driver
+  still surfaces a non-ok freshness signal on the board, then exits non-zero.
+
 ## 1.1.0 - 2026-06-17
 
 - Added optional GUA Board cloud sync. `gua enroll` claims a one-time

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpu-usage-audit
-Version: 1.1.0
+Version: 1.3.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.3.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.3.0/docs/work-specs/0003-collection-status-emit.ko.md

@@ -0,0 +1,50 @@
+# 0003 Collection Status Emit (partial / error)
+
+상태: implemented
+관련: 0001 (enroll + sync-once, payload builder), 0002 (daemon cloud mode)
+목표: agent 가 수집이 실제로 저하/실패했을 때 `collectionStatus` 를 `partial`/`error` 로 emit 한다. 지금까지 두 push call site 는 항상 `ok` 만 보냈다. board 측은 partial/error 를 이미 검증·저장하므로 board 변경은 없다 (agent 전용).
+
+## 배경
+
+0001 의 payload builder(`build_observation_payload`)는 `ok`/`partial`/`error` 셋 다 지원·검증한다 (`partial`/`error` 는 errors ≥1, `ok` 는 errors 비어야 함). 하지만 MVP 는 후속으로 미뤄 두 call site(`sync-once`, daemon `push_snapshot`)가 status/errors 를 생략해 항상 `ok` 였다 (0001 Implementation Notes "collectionStatus 매핑").
+
+실제 운영에서 수집은 두 가지로 저하된다:
+- 일부 카드의 process list 가 권한/일시오류로 안 읽힌다 — core GPU metric 은 정상. board 가 idle-held 신호를 *과소평가* 할 수 있으니 `partial` 로 알려야 한다.
+- NVML init 자체가 실패한다(드라이버 손실 등) — GPU inventory 가 아예 없다. crash 로 끝내는 대신 `error` heartbeat 를 보내 board 가 non-ok freshness 로 표시하게 한다.
+
+## 범위
+
+포함:
+
+- `NVMLTier.collect()` 가 그 틱에 process list 를 못 읽은 카드를 *틱마다 리셋* 되는 집합으로 추적하고 `last_process_list_unavailable: bool` 로 노출. 기존 누적 warning 집합(반복 로그 억제)과 분리.
+- `cloud.snapshot.derive_collection_status(snapshot, *, process_list_unavailable)` — 수집 결과 → `(status, errors)`. GPU 가 있고 process list 가 비었으면 `partial` + `["process_list_unavailable"]`, 그 외 `ok`. contract 와 같은 곳에 둬 두 call site 가 같은 규칙 공유.
+- 안정적 short error code 상수: `process_list_unavailable`, `nvml_init_failed`.
+- `sync-once`: collect 후 partial 신호를 builder 로 thread. NVML init 실패 시 `error` heartbeat(빈 inventory, `nvml_init_failed`) push 후 non-zero exit. 데이터가 없으므로 local DB 는 쓰지 않는다.
+- daemon `push_snapshot`: 매 틱 `tier.last_process_list_unavailable` 로 partial 도출해 thread (on_tick 은 같은 스레드에서 collect 직후 동기 호출이라 일치).
+
+제외:
+
+- daemon 의 `error` heartbeat. daemon 은 NVML 열기 *전에* probe 실패면 즉시 종료하는 구조라(0002 `_cmd_daemon`), error heartbeat 를 끼우려면 cloud config 검증 순서·종료 경로를 재배치해야 한다. 위험 대비 가치가 낮아 보류 — sync-once 의 error heartbeat 로 단발 진단은 가능하다.
+- 새 error code 분류(예: GPU별 temperature/power 실패) — builder 는 음수 sentinel 을 0 으로 눌러 이미 흡수하므로 partial 로 격상하지 않는다.
+- 신규 의존성/version bump/release tag (별도 수동 단계).
+
+## Acceptance
+
+- 모든 카드 정상 수집 → `ok`, errors 빈 배열 (기존과 동일).
+- 한 카드라도 process list 가 NVMLError 로 비고 core GPU metric 은 수집됨 → `partial` + `["process_list_unavailable"]`, GPU 데이터는 그대로 push.
+- partial 은 *틱 단위* — 다음 틱에 process list 가 복구되면 `ok` 로 돌아온다.
+- NVML init 실패(`sync-once`) → `error` + `["nvml_init_failed"]` heartbeat push, GPU 빈 배열, local write 없음, non-zero exit. heartbeat push 도 실패하면 두 에러를 모두 보고.
+- 두 call site 가 도출한 status/errors 를 builder 에 넘기며, builder 검증을 그대로 통과(partial/error errors ≥1).
+
+## Verification
+
+- `tests/test_nvml.py`: `last_process_list_unavailable` 가 process list 실패 틱에 True, 복구 틱에 False 로 리셋(틱 단위), core GPU metric 유지.
+- `tests/test_cloud_snapshot.py`: `derive_collection_status` ok/partial 도출, GPU 0개면 partial flag 무시(ok), partial 도출값이 builder 검증 통과.
+- `tests/test_cloud_cli.py`: `sync-once` 가 process list 불가 시 `partial` payload + GPU 보존 + local write; NVML init 실패 시 `error` heartbeat(빈 inventory, local write 없음, exit 1); heartbeat push 실패 시 두 에러 모두 보고.
+- 전체 `uv run pytest`: 170 passed (기존 163 + 신규 7). `ruff check` clean, `mypy` clean.
+
+## Implementation Notes
+
+- partial 판정은 `derive_collection_status` 한곳 — `sync-once`(`NVMLTier.last_process_list_unavailable`) 와 daemon(같은 tier 인스턴스 closure) 이 공유.
+- error heartbeat 는 `Snapshot()`(빈) 으로 builder 호출 — GPU 0개라 검증 통과하고, errors 비우지 않아 `error` contract 충족. driver_version 은 probe 실패라 `"unknown"`.
+- daemon error heartbeat 는 보류 — 위 "제외" 참조. partial 경로는 daemon·sync-once 양쪽 모두 적용.

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

@@ -1,6 +1,6 @@
 [project]
 name = "gpu-usage-audit"
-version = "1.1.0"
+version = "1.3.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.3.0}/src/gpu_usage_audit/__main__.py

@@ -34,16 +34,21 @@ from pathlib import Path
 from . import __version__
 from .cloud.client import CloudError, claim_enrollment, post_observation
 from .cloud.config import (
+    CloudConfig,
     CloudConfigError,
     load_cloud_config,
     save_cloud_config,
 )
-from .cloud.snapshot import build_observation_payload
+from .cloud.snapshot import (
+    ERROR_NVML_INIT_FAILED,
+    build_observation_payload,
+    derive_collection_status,
+)
 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 +126,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 +204,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 +313,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 +327,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(
@@ -483,6 +504,8 @@ def _cmd_gua_sync_once(args: argparse.Namespace) -> int:
         return 2
 
     observed_at = datetime.now(UTC)
+    hostname = socket.gethostname() or "unknown"
+    process_list_unavailable = False
     if args.fake:
         tier = FakeTier()
         driver = tier.probe()
@@ -493,14 +516,19 @@ def _cmd_gua_sync_once(args: argparse.Namespace) -> int:
             try:
                 driver = nvml_tier.probe()
             except NVMLNotAvailableError as exc:
-                print(f"gua sync-once: {exc}", file=sys.stderr)
-                return 1
+                # 드라이버를 잃은 host 도 board 가 non-ok freshness 로 보여줄 수
+                # 있게 error heartbeat 를 push 한다 (GPU inventory 없음, local
+                # write 도 없음 — 기록할 데이터가 없다).
+                return _push_error_heartbeat(config, hostname, observed_at, exc)
             snap = nvml_tier.collect(observed_at)
+            process_list_unavailable = nvml_tier.last_process_list_unavailable
             resolve_proc_identities(snap.procs, system_user_lookup, system_process_name_lookup)
         finally:
             nvml_tier.close()
 
-    hostname = socket.gethostname() or "unknown"
+    collection_status, errors = derive_collection_status(
+        snap, process_list_unavailable=process_list_unavailable
+    )
     host = HostMeta(
         hostname=hostname,
         env_kind=LOCAL_ENV_KIND,
@@ -528,6 +556,8 @@ def _cmd_gua_sync_once(args: argparse.Namespace) -> int:
             observed_at=observed_at,
             host_id=config.host_id,
             display_name=config.display_name,
+            collection_status=collection_status,
+            errors=errors,
         )
     except ValueError as exc:
         print(
@@ -546,14 +576,53 @@ def _cmd_gua_sync_once(args: argparse.Namespace) -> int:
         )
         return 1
 
+    status_note = "" if collection_status == "ok" else f" [{collection_status}: {','.join(errors)}]"
     print(
         f"gua sync-once: pushed {len(payload['gpus'])} GPUs to "
-        f"{config.display_name} ({config.server_url})"
+        f"{config.display_name} ({config.server_url}){status_note}"
     )
     print(f"  local snapshot saved to {db_path}")
     return 0
 
 
+def _push_error_heartbeat(
+    config: CloudConfig,
+    hostname: str,
+    observed_at: datetime,
+    exc: NVMLNotAvailableError,
+) -> int:
+    """NVML init 실패 시 board 에 `error` heartbeat 만 push 한다 (데이터 없음).
+
+    GPU inventory 가 비어 있어 local DB 에 쓸 게 없으므로 push 만 한다. push
+    실패는 비치명적 — 에러를 보고하고 non-zero exit 로 신호한다.
+    """
+    payload = build_observation_payload(
+        snapshot=Snapshot(),
+        hostname=hostname,
+        driver_version="unknown",
+        agent_version=__version__,
+        observed_at=observed_at,
+        host_id=config.host_id,
+        display_name=config.display_name,
+        collection_status="error",
+        errors=[ERROR_NVML_INIT_FAILED],
+    )
+    try:
+        post_observation(config, payload)
+    except CloudError as push_exc:
+        print(
+            f"gua sync-once: {exc}; error heartbeat push also failed: {push_exc}",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"gua sync-once: {exc}; pushed error heartbeat to "
+        f"{config.display_name} ({config.server_url})",
+        file=sys.stderr,
+    )
+    return 1
+
+
 def _cmd_gua_daemon(args: argparse.Namespace) -> int:
     if args.foreground:
         args.display_command = "gua daemon --foreground"
@@ -598,6 +667,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 +784,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 +803,44 @@ 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:
+                    # on_tick 은 같은 데몬 스레드에서 tier.collect() 직후 동기로
+                    # 호출되므로, tier 의 last-collect 상태가 이 snap 과 일치한다.
+                    collection_status, errors = derive_collection_status(
+                        snap, process_list_unavailable=tier.last_process_list_unavailable
+                    )
+                    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,
+                        collection_status=collection_status,
+                        errors=errors,
+                    )
+                    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 +851,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.3.0}/src/gpu_usage_audit/cloud/snapshot.py

@@ -21,6 +21,35 @@ from . import SCHEMA_VERSION
 CollectionStatus = str  # "ok" | "partial" | "error" — 서버가 enum 검증.
 _UNKNOWN = "unknown"
 
+# 안정적인 short error code — 서버/board 가 freshness 신호로 표시한다.
+# 새 code 는 여기 한곳에 모아 builder/CLI/daemon 이 같은 문자열을 공유한다.
+ERROR_PROCESS_LIST_UNAVAILABLE = "process_list_unavailable"
+ERROR_NVML_INIT_FAILED = "nvml_init_failed"
+
+
+def derive_collection_status(
+    snapshot: Snapshot,
+    *,
+    process_list_unavailable: bool = False,
+) -> tuple[CollectionStatus, list[str]]:
+    """수집 결과에서 `(collectionStatus, errors)` 를 도출한다.
+
+    contract 와 같은 곳에 둬서 CLI(`sync-once`)/daemon 두 call site 가 같은
+    규칙을 공유한다. builder 의 검증(`partial`/`error` 는 errors ≥1, `ok` 는
+    errors 비어야 함)과 일관되게 만든다.
+
+    - GPU 가 하나라도 수집되고 일부 카드의 process list 만 권한/일시오류로
+      비었으면 → `partial` + `process_list_unavailable`. core GPU metric 은
+      그대로 push 한다.
+    - 그 외(모든 카드 정상, 또는 애초에 GPU 0개여도 push 흐름 자체는 정상) → `ok`.
+
+    NVML init 자체가 실패해 GPU inventory 가 아예 없는 `error` heartbeat 는
+    수집을 못 한 상황이라 이 함수가 아니라 call site 에서 직접 구성한다.
+    """
+    if snapshot.gpus and process_list_unavailable:
+        return "partial", [ERROR_PROCESS_LIST_UNAVAILABLE]
+    return "ok", []
+
 
 def build_observation_payload(
     *,

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.3.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.3.0}/src/gpu_usage_audit/nvml.py

@@ -63,6 +63,10 @@ class NVMLTier:
         self._nvml: Any | None = None  # pynvml ModuleType
         self._initialized = False
         self._process_list_warning_uuids: set[str] = set()
+        # 가장 최근 collect() 에서 process list 를 읽지 못한 GPU UUID 들.
+        # warning 집합(반복 로그 억제용, 누적)과 달리 *틱마다 리셋* 되어
+        # 그 틱의 collectionStatus(partial) 판정에 쓰인다.
+        self._last_process_list_unavailable_uuids: set[str] = set()
 
     def __enter__(self) -> NVMLTier:
         return self
@@ -90,6 +94,7 @@ class NVMLTier:
 
         gpus: list[GPUSample] = []
         procs: list[ProcSample] = []
+        self._last_process_list_unavailable_uuids = set()  # 이 틱 기준으로 리셋.
         count = nvml.nvmlDeviceGetCount()
         for i in range(count):
             h = nvml.nvmlDeviceGetHandleByIndex(i)
@@ -114,6 +119,8 @@ class NVMLTier:
             try:
                 running = nvml.nvmlDeviceGetComputeRunningProcesses(h)
             except nvml.NVMLError as e:
+                # 이 틱의 partial 판정용 — collectionStatus 에 반영된다.
+                self._last_process_list_unavailable_uuids.add(uuid)
                 if uuid not in self._process_list_warning_uuids:
                     logger.warning(
                         "NVML process list unavailable for %s; idle-held classification "
@@ -141,6 +148,15 @@ class NVMLTier:
                 )
         return Snapshot(gpus=gpus, procs=procs)
 
+    @property
+    def last_process_list_unavailable(self) -> bool:
+        """가장 최근 collect() 에서 한 카드라도 process list 를 못 읽었는지.
+
+        True 면 core GPU metric 은 수집됐지만 일부 카드의 process 목록이
+        권한/일시오류로 비었다는 뜻 — cloud push 는 `partial` 로 보낸다.
+        """
+        return bool(self._last_process_list_unavailable_uuids)
+
     @staticmethod
     def _read_temperature(nvml: Any, handle: Any) -> int | None:
         """GPU 온도(°C). 일부 카드/드라이버는 미지원 — 실패 시 None (optional metric)."""

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

@@ -12,6 +12,7 @@ from gpu_usage_audit.__main__ import gua_main
 from gpu_usage_audit.cloud.client import CloudError
 from gpu_usage_audit.cloud.config import CloudConfig, load_cloud_config, save_cloud_config
 from gpu_usage_audit.model import GPUSample, Snapshot
+from gpu_usage_audit.nvml import NVMLNotAvailableError
 
 
 def _config() -> CloudConfig:
@@ -241,6 +242,138 @@ def test_sync_once_unbuildable_payload_keeps_local_write_without_pushing(
         conn.close()
 
 
+def test_sync_once_emits_partial_when_process_list_unavailable(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    config_path = tmp_path / "cloud.json"
+    save_cloud_config(_config(), config_path)
+    db_path = tmp_path / "gua.db"
+
+    class _PartialTier:
+        # core GPU metric 은 수집했지만 한 카드의 process list 가 권한 부족.
+        def probe(self) -> str:
+            return "560.35.05"
+
+        def collect(self, _ts: object) -> Snapshot:
+            return Snapshot(
+                gpus=[
+                    GPUSample(uuid="GPU-0", util_pct=10, index=0, name="GPU", memory_total_mb=1000)
+                ]
+            )
+
+        @property
+        def last_process_list_unavailable(self) -> bool:
+            return True
+
+        def close(self) -> None:
+            pass
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.NVMLTier", _PartialTier)
+    pushed: dict[str, Any] = {}
+
+    def fake_post(config: CloudConfig, payload: dict[str, Any], **_kw: Any) -> dict[str, Any]:
+        pushed["payload"] = payload
+        return {}
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.post_observation", fake_post)
+
+    # --fake 없이 실 NVML 경로를 탄다 (위에서 NVMLTier 를 monkeypatch).
+    rc = gua_main(["sync-once", "--config", str(config_path), "--db", str(db_path)])
+
+    assert rc == 0
+    payload = pushed["payload"]
+    assert payload["collectionStatus"] == "partial"
+    assert payload["errors"] == ["process_list_unavailable"]
+    # 핵심: GPU 데이터는 그대로 push 됐다.
+    assert len(payload["gpus"]) == 1
+    out = capsys.readouterr().out
+    assert "partial: process_list_unavailable" in out
+    # local write 도 보존.
+    conn = sqlite3.connect(db_path)
+    try:
+        assert conn.execute("SELECT COUNT(*) FROM gpu_sample").fetchone()[0] == 1
+    finally:
+        conn.close()
+
+
+def test_sync_once_pushes_error_heartbeat_when_nvml_init_fails(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    config_path = tmp_path / "cloud.json"
+    save_cloud_config(_config(), config_path)
+    db_path = tmp_path / "gua.db"
+
+    class _DeadTier:
+        # 드라이버를 잃은 host — NVML init 자체가 실패.
+        def probe(self) -> str:
+            raise NVMLNotAvailableError("the NVIDIA driver is not loaded")
+
+        def collect(self, _ts: object) -> Snapshot:  # pragma: no cover - 도달 안 함
+            raise AssertionError("collect must not run after probe failure")
+
+        def close(self) -> None:
+            pass
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.NVMLTier", _DeadTier)
+    pushed: dict[str, Any] = {}
+
+    def fake_post(config: CloudConfig, payload: dict[str, Any], **_kw: Any) -> dict[str, Any]:
+        pushed["payload"] = payload
+        return {}
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.post_observation", fake_post)
+
+    rc = gua_main(["sync-once", "--config", str(config_path), "--db", str(db_path)])
+
+    # error heartbeat 는 보냈지만 수집 실패라 non-zero exit.
+    assert rc == 1
+    payload = pushed["payload"]
+    assert payload["collectionStatus"] == "error"
+    assert payload["errors"] == ["nvml_init_failed"]
+    assert payload["gpus"] == []
+    err = capsys.readouterr().err
+    assert "pushed error heartbeat" in err
+    assert "driver is not loaded" in err
+    # 데이터가 없으므로 local DB 는 쓰지 않는다.
+    assert not db_path.exists()
+
+
+def test_sync_once_error_heartbeat_push_failure_reports_both(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    config_path = tmp_path / "cloud.json"
+    save_cloud_config(_config(), config_path)
+
+    class _DeadTier:
+        def probe(self) -> str:
+            raise NVMLNotAvailableError("the NVIDIA driver is not loaded")
+
+        def collect(self, _ts: object) -> Snapshot:  # pragma: no cover
+            raise AssertionError
+
+        def close(self) -> None:
+            pass
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.NVMLTier", _DeadTier)
+
+    def fake_post(*_args: Any, **_kw: Any) -> dict[str, Any]:
+        raise CloudError("could not reach GUA Board server: connection refused")
+
+    monkeypatch.setattr("gpu_usage_audit.__main__.post_observation", fake_post)
+
+    rc = gua_main(["sync-once", "--config", str(config_path), "--db", str(tmp_path / "gua.db")])
+
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "error heartbeat push also failed" in err
+
+
 def test_sync_once_creates_missing_db_parent_dir(
     monkeypatch: pytest.MonkeyPatch,
     tmp_path: Path,
@@ -273,3 +406,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.3.0}/tests/test_cloud_snapshot.py

@@ -7,10 +7,15 @@ from typing import Any
 
 import pytest
 
-from gpu_usage_audit.cloud.snapshot import build_observation_payload
+from gpu_usage_audit.cloud.snapshot import (
+    build_observation_payload,
+    derive_collection_status,
+)
 from gpu_usage_audit.model import GPUSample, ProcSample, Snapshot
 from gpu_usage_audit.tier import FakeTier
 
+_GPU = GPUSample(uuid="GPU-0", util_pct=0, index=0, name="GPU", memory_total_mb=1000)
+
 OBSERVED_AT = datetime(2026, 6, 17, 4, 0, 0, tzinfo=UTC)
 
 
@@ -142,6 +147,31 @@ def test_collection_status_error_requires_errors() -> None:
         _build(Snapshot(), collection_status="ok", errors=["boom"])
 
 
+# ── derive_collection_status ─────────────────────────────────────
+
+
+def test_derive_status_ok_when_no_degradation() -> None:
+    snap = Snapshot(gpus=[_GPU])
+    assert derive_collection_status(snap) == ("ok", [])
+    assert derive_collection_status(snap, process_list_unavailable=False) == ("ok", [])
+
+
+def test_derive_status_partial_when_process_list_unavailable() -> None:
+    snap = Snapshot(gpus=[_GPU])
+    status, errors = derive_collection_status(snap, process_list_unavailable=True)
+    assert status == "partial"
+    assert errors == ["process_list_unavailable"]
+    # builder 검증을 그대로 통과해야 한다 (partial 은 errors ≥1).
+    payload = _build(snap, collection_status=status, errors=errors)
+    assert payload["collectionStatus"] == "partial"
+    assert payload["errors"] == ["process_list_unavailable"]
+
+
+def test_derive_status_partial_flag_ignored_when_no_gpus() -> None:
+    # GPU 가 0개면 partial 로 판정할 카드가 없다 — ok.
+    assert derive_collection_status(Snapshot(), process_list_unavailable=True) == ("ok", [])
+
+
 def test_fake_tier_snapshot_builds_valid_payload() -> None:
     # FakeTier 출력이 그대로 contract 모양으로 변환되는지 (sync-once --fake 기반).
     snap = FakeTier().collect(OBSERVED_AT)

{gpu_usage_audit-1.1.0 → gpu_usage_audit-1.3.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.3.0}/tests/test_nvml.py

@@ -235,6 +235,41 @@ def test_collect_handles_per_device_running_processes_error(
     assert snap.procs == []
 
 
+def test_last_process_list_unavailable_tracks_per_tick(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = _make_mock_pynvml(
+        driver="x",
+        gpus=[{"uuid": "GPU-x", "util": 0, "procs": [{"pid": 1, "mem": 1024 * 1024}]}],
+    )
+    monkeypatch.setitem(sys.modules, "pynvml", fake)
+
+    def _raise(_h: Any) -> Any:
+        raise fake.NVMLError("permission denied")
+
+    def _ok(_h: Any) -> Any:
+        return [SimpleNamespace(pid=1, usedGpuMemory=1024 * 1024)]
+
+    with NVMLTier() as tier:
+        tier.probe()
+        # 정상 collect → process list 가용.
+        tier.collect(TS)
+        clean = tier.last_process_list_unavailable
+
+        # process list 가 실패하는 틱 → True (core GPU metric 은 유지).
+        fake.nvmlDeviceGetComputeRunningProcesses = MagicMock(side_effect=_raise)
+        snap = tier.collect(TS)
+        degraded = tier.last_process_list_unavailable
+
+        # 다시 정상으로 돌아오면 *틱마다 리셋* 된다.
+        fake.nvmlDeviceGetComputeRunningProcesses = MagicMock(side_effect=_ok)
+        tier.collect(TS)
+        recovered = tier.last_process_list_unavailable
+
+    assert clean is False
+    assert degraded is True  # core metric 은 유지된 채 partial 신호만 켜진다.
+    assert [g.uuid for g in snap.gpus] == ["GPU-x"]
+    assert recovered is False
+
+
 def test_probe_translates_nvml_error_to_friendly(monkeypatch: pytest.MonkeyPatch) -> None:
     fake = _make_mock_pynvml(driver="x", gpus=[])
     fake.nvmlInit = MagicMock(side_effect=fake.NVMLError("localized message", value=9))

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

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