dockerbrain 1.0__py3-none-any.whl

core/monitor/collector.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
+
+import docker
+from docker.errors import APIError, DockerException
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+
+from core.monitor.snapshot import (
+    ContainerSnapshot,
+    IDLE_CPU_THRESHOLD,
+    IDLE_CONSECUTIVE_POLLS,
+)
+from core.monitor.display import build_monitor_layout
+from core.storage import store_snapshot
+from core.utils import calc_cpu_percent, get_docker_offline_hint
+
+console = Console()
+
+
+class ContainerMonitor:
+    """Polls Docker container stats and tracks idle state."""
+
+    def __init__(self, interval: int = 1) -> None:
+        self.interval = interval
+        self.client = self._connect()
+        self._idle_counter: dict[str, int] = defaultdict(int)
+        self._lock = threading.Lock()
+        self._latest_snapshots: list[ContainerSnapshot] = []
+
+    @staticmethod
+    def _connect() -> docker.DockerClient:
+        try:
+            return docker.from_env()
+        except DockerException as exc:
+            console.print(
+                Panel(
+                    "[red bold]Could not connect to Docker daemon.[/]\n\n"
+                    f"{get_docker_offline_hint()}\n\n",
+                    title="[bold red]Docker Unavailable[/]",
+                    border_style="red",
+                    expand=False,
+                )
+            )
+            raise SystemExit(3) from exc
+
+    def _fetch_one(self, ctr: object) -> ContainerSnapshot | None:
+        """Fetch stats for a single container."""
+        try:
+            raw = ctr.stats(stream=False)
+            ctr.reload()
+        except (APIError, DockerException) as exc:
+            console.print(f"[yellow] Skipping {ctr.name}: {exc}[/]", highlight=False)
+            return None
+
+        cpu = calc_cpu_percent(raw)
+
+        mem_stats = raw.get("memory_stats", {})
+        mem_raw = mem_stats.get("usage", 0)
+        mem_limit = mem_stats.get("limit", 1)
+
+        cache = mem_stats.get("stats", {}).get("inactive_file", 0)
+        if not cache:
+            cache = mem_stats.get("stats", {}).get("cache", 0)
+        mem_usage = mem_raw - cache
+
+        mem_usage_mb = mem_usage / (1024 * 1024)
+        mem_limit_mb = mem_limit / (1024 * 1024)
+        mem_percent = (mem_usage / mem_limit) * 100.0 if mem_limit else 0.0
+
+        networks = raw.get("networks", {})
+        net_rx = sum(v.get("rx_bytes", 0) for v in networks.values())
+        net_tx = sum(v.get("tx_bytes", 0) for v in networks.values())
+        net_rx_pkts = sum(v.get("rx_packets", 0) for v in networks.values())
+        net_tx_pkts = sum(v.get("tx_packets", 0) for v in networks.values())
+        net_rx_errs = sum(v.get("rx_errors", 0) for v in networks.values())
+        net_tx_errs = sum(v.get("tx_errors", 0) for v in networks.values())
+        net_rx_drop = sum(v.get("rx_dropped", 0) for v in networks.values())
+        net_tx_drop = sum(v.get("tx_dropped", 0) for v in networks.values())
+
+        uptime_secs = 0.0
+        started_at = ctr.attrs.get("State", {}).get("StartedAt", "")
+        if started_at:
+            try:
+                start_dt = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+                uptime_secs = (datetime.now(timezone.utc) - start_dt).total_seconds()
+            except (ValueError, TypeError):
+                pass
+
+        restart_count = ctr.attrs.get("RestartCount", 0)
+        image_tag = ctr.image.tags[0] if ctr.image.tags else ctr.image.short_id
+
+        with self._lock:
+            if cpu < IDLE_CPU_THRESHOLD:
+                self._idle_counter[ctr.name] += 1
+            else:
+                self._idle_counter[ctr.name] = 0
+            idle_polls = self._idle_counter[ctr.name]
+
+        is_idle = idle_polls >= IDLE_CONSECUTIVE_POLLS
+
+        return ContainerSnapshot(
+            name=ctr.name,
+            status=ctr.status,
+            cpu_percent=cpu,
+            mem_usage_mb=mem_usage_mb,
+            mem_limit_mb=mem_limit_mb,
+            mem_percent=mem_percent,
+            mem_cache_mb=cache / (1024 * 1024),
+            net_rx_bytes=net_rx,
+            net_tx_bytes=net_tx,
+            net_rx_packets=net_rx_pkts,
+            net_tx_packets=net_tx_pkts,
+            net_rx_errors=net_rx_errs,
+            net_tx_errors=net_tx_errs,
+            net_rx_dropped=net_rx_drop,
+            net_tx_dropped=net_tx_drop,
+            is_idle=is_idle,
+            idle_polls=idle_polls,
+            uptime_seconds=uptime_secs,
+            restart_count=restart_count,
+            image_tag=image_tag,
+        )
+
+    def poll(self) -> list[ContainerSnapshot]:
+        """Collect one snapshot for every running container in parallel.
+        Uses a thread pool so N containers finish in ~1s (time of slowest
+        single stats call), not N seconds.
+        """
+        containers = self.client.containers.list()
+        if not containers:
+            return []
+
+        snapshots: list[ContainerSnapshot] = []
+
+        with ThreadPoolExecutor(max_workers=min(len(containers), 20)) as pool:
+            futures = {pool.submit(self._fetch_one, ctr): ctr for ctr in containers}
+            for fut in as_completed(futures):
+                result = fut.result()
+                if result is not None:
+                    snapshots.append(result)
+                    store_snapshot(result)
+
+        snapshots.sort(key=lambda s: s.name)
+        return snapshots
+
+    def run(self, duration: int | None = None) -> None:
+        """Poll containers in a background thread, refresh display every second.
+
+        Polling runs in a daemon thread using a thread pool.
+        The display loop redraws every second from the latest shared snapshot.
+        """
+        start = time.monotonic()
+        stop_event = threading.Event()
+
+        def _poll_loop() -> None:
+            while not stop_event.is_set():
+                snaps = self.poll()
+                with self._lock:
+                    self._latest_snapshots = snaps
+                stop_event.wait(self.interval)
+
+        poll_thread = threading.Thread(target=_poll_loop, daemon=True)
+        poll_thread.start()
+
+        try:
+            with Live(console=console, refresh_per_second=4, screen=True) as live:
+                while True:
+                    elapsed = time.monotonic() - start
+                    if duration and elapsed >= duration:
+                        break
+
+                    with self._lock:
+                        snaps = list(self._latest_snapshots)
+
+                    live.update(build_monitor_layout(snaps))
+                    time.sleep(1)
+
+        except KeyboardInterrupt:
+            pass
+        finally:
+            stop_event.set()
+
+        elapsed = time.monotonic() - start
+        console.print(f"\n[yellow]Monitoring stopped after {elapsed:.0f}s.[/]")
+
+
+def run_monitor(interval: int = 1, duration: int | None = None) -> None:
+    """Create a ContainerMonitor and start polling."""
+    monitor = ContainerMonitor(interval=interval)
+    monitor.run(duration=duration)

core/monitor/display.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from rich.align import Align
+from rich.layout import Layout
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from core.monitor.snapshot import (
+    ContainerSnapshot,
+    MEM_WARNING_PCT,
+    MEM_CRITICAL_PCT,
+)
+from core.utils import format_bytes
+
+_BLOCKS = " ▏▎▍▌▋▊▉█"
+
+
+def _format_uptime(seconds: float) -> str:
+    """Convert seconds to a human-readable uptime string."""
+    if seconds < 60:
+        return f"{seconds:.0f}s"
+    if seconds < 3600:
+        return f"{seconds / 60:.0f}m"
+    hours = seconds // 3600
+    mins = (seconds % 3600) // 60
+    if hours < 24:
+        return f"{hours:.0f}h {mins:.0f}m"
+    days = hours // 24
+    hours = hours % 24
+    return f"{days:.0f}d {hours:.0f}h"
+
+
+def _make_bar(value: float, max_value: float, width: int, color: str) -> Text:
+    """Build a Unicode bar with sub-character precision.
+
+    Uses eighth-block characters (▏▎▍▌▋▊▉█) so a 30-char bar
+    effectively has 240 discrete steps of resolution.
+    """
+    if max_value <= 0:
+        return Text("░" * width, style="dim")
+
+    ratio = min(value / max_value, 1.0)
+    total_eighths = int(ratio * width * 8)
+    full = total_eighths // 8
+    frac = total_eighths % 8
+    empty = width - full - (1 if frac else 0)
+
+    bar = Text()
+    bar.append("█" * full, style=color)
+    if frac:
+        bar.append(_BLOCKS[frac], style=color)
+    bar.append("░" * empty, style="dim")
+    return bar
+
+
+def _cpu_color(pct: float) -> str:
+    """Return a Rich style for a CPU percentage."""
+    if pct > 80:
+        return "bold red"
+    if pct > 50:
+        return "yellow"
+    return "green"
+
+
+def _mem_color(pct: float) -> str:
+    """Return a Rich style for a memory percentage."""
+    if pct > MEM_CRITICAL_PCT:
+        return "bold red"
+    if pct > MEM_WARNING_PCT:
+        return "yellow"
+    return "cyan"
+
+
+def build_monitor_layout(snapshots: list[ContainerSnapshot]) -> Layout:
+    """Build a full-screen Rich Layout with bar graphs and panels."""
+    n = max(len(snapshots), 1)
+    BAR_WIDTH = 30
+
+    header_text = Text()
+    header_text.append("DockerBrain", style="bold cyan")
+    header_text.append("  Monitor", style="dim")
+
+    header = Panel(
+        Align.center(header_text),
+        border_style="bright_blue",
+        style="on #1a1a2e",
+    )
+
+    running = sum(1 for s in snapshots if s.status == "running")
+    idle = sum(1 for s in snapshots if s.is_idle)
+    healthy = sum(1 for s in snapshots if s.health_label == "HEALTHY")
+    warning = sum(1 for s in snapshots if s.health_label == "WARNING")
+    critical = sum(1 for s in snapshots if s.health_label == "CRITICAL")
+
+    total_cpu = sum(s.cpu_percent for s in snapshots)
+    total_mem = sum(s.mem_usage_mb for s in snapshots)
+    total_mem_limit = max((s.mem_limit_mb for s in snapshots), default=1)
+    avg_mem_pct = (total_mem / total_mem_limit) * 100 if snapshots else 0
+    total_cache = sum(s.mem_cache_mb for s in snapshots)
+
+    stats = Text()
+    stats.append("  Containers ", style="bold")
+    stats.append(f"{len(snapshots)}", style="bold cyan")
+    stats.append("  Running ", style="bold")
+    stats.append(f"{running}", style="bold green")
+    stats.append("  Idle ", style="bold")
+    stats.append(f"{idle}", style="bold red" if idle else "dim")
+    stats.append("  Healthy ", style="bold")
+    stats.append(f"{healthy}", style="bold green")
+    stats.append("  Warn ", style="bold")
+    stats.append(f"{warning}", style="bold yellow" if warning else "dim")
+    stats.append("  Crit ", style="bold")
+    stats.append(f"{critical}\n", style="bold red" if critical else "dim")
+    stats.append("  CPU ", style="bold")
+    stats.append(f"{total_cpu:.1f}%", style=_cpu_color(total_cpu))
+    stats.append("  Mem ", style="bold")
+    stats.append(f"{total_mem:.0f}/{total_mem_limit:.0f} MB", style=_mem_color(avg_mem_pct))
+    stats.append("  Cache ", style="bold")
+    stats.append(f"{total_cache:.0f} MB", style="dim")
+
+    overview_panel = Panel(
+        stats,
+        title="[bold cyan]System Overview[/]",
+        border_style="cyan",
+        padding=(0, 1),
+    )
+
+    table = Table(expand=True, border_style="dim", show_lines=False, pad_edge=False)
+    table.add_column("Container", style="bold cyan", no_wrap=True)
+    table.add_column("Image", style="dim", no_wrap=True, max_width=28)
+    table.add_column("Status", justify="center")
+    table.add_column("Uptime", justify="right")
+    table.add_column("Health", justify="center")
+
+    for s in snapshots:
+        dot_style = "green" if s.status == "running" else "red"
+        status_text = Text()
+        status_text.append("● ", style=dot_style)
+        status_text.append(s.status)
+
+        table.add_row(
+            s.name,
+            s.image_tag,
+            status_text,
+            _format_uptime(s.uptime_seconds),
+            Text(s.health_label, style=f"bold {s.health_style}"),
+        )
+
+    if not snapshots:
+        table.add_row(
+            Text("No running containers", style="yellow"),
+            "", "", "", "",
+        )
+
+    table_panel = Panel(
+        table,
+        title="[bold cyan]Containers[/]",
+        border_style="cyan",
+        padding=(0, 1),
+    )
+
+    cpu_content = Text()
+    for i, s in enumerate(snapshots):
+        color = _cpu_color(s.cpu_percent)
+        label = s.name if len(s.name) <= 14 else s.name[:11] + "…"
+        cpu_content.append(f" {label:<14} ", style="cyan")
+        cpu_content.append_text(_make_bar(s.cpu_percent, 100, BAR_WIDTH, color))
+        cpu_content.append(f" {s.cpu_percent:>5.1f}%", style=f"bold {color}")
+        if s.is_idle:
+            cpu_content.append(" idle", style="bold red")
+        if i < len(snapshots) - 1:
+            cpu_content.append("\n")
+
+    if not snapshots:
+        cpu_content.append("  Waiting for containers…", style="dim italic")
+
+    cpu_panel = Panel(
+        cpu_content,
+        title="[bold green]CPU Usage[/]",
+        border_style="green",
+        padding=(0, 1),
+    )
+
+    mem_content = Text()
+    for i, s in enumerate(snapshots):
+        color = _mem_color(s.mem_percent)
+        label = s.name if len(s.name) <= 14 else s.name[:11] + "…"
+        mem_content.append(f" {label:<14} ", style="cyan")
+        mem_content.append_text(_make_bar(s.mem_percent, 100, BAR_WIDTH, color))
+        mem_content.append(
+            f" {s.mem_usage_mb:>6.1f}/{s.mem_limit_mb:>.0f}MB",
+            style=color,
+        )
+        mem_content.append(f" {s.mem_percent:.0f}%", style=f"bold {color}")
+        if i < len(snapshots) - 1:
+            mem_content.append("\n")
+
+    if not snapshots:
+        mem_content.append("  Waiting for containers…", style="dim italic")
+
+    mem_panel = Panel(
+        mem_content,
+        title="[bold blue]Memory Usage[/]",
+        border_style="blue",
+        padding=(0, 1),
+    )
+
+    net_table = Table(expand=True, show_header=True, show_lines=False, border_style="dim", pad_edge=False)
+    net_table.add_column("Container", style="cyan", no_wrap=True)
+    net_table.add_column("↓ Recv", justify="right", style="green")
+    net_table.add_column("↑ Sent", justify="right", style="yellow")
+    net_table.add_column("Rx Pkts", justify="right", style="blue")
+    net_table.add_column("Tx Pkts", justify="right", style="blue")
+    net_table.add_column("Err", justify="right")
+    net_table.add_column("Drop", justify="right")
+
+    total_rx = total_tx = 0
+    total_rx_pkts = total_tx_pkts = 0
+    total_errs = total_drops = 0
+    for s in snapshots:
+        total_rx += s.net_rx_bytes
+        total_tx += s.net_tx_bytes
+        total_rx_pkts += s.net_rx_packets
+        total_tx_pkts += s.net_tx_packets
+        errs = s.net_rx_errors + s.net_tx_errors
+        drops = s.net_rx_dropped + s.net_tx_dropped
+        total_errs += errs
+        total_drops += drops
+
+        err_style = "bold red" if errs > 0 else "dim"
+        drop_style = "bold red" if drops > 0 else "dim"
+
+        net_table.add_row(
+            s.name,
+            format_bytes(s.net_rx_bytes),
+            format_bytes(s.net_tx_bytes),
+            f"{s.net_rx_packets:,}",
+            f"{s.net_tx_packets:,}",
+            Text(str(errs), style=err_style),
+            Text(str(drops), style=drop_style),
+        )
+
+
+    if not snapshots:
+        net_table.add_row(
+            Text("Waiting for containers…", style="dim italic"),
+            "", "", "", "", "", "",
+        )
+
+    net_panel = Panel(
+        net_table,
+        title="[bold magenta]Network I/O[/]",
+        border_style="magenta",
+        padding=(0, 1),
+    )
+
+    layout = Layout()
+
+    layout.split_column(
+        Layout(name="header", size=3),
+        Layout(name="overview", size=4),
+        Layout(name="table", ratio=2),
+        Layout(name="bars_row", ratio=1),
+        Layout(name="network", ratio=2),
+    )
+
+    layout["header"].update(header)
+    layout["overview"].update(overview_panel)
+    layout["table"].update(table_panel)
+    layout["bars_row"].split_row(
+        Layout(name="cpu", ratio=1),
+        Layout(name="mem", ratio=1),
+    )
+    layout["cpu"].update(cpu_panel)
+    layout["mem"].update(mem_panel)
+    layout["network"].update(net_panel)
+
+    return layout

core/monitor/snapshot.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+IDLE_CPU_THRESHOLD: float = 0.5
+IDLE_CONSECUTIVE_POLLS: int = 10
+MEM_WARNING_PCT: float = 70.0
+MEM_CRITICAL_PCT: float = 85.0
+
+
+@dataclass
+class ContainerSnapshot:
+    """One point-in-time snapshot of a container's resource usage."""
+
+    name: str
+    status: str
+    cpu_percent: float
+    mem_usage_mb: float
+    mem_limit_mb: float
+    mem_percent: float
+    net_rx_bytes: int
+    net_tx_bytes: int
+    net_rx_packets: int = 0
+    net_tx_packets: int = 0
+    net_rx_errors: int = 0
+    net_tx_errors: int = 0
+    net_rx_dropped: int = 0
+    net_tx_dropped: int = 0
+    mem_cache_mb: float = 0.0
+    is_idle: bool = False
+    idle_polls: int = 0
+    uptime_seconds: float = 0.0
+    restart_count: int = 0
+    image_tag: str = ""
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    @property
+    def health_style(self) -> str:
+        """Return a Rich style string based on health status."""
+        if self.is_idle:
+            return "red"
+        if self.mem_percent > MEM_CRITICAL_PCT:
+            return "red"
+        if self.mem_percent > MEM_WARNING_PCT:
+            return "yellow"
+        return "green"
+
+    @property
+    def health_label(self) -> str:
+        if self.is_idle:
+            return "IDLE"
+        if self.mem_percent > MEM_CRITICAL_PCT:
+            return "CRITICAL"
+        if self.mem_percent > MEM_WARNING_PCT:
+            return "WARNING"
+        return "HEALTHY"

core/optimizer/__init__.py

@@ -0,0 +1,23 @@
+from core.optimizer.rules import (
+    Severity,
+    Suggestion,
+    Rule,
+    IdleContainerRule,
+    MemoryHogRule,
+    NoMemoryLimitRule,
+    HighRestartRule,
+    StaleImageRule,
+)
+from core.optimizer.engine import RuleBasedOptimizer
+
+__all__ = [
+    "Severity",
+    "Suggestion",
+    "Rule",
+    "IdleContainerRule",
+    "MemoryHogRule",
+    "NoMemoryLimitRule",
+    "HighRestartRule",
+    "StaleImageRule",
+    "RuleBasedOptimizer",
+]

core/optimizer/engine.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import docker
+from docker.errors import APIError, DockerException
+from rich.console import Console
+from rich.panel import Panel
+
+from core.optimizer.rules import (
+    Suggestion,
+    IdleContainerRule,
+    MemoryHogRule,
+    NoMemoryLimitRule,
+    HighRestartRule,
+    StaleImageRule,
+    Rule,
+)
+from core.utils import get_docker_offline_hint
+
+if TYPE_CHECKING:
+    from docker.models.containers import Container
+
+console = Console()
+
+
+class RuleBasedOptimizer:
+    """Evaluates all registered rules against running containers."""
+
+    def __init__(self) -> None:
+        self.client = self._connect()
+        self.rules: list[Rule] = [
+            IdleContainerRule(),
+            MemoryHogRule(),
+            NoMemoryLimitRule(),
+            HighRestartRule(),
+            StaleImageRule(),
+        ]
+
+    @staticmethod
+    def _connect() -> docker.DockerClient:
+        try:
+            return docker.from_env()
+        except DockerException as exc:
+            console.print(
+                Panel(
+                    "[red bold]Could not connect to Docker daemon.[/]\n\n"
+                    f"{get_docker_offline_hint()}\n\n",
+                    title="[bold red]Docker Unavailable[/]",
+                    border_style="red",
+                    expand=False,
+                )
+            )
+            raise SystemExit(3) from exc
+
+    def analyze(self, container_name: str | None = None) -> list[Suggestion]:
+        """Run every rule against target containers and return suggestions."""
+        containers: list[Container] = (
+            [self.client.containers.get(container_name)]
+            if container_name
+            else self.client.containers.list()
+        )
+
+        if not containers:
+            return []
+
+        suggestions: list[Suggestion] = []
+
+        for ctr in containers:
+            try:
+                ctr.reload()
+                raw_stats = ctr.stats(stream=False)
+            except (APIError, DockerException) as exc:
+                console.print(
+                    f"[yellow] Skipping {ctr.name}: {exc}[/]",
+                    highlight=False,
+                )
+                continue
+
+            for rule in self.rules:
+                suggestions.extend(rule.evaluate(ctr, raw_stats))
+
+        suggestions.sort(key=lambda s: s.severity.rank)
+        return suggestions