shikiru-cli 0.2.0__py3-none-any.whl

shikiru/telemetry/__init__.py

@@ -0,0 +1 @@
+"""Host and engine process resource samplers."""

shikiru/telemetry/disk.py

@@ -0,0 +1,167 @@
+"""Disk space and directory usage for the dashboard's Disk section."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from shikiru.paths import project_state_dir
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+    from datetime import datetime
+    from pathlib import Path
+
+    from shikiru.clock import Clock
+
+
+@dataclass(frozen=True, slots=True)
+class DirectoryUsage:
+    """The directories directly under a root and the bytes of every file beneath it."""
+
+    directories: int
+    size_bytes: int
+
+
+def directory_usage(root: Path) -> DirectoryUsage:
+    """Measure `root`, following no symlink; a missing `root` measures as empty.
+
+    A file removed while the tree is walked (by retention) counts for nothing.
+    """
+    if not root.is_dir():
+        return DirectoryUsage(0, 0)
+    directories = sum(1 for entry in root.iterdir() if entry.is_dir())
+    return DirectoryUsage(directories, sum(stat.st_size for stat in _file_stats(root, None)))
+
+
+def tree_size(root: Path) -> int:
+    """Return the apparent bytes of every file beneath `root`; a missing `root` is zero.
+
+    Symlinks are not followed, a hard-linked file counts once, and an unreadable subtree raises
+    `OSError` instead of being skipped.
+    """
+    if not root.is_dir():
+        return 0
+    linked: set[tuple[int, int]] = set()
+    size = 0
+    for stat in _file_stats(root, _raise):
+        if stat.st_nlink > 1:
+            identity = (stat.st_dev, stat.st_ino)
+            if identity in linked:
+                continue
+            linked.add(identity)
+        size += stat.st_size
+    return size
+
+
+def _raise(error: OSError) -> None:
+    raise error
+
+
+def _file_stats(root: Path, onerror: Callable[[OSError], None] | None) -> Iterator[os.stat_result]:
+    for parent, _, names in os.walk(root, onerror=onerror):
+        for name in names:
+            with suppress(FileNotFoundError):
+                yield os.lstat(os.path.join(parent, name))  # noqa: PTH118
+
+
+@dataclass(frozen=True)
+class DiskSnapshot:
+    """The latest disk observation; sizes and `sampled_at` survive a failed later sample."""
+
+    free_bytes: int | None = None
+    total_bytes: int | None = None
+    shikiru_bytes: int | None = None
+    sampled_at: datetime | None = None
+    error: str | None = None
+    failed: bool = False
+
+
+class DiskSampler:
+    """Measure the project filesystem and its `.shikiru` folder off the event loop.
+
+    Free space is measured every `refresh_seconds`; the folder size is walked on its own, slower
+    cadence in a single background flight so a long walk never delays the free-space reading.
+    """
+
+    def __init__(
+        self,
+        clock: Clock,
+        project_root: Path,
+        *,
+        refresh_seconds: Callable[[], float],
+        size_refresh_seconds: Callable[[], float],
+    ) -> None:
+        """Measure `project_root` at most once per cadence of `clock` time."""
+        self._clock = clock
+        self._project_root = project_root
+        self._shikiru_root = project_state_dir(project_root)
+        self._refresh_seconds = refresh_seconds
+        self._size_refresh_seconds = size_refresh_seconds
+        self._attempted_at: datetime | None = None
+        self._size_finished_at: datetime | None = None
+        self._size_task: asyncio.Task[None] | None = None
+        self._free_bytes: int | None = None
+        self._total_bytes: int | None = None
+        self._sampled_at: datetime | None = None
+        self._shikiru_bytes: int | None = None
+        self._free_error: str | None = None
+        self._size_error: str | None = None
+        self._lock = asyncio.Lock()
+
+    async def sample_if_due(self) -> DiskSnapshot:
+        """Return the cached observation, measuring again once a cadence has passed."""
+        self._start_size_walk_if_due()
+        async with self._lock:
+            if self._is_due(self._attempted_at, self._refresh_seconds):
+                await self._sample_free_space()
+            return self._snapshot()
+
+    def _is_due(self, since: datetime | None, interval: Callable[[], float]) -> bool:
+        return since is None or (self._clock.now() - since).total_seconds() >= interval()
+
+    def _start_size_walk_if_due(self) -> None:
+        if self._size_task is not None and not self._size_task.done():
+            return
+        if self._is_due(self._size_finished_at, self._size_refresh_seconds):
+            self._size_task = asyncio.create_task(self._walk_size())
+
+    async def _walk_size(self) -> None:
+        try:
+            self._shikiru_bytes = await asyncio.to_thread(tree_size, self._shikiru_root)
+            self._size_error = None
+        except OSError as error:
+            self._size_error = str(error)
+        self._size_finished_at = self._clock.now()
+
+    async def _sample_free_space(self) -> None:
+        now = self._clock.now()
+        self._attempted_at = now
+        try:
+            self._free_bytes, self._total_bytes = await asyncio.to_thread(
+                _filesystem, self._project_root
+            )
+        except OSError as error:
+            self._free_error = str(error)
+            return
+        self._free_error = None
+        self._sampled_at = now
+
+    def _snapshot(self) -> DiskSnapshot:
+        return DiskSnapshot(
+            self._free_bytes,
+            self._total_bytes,
+            self._shikiru_bytes,
+            self._sampled_at,
+            self._free_error or self._size_error,
+            failed=self._free_error is None and self._size_error is not None,
+        )
+
+
+def _filesystem(root: Path) -> tuple[int, int]:
+    usage = shutil.disk_usage(root)
+    return usage.free, usage.total

shikiru/telemetry/docker.py

@@ -0,0 +1,164 @@
+"""Docker container sampling for the dashboard."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+from shikiru.domain.docker import (
+    ContainerUsage,
+    DockerParseError,
+    DockerSummary,
+    parse_ps_record,
+    parse_stats_record,
+    summarize,
+)
+from shikiru.errors import CommandTimeoutError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+    from datetime import datetime
+    from pathlib import PurePath
+    from typing import Any
+
+    from shikiru.clock import Clock
+    from shikiru.process import ProcessResult, SubprocessRunner
+
+DOCKER_BINARY = "docker"
+DOCKER_PS_SUBCOMMAND = "ps"
+DOCKER_ALL_FLAG = "-a"
+DOCKER_STATS_SUBCOMMAND = "stats"
+DOCKER_NO_STREAM_FLAG = "--no-stream"
+DOCKER_FORMAT_FLAG = "--format"
+DOCKER_JSON_FORMAT = "json"
+
+
+@dataclass(frozen=True)
+class DockerSnapshot:
+    """The latest Docker sample and whether its daemon responded."""
+
+    available: bool
+    summary: DockerSummary | None = None
+    sampled_at: datetime | None = None
+    error: str | None = None
+    failed: bool = False
+
+
+class DockerSampler:
+    """Samples `docker ps -a` and `docker stats --no-stream` together through `SubprocessRunner`."""
+
+    def __init__(
+        self,
+        runner: SubprocessRunner,
+        clock: Clock,
+        *,
+        refresh_seconds: Callable[[], float],
+        timeout_seconds: float,
+        project_roots: Sequence[PurePath] | None,
+    ) -> None:
+        """Use injected process and time boundaries; `project_roots=None` scopes every container."""
+        self._runner = runner
+        self._clock = clock
+        self._refresh_seconds = refresh_seconds
+        self._timeout_seconds = timeout_seconds
+        self._project_roots = project_roots
+        self._sampled_at: datetime | None = None
+        self._last = DockerSnapshot(available=False)
+
+    async def sample(self) -> DockerSnapshot:
+        """Probe Docker and return the scoped container summary."""
+        now = self._clock.now()
+        if shutil.which(DOCKER_BINARY) is None:
+            self._record_problem(error="Docker CLI is unavailable", failed=False)
+        else:
+            listing, stats = await asyncio.gather(
+                self._attempt(DOCKER_PS_SUBCOMMAND, DOCKER_ALL_FLAG),
+                self._attempt(DOCKER_STATS_SUBCOMMAND, DOCKER_NO_STREAM_FLAG),
+            )
+            self._record(now, listing, stats)
+        self._sampled_at = now
+        return self._last
+
+    async def sample_if_due(self) -> DockerSnapshot:
+        """Run a Docker sample no more often than the configured refresh cadence."""
+        sampled_at = self._sampled_at
+        if (
+            sampled_at is None
+            or (self._clock.now() - sampled_at).total_seconds() >= self._refresh_seconds()
+        ):
+            return await self.sample()
+        return self._last
+
+    async def _attempt(self, *arguments: str) -> ProcessResult | CommandTimeoutError | OSError:
+        try:
+            return await self._runner.run(
+                [DOCKER_BINARY, *arguments, DOCKER_FORMAT_FLAG, DOCKER_JSON_FORMAT],
+                timeout=self._timeout_seconds,
+                check=False,
+            )
+        except (CommandTimeoutError, OSError) as error:
+            return error
+
+    def _record(
+        self,
+        now: datetime,
+        listing: ProcessResult | CommandTimeoutError | OSError,
+        stats: ProcessResult | CommandTimeoutError | OSError,
+    ) -> None:
+        if isinstance(listing, (CommandTimeoutError, OSError)):
+            self._record_problem(error=str(listing), failed=True)
+        elif listing.returncode != 0:
+            error = listing.stderr.strip() or f"Docker ps exited with status {listing.returncode}"
+            self._record_problem(error=error, failed=False)
+        else:
+            try:
+                containers = _decode(listing.stdout, parse_ps_record)
+                usages = _usages(stats)
+            except DockerParseError as error:
+                self._record_problem(error=str(error), failed=True)
+                return
+            self._last = DockerSnapshot(
+                available=True,
+                summary=summarize(containers, usages, self._project_roots),
+                sampled_at=now,
+            )
+
+    def _record_problem(self, *, error: str, failed: bool) -> None:
+        self._last = DockerSnapshot(
+            available=False,
+            summary=self._last.summary,
+            sampled_at=self._last.sampled_at,
+            error=error,
+            failed=failed,
+        )
+
+
+def _usages(
+    stats: ProcessResult | CommandTimeoutError | OSError,
+) -> list[ContainerUsage] | None:
+    if isinstance(stats, (CommandTimeoutError, OSError)) or stats.returncode != 0:
+        return None
+    try:
+        parsed = _decode(stats.stdout, parse_stats_record)
+    except DockerParseError:
+        return None
+    return [usage for usage in parsed if usage is not None]
+
+
+def _decode[Parsed](stdout: str, parse: Callable[[dict[str, object]], Parsed]) -> list[Parsed]:
+    return [parse(_record(line)) for line in stdout.splitlines() if line.strip()]
+
+
+def _record(line: str) -> dict[str, object]:
+    try:
+        decoded = json.loads(line)
+    except json.JSONDecodeError as error:
+        message = f"docker returned invalid JSON: {error}"
+        raise DockerParseError(message) from error
+    if not isinstance(decoded, dict):
+        message = "docker JSON record must be an object"
+        raise DockerParseError(message)
+    return cast("dict[str, Any]", decoded)

shikiru/telemetry/resources.py

@@ -0,0 +1,296 @@
+"""Host and engine process-tree resource sampling for scheduling and the dashboard."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import psutil
+
+from shikiru.process import ProcessIdentity
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from datetime import datetime
+
+    from shikiru.clock import Clock
+    from shikiru.config.settings import ResourcesConfig
+
+_BYTES_PER_GIB = 1024**3
+_PPID_ATTR = "ppid"
+_CREATE_TIME_ATTR = "create_time"
+_PERCENT_PER_CORE = 100.0
+_MIN_LIFETIME_SECONDS = 0.1
+
+
+@dataclass(frozen=True, slots=True)
+class _TableEntry:
+    process: psutil.Process
+    ppid: int
+    create_time: float
+
+
+@dataclass(frozen=True, slots=True)
+class _ProcessTable:
+    entries: dict[int, _TableEntry]
+    children: dict[int, list[int]]
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceSnapshot:
+    """The latest host, Shikiru and agent process-tree measurements."""
+
+    host_cpu_pct: float
+    host_ram_used_pct: float
+    free_ram_gb: float
+    instance_cpu_pct: float | None = None
+    instance_rss_gb: float | None = None
+    sampled_at: datetime | None = None
+    host_ram_used_bytes: int | None = None
+    host_ram_total_bytes: int | None = None
+    shikiru_cpu_pct: float | None = None
+    shikiru_rss_gb: float | None = None
+    agents_cpu_pct: float | None = None
+    agents_rss_gb: float | None = None
+    shikiru_process_tree_empty: bool | None = None
+    agents_process_tree_empty: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceProcessRoots:
+    """Classified live process identities supplied by the current project."""
+
+    shikiru: tuple[ProcessIdentity, ...]
+    agents: tuple[ProcessIdentity, ...]
+
+
+class ResourceSampleError(RuntimeError):
+    """The operating system could not provide a complete host or process sample."""
+
+
+class ResourceSampler:
+    """Samples host CPU and available memory through `psutil`."""
+
+    def __init__(self, clock: Clock, config: Callable[[], ResourcesConfig]) -> None:
+        """Use `clock` and the cadences `config` returns when each sample is due."""
+        self._clock = clock
+        self._config = config
+        self._host_cpu: deque[tuple[datetime, float]] = deque()
+        self._last = ResourceSnapshot(0.0, 0.0, 0.0)
+        self._last_complete = ResourceSnapshot(0.0, 0.0, 0.0)
+        self._sampled_at: datetime | None = None
+        self._instance_sampled_at: datetime | None = None
+        self._processes: dict[tuple[int, float], psutil.Process] = {}
+
+    def sample(self) -> ResourceSnapshot:
+        """Take one host CPU and available memory sample."""
+        now = self._clock.now()
+        try:
+            host_cpu = psutil.cpu_percent(interval=None)
+            virtual_memory = psutil.virtual_memory()
+        except psutil.Error as error:
+            raise ResourceSampleError(str(error)) from error
+        self._host_cpu.append((now, host_cpu))
+        self._trim(now)
+        self._last = ResourceSnapshot(
+            host_cpu_pct=_average(value for _, value in self._host_cpu),
+            host_ram_used_pct=virtual_memory.percent,
+            free_ram_gb=virtual_memory.available / _BYTES_PER_GIB,
+            sampled_at=now,
+            host_ram_used_bytes=virtual_memory.used,
+            host_ram_total_bytes=virtual_memory.total,
+        )
+        self._sampled_at = now
+        return self._last
+
+    def sample_if_due(self) -> ResourceSnapshot:
+        """Sample at the configured cadence and return the latest snapshot."""
+        sampled_at = self._sampled_at
+        if (
+            sampled_at is None
+            or (self._clock.now() - sampled_at).total_seconds() >= self._config().sample_seconds
+        ):
+            return self.sample()
+        return self._last
+
+    def resources_ok(self, config: ResourcesConfig) -> bool:
+        """Return whether a fresh sample passes scheduling thresholds."""
+        sample = self.sample_if_due()
+        return (
+            sample.host_cpu_pct < config.max_cpu_pct
+            and sample.free_ram_gb >= config.min_free_ram_gb
+        )
+
+    def process_sample_is_fresh(self) -> bool:
+        """Return whether the latest process-tree sample is younger than the sample cadence."""
+        sampled_at = self._instance_sampled_at
+        return (
+            sampled_at is not None
+            and (self._clock.now() - sampled_at).total_seconds() < self._config().sample_seconds
+        )
+
+    def sample_process_roots(self, roots: ResourceProcessRoots) -> ResourceSnapshot:
+        """Sample host, Shikiru and agent trees from classified process identities."""
+        if self.process_sample_is_fresh():
+            return self._last_complete
+        now = self._clock.now()
+        host_sample = self.sample_if_due()
+        table = self._process_table()
+        agent_processes = self._process_tree(roots.agents, table)
+        agent_identities = set(agent_processes)
+        shikiru_processes = {
+            identity: process
+            for identity, process in self._process_tree(roots.shikiru, table).items()
+            if identity not in agent_identities
+        }
+        all_processes = {**shikiru_processes, **agent_processes}
+        measurements = self._measure_processes(all_processes, now.timestamp())
+        shikiru_measurements = [
+            measurement
+            for identity, measurement in measurements.items()
+            if identity in shikiru_processes
+        ]
+        agent_measurements = [
+            measurement
+            for identity, measurement in measurements.items()
+            if identity in agent_processes
+        ]
+        instance_cpu_pct, instance_rss_gb = _usage(list(measurements.values()))
+        shikiru_cpu_pct, shikiru_rss_gb = _usage(shikiru_measurements)
+        agents_cpu_pct, agents_rss_gb = _usage(agent_measurements)
+        snapshot = ResourceSnapshot(
+            host_cpu_pct=host_sample.host_cpu_pct,
+            host_ram_used_pct=host_sample.host_ram_used_pct,
+            free_ram_gb=host_sample.free_ram_gb,
+            instance_cpu_pct=instance_cpu_pct,
+            instance_rss_gb=instance_rss_gb,
+            sampled_at=now,
+            host_ram_used_bytes=host_sample.host_ram_used_bytes,
+            host_ram_total_bytes=host_sample.host_ram_total_bytes,
+            shikiru_cpu_pct=shikiru_cpu_pct,
+            shikiru_rss_gb=shikiru_rss_gb,
+            agents_cpu_pct=agents_cpu_pct,
+            agents_rss_gb=agents_rss_gb,
+            shikiru_process_tree_empty=not shikiru_measurements,
+            agents_process_tree_empty=not agent_measurements,
+        )
+        self._last = snapshot
+        self._last_complete = snapshot
+        self._instance_sampled_at = now
+        self._processes = {
+            identity: process
+            for identity, process in all_processes.items()
+            if identity in measurements
+        }
+        return snapshot
+
+    def latest(self) -> ResourceSnapshot:
+        """Return the latest sample without starting a new observation."""
+        return self._last_complete
+
+    def _process_table(self) -> _ProcessTable:
+        entries: dict[int, _TableEntry] = {}
+        children: dict[int, list[int]] = {}
+        for process in psutil.process_iter([_PPID_ATTR, _CREATE_TIME_ATTR]):
+            ppid = process.info[_PPID_ATTR]
+            create_time = process.info[_CREATE_TIME_ATTR]
+            if ppid is None or create_time is None:
+                continue
+            entries[process.pid] = _TableEntry(process, ppid, create_time)
+            children.setdefault(ppid, []).append(process.pid)
+        return _ProcessTable(entries, children)
+
+    @staticmethod
+    def _add_unlisted_root(root_identity: ProcessIdentity, table: _ProcessTable) -> bool:
+        try:
+            process = psutil.Process(root_identity.pid)
+            entry = _TableEntry(process, process.ppid(), process.create_time())
+        except psutil.NoSuchProcess, psutil.ZombieProcess:
+            return False
+        except psutil.Error as error:
+            raise ResourceSampleError(str(error)) from error
+        table.entries[root_identity.pid] = entry
+        table.children.setdefault(entry.ppid, []).append(root_identity.pid)
+        return True
+
+    def _process_tree(
+        self, roots: Iterable[ProcessIdentity], table: _ProcessTable
+    ) -> dict[tuple[int, float], psutil.Process]:
+        found: dict[tuple[int, float], psutil.Process] = {}
+        for root_identity in roots:
+            if root_identity.pid not in table.entries and not self._add_unlisted_root(
+                root_identity, table
+            ):
+                continue
+            root = table.entries[root_identity.pid]
+            if not root_identity.matches(ProcessIdentity(root_identity.pid, root.create_time)):
+                continue
+            pending = [root_identity.pid]
+            while pending:
+                pid = pending.pop()
+                entry = table.entries[pid]
+                process_key = (pid, entry.create_time)
+                if process_key in found:
+                    continue
+                found[process_key] = self._processes.get(process_key, entry.process)
+                pending.extend(
+                    child
+                    for child in table.children.get(pid, ())
+                    if table.entries[child].create_time >= entry.create_time
+                )
+        return found
+
+    def _measure_processes(
+        self,
+        processes: dict[tuple[int, float], psutil.Process],
+        now_timestamp: float,
+    ) -> dict[tuple[int, float], tuple[float, int]]:
+        measurements: dict[tuple[int, float], tuple[float, int]] = {}
+        for identity, process in processes.items():
+            first_sight_at = None if identity in self._processes else now_timestamp
+            measurement = self._measure(process, first_sight_at)
+            if measurement is not None:
+                measurements[identity] = measurement
+        return measurements
+
+    @staticmethod
+    def _measure(process: psutil.Process, first_sight_at: float | None) -> tuple[float, int] | None:
+        try:
+            with process.oneshot():
+                cpu_pct = process.cpu_percent(interval=None)
+                if first_sight_at is not None:
+                    cpu_pct = _lifetime_cpu_pct(process, first_sight_at)
+                return cpu_pct, process.memory_info().rss
+        except psutil.NoSuchProcess, psutil.ZombieProcess:
+            return None
+        except psutil.Error as error:
+            raise ResourceSampleError(str(error)) from error
+
+    def _trim(self, now: datetime) -> None:
+        cutoff = now.timestamp() - self._config().cpu_window_seconds
+        while self._host_cpu and self._host_cpu[0][0].timestamp() < cutoff:
+            self._host_cpu.popleft()
+
+
+def _lifetime_cpu_pct(process: psutil.Process, now_timestamp: float) -> float:
+    times = process.cpu_times()
+    lifetime = max(now_timestamp - process.create_time(), _MIN_LIFETIME_SECONDS)
+    return (times.user + times.system) * _PERCENT_PER_CORE / lifetime
+
+
+def _average(values: Iterable[float]) -> float:
+    sequence = tuple(values)
+    return sum(sequence, 0.0) / len(sequence) if sequence else 0.0
+
+
+def _usage(measurements: list[tuple[float, int]]) -> tuple[float | None, float | None]:
+    if not measurements:
+        return None, None
+    cpu_count = psutil.cpu_count(logical=True)
+    if cpu_count is None or cpu_count < 1:
+        message = "psutil did not report a logical CPU count"
+        raise RuntimeError(message)
+    cpu_pct = sum(cpu for cpu, _ in measurements) / cpu_count
+    rss_gb = sum(rss for _, rss in measurements) / _BYTES_PER_GIB
+    return cpu_pct, rss_gb

shikiru/tmux/__init__.py

@@ -0,0 +1,3 @@
+"""tmux client, session, layout and decoration."""
+
+from __future__ import annotations