servchart-agent 0.3.1__tar.gz → 0.4.0__tar.gz

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: servchart-agent
-Version: 0.3.1
+Version: 0.4.0
 Summary: ServChart agent: reports a host's Docker containers, networks and Compose stacks to a ServChart hub.
 Project-URL: Homepage, https://github.com/opticodev/servchart
 Project-URL: Issues, https://github.com/opticodev/servchart/issues
@@ -31,6 +31,7 @@ It reads this host's Docker state (GET requests only), drops anything sensitive,
 ```bash
 docker run -d --name servchart-agent --restart unless-stopped --pid host \
   -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -v /:/host:ro,rslave -e SERVCHART_HOST_ROOT=/host \
   -e SERVCHART_OBSERVE_CONNECTIONS=1 \
   -e SERVCHART_HUB=https://servchart.example.com \
   -e SERVCHART_TOKEN=sc_... \
@@ -51,4 +52,6 @@ Get the token from the hub: **+ Add host** in the map.
 
 It sends container names, images, state and health, networks and IPs, published ports, mounts, restart policy, and Compose stack details (project, service, folder, compose files). It **never** sends environment variables or container commands, and secret-looking label values are redacted. Set `SERVCHART_HIDE_PATHS=1` to also drop host paths and stack folders.
 
+Since 0.4 it also reports server health (CPU, memory, load, uptime, disk usage of each mount point), per-container CPU and memory, Docker's disk use, and backup status files from `/var/lib/servchart/status`. After a backup job, record it with `servchart-agent --mark NAME` (add `--failed` when it failed).
+
 All options are in the [main README](https://github.com/opticodev/servchart#agent).

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/README.md

@@ -11,6 +11,7 @@ It reads this host's Docker state (GET requests only), drops anything sensitive,
 ```bash
 docker run -d --name servchart-agent --restart unless-stopped --pid host \
   -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -v /:/host:ro,rslave -e SERVCHART_HOST_ROOT=/host \
   -e SERVCHART_OBSERVE_CONNECTIONS=1 \
   -e SERVCHART_HUB=https://servchart.example.com \
   -e SERVCHART_TOKEN=sc_... \
@@ -31,4 +32,6 @@ Get the token from the hub: **+ Add host** in the map.
 
 It sends container names, images, state and health, networks and IPs, published ports, mounts, restart policy, and Compose stack details (project, service, folder, compose files). It **never** sends environment variables or container commands, and secret-looking label values are redacted. Set `SERVCHART_HIDE_PATHS=1` to also drop host paths and stack folders.
 
+Since 0.4 it also reports server health (CPU, memory, load, uptime, disk usage of each mount point), per-container CPU and memory, Docker's disk use, and backup status files from `/var/lib/servchart/status`. After a backup job, record it with `servchart-agent --mark NAME` (add `--failed` when it failed).
+
 All options are in the [main README](https://github.com/opticodev/servchart#agent).

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/servchart_agent/__init__.py

@@ -1,4 +1,4 @@
 """ServChart agent: reads Docker state on one host and reports it to a ServChart hub."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 SCHEMA_VERSION = 1

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/servchart_agent/__main__.py

@@ -2,6 +2,7 @@
 
     python -m servchart_agent --hub https://servchart.example.com --token sc_xxx
     python -m servchart_agent --stdout          # print one snapshot and exit
+    python -m servchart_agent --mark kopia      # record a successful backup run (see backups.py)
 
 Every option can also be set with an environment variable (shown in --help).
 """
@@ -18,7 +19,7 @@ import time
 import urllib.error
 import urllib.request
 
-from . import __version__, commands
+from . import __version__, backups, commands
 from .collect import collect
 from .docker_api import DockerClient, DockerError
 
@@ -55,7 +56,27 @@ def hub_request(hub: str, token: str, ca_file: str | None = None, insecure: bool
 
 
 def push(snapshot: dict, hub: str, token: str, ca_file: str | None = None, insecure: bool = False) -> None:
-    hub_request(hub, token, ca_file, insecure)("POST", "/api/v1/report", snapshot)
+    answer = hub_request(hub, token, ca_file, insecure)("POST", "/api/v1/report", snapshot)
+    apply_hub_hints(answer)
+
+
+def apply_hub_hints(answer) -> None:
+    """The hub may list your public addresses so connections to them get reported (max 50, IPs only)."""
+    import ipaddress
+
+    from . import connections
+
+    ips = (answer or {}).get("observe_ips") if isinstance(answer, dict) else None
+    if not isinstance(ips, list):
+        return
+    clean = set()
+    for ip in ips[:50]:
+        try:
+            clean.add(str(ipaddress.ip_address(str(ip))))
+        except ValueError:
+            continue
+    connections.EXTRA_IPS.clear()
+    connections.EXTRA_IPS.update(clean)
 
 
 def parse_args(argv=None):
@@ -72,6 +93,10 @@ def parse_args(argv=None):
                    help="Skip TLS verification (env SERVCHART_INSECURE=1). Not recommended.")
     p.add_argument("--once", action="store_true", help="Report once and exit")
     p.add_argument("--stdout", action="store_true", help="Print the snapshot as JSON instead of sending it")
+    p.add_argument("--mark", metavar="NAME", help="Record that the backup job NAME just finished, then exit")
+    p.add_argument("--failed", action="store_true", help="With --mark: the backup failed")
+    p.add_argument("--message", default="", help="With --mark: a short note shown in ServChart")
+    p.add_argument("--max-age-hours", type=float, help="With --mark: warn when no new run within this many hours (default 26)")
     p.add_argument("--version", action="version", version=f"servchart-agent {__version__}")
     return p.parse_args(argv)
 
@@ -80,6 +105,14 @@ def main(argv=None) -> int:
     logging.basicConfig(level=os.environ.get("SERVCHART_LOG_LEVEL", "INFO"),
                         format="%(asctime)s %(levelname)s %(message)s")
     args = parse_args(argv)
+    if args.mark:
+        try:
+            path = backups.mark(args.mark, ok=not args.failed, message=args.message, max_age_hours=args.max_age_hours)
+        except (ValueError, OSError) as exc:
+            log.error("could not record backup status: %s", exc)
+            return 1
+        log.info("recorded %s backup %s in %s", args.mark, "failure" if args.failed else "success", path)
+        return 0
     client = DockerClient()
 
     if args.stdout:

servchart_agent-0.4.0/servchart_agent/backups.py

@@ -0,0 +1,111 @@
+"""Backup status, from small status files your backup jobs write (any backup tool).
+
+Put one file per job in /var/lib/servchart/status on the host (or SERVCHART_STATUS_DIR). In a
+container the agent finds it through the host root mount (SERVCHART_HOST_ROOT=/host):
+
+  * a JSON file such as `kopia.json`:
+      {"ok": true, "finished_at": "2026-10-20T03:12:00Z", "max_age_hours": 26,
+       "message": "1.2 GB uploaded", "size_bytes": 1234567}
+    every field is optional; `finished_at` defaults to the file's modification time;
+  * or any other file: its modification time counts as the last successful run.
+
+`servchart-agent --mark NAME` (or `--mark NAME --failed --message "..."`) writes one for you,
+so a cron job can end with `&& servchart-agent --mark kopia || servchart-agent --mark kopia --failed`.
+Only these fields are sent; the files are never executed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime, timezone
+
+DEFAULT_DIR = "/var/lib/servchart/status"
+NAME_RE = re.compile(r"^[A-Za-z0-9._-]{1,64}$")
+MAX_FILES = 50
+MAX_BYTES = 16 * 1024
+
+
+def status_dir() -> str:
+    """SERVCHART_STATUS_DIR, else the host's /var/lib/servchart/status (through SERVCHART_HOST_ROOT in a container)."""
+    if os.environ.get("SERVCHART_STATUS_DIR"):
+        return os.environ["SERVCHART_STATUS_DIR"]
+    from .system import host_root
+
+    root = host_root()
+    return os.path.join(root, DEFAULT_DIR.lstrip("/")) if root and root != "/" else DEFAULT_DIR
+
+
+def _iso(ts: float) -> str:
+    return datetime.fromtimestamp(ts, timezone.utc).isoformat(timespec="seconds")
+
+
+def read_one(path: str) -> dict | None:
+    name = os.path.basename(path)
+    stem = name[:-5] if name.endswith(".json") else name
+    if not NAME_RE.match(stem):
+        return None
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    entry = {"name": stem, "ok": True, "finished_at": _iso(st.st_mtime), "max_age_hours": None, "message": "", "size_bytes": None}
+    if name.endswith(".json") and st.st_size <= MAX_BYTES:
+        try:
+            with open(path) as fh:
+                doc = json.load(fh)
+        except (OSError, ValueError):
+            doc = None
+        if isinstance(doc, dict):
+            if "ok" in doc:
+                entry["ok"] = bool(doc["ok"])
+            if isinstance(doc.get("finished_at"), str):
+                entry["finished_at"] = doc["finished_at"][:40]
+            if isinstance(doc.get("max_age_hours"), (int, float)) and 0 < doc["max_age_hours"] <= 24 * 366:
+                entry["max_age_hours"] = doc["max_age_hours"]
+            if isinstance(doc.get("message"), str):
+                entry["message"] = doc["message"][:300]
+            if isinstance(doc.get("size_bytes"), int) and doc["size_bytes"] >= 0:
+                entry["size_bytes"] = doc["size_bytes"]
+    return entry
+
+
+def collect() -> list[dict] | None:
+    """None when the status directory doesn't exist (backups not set up for ServChart here)."""
+    d = status_dir()
+    try:
+        names = sorted(os.listdir(d))
+    except OSError:
+        return None
+    out = []
+    for n in names:
+        if n.startswith(".") or n.endswith(".tmp"):
+            continue
+        path = os.path.join(d, n)
+        if os.path.isfile(path):
+            e = read_one(path)
+            if e:
+                out.append(e)
+        if len(out) >= MAX_FILES:
+            break
+    return out
+
+
+def mark(name: str, ok: bool = True, message: str = "", max_age_hours: float | None = None, size_bytes: int | None = None) -> str:
+    """Write <status dir>/<name>.json atomically. Returns the path."""
+    if not NAME_RE.match(name):
+        raise ValueError("Use letters, digits, dot, dash or underscore (max 64) for the backup name.")
+    d = status_dir()
+    os.makedirs(d, exist_ok=True)
+    doc = {"ok": ok, "finished_at": datetime.now(timezone.utc).isoformat(timespec="seconds"), "message": message[:300]}
+    if max_age_hours:
+        doc["max_age_hours"] = max_age_hours
+    if size_bytes is not None:
+        doc["size_bytes"] = size_bytes
+    path = os.path.join(d, f"{name}.json")
+    tmp = path + ".tmp"
+    with open(tmp, "w") as fh:
+        json.dump(doc, fh)
+    os.replace(tmp, path)
+    return path

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/servchart_agent/collect.py

@@ -15,6 +15,7 @@ import re
 from datetime import datetime, timezone
 
 from . import SCHEMA_VERSION, __version__
+from . import backups, stats, storage, system
 from . import connections as conn
 from .docker_api import DockerClient
 
@@ -112,6 +113,26 @@ def parse_depends_on(value: str | None) -> list[str]:
     return services
 
 
+_digests: dict[str, list[str]] = {}  # image id -> RepoDigests
+
+
+def image_digests(client, image_id: str | None) -> list[str]:
+    """Registry digests of an image ("repo@sha256:..."), so the hub can tell if its tag moved."""
+    if not image_id:
+        return []
+    if image_id not in _digests:
+        try:
+            doc = client.get(f"/images/{image_id}/json")
+            _digests[image_id] = [d for d in (doc.get("RepoDigests") or []) if isinstance(d, str)][:10]
+        except Exception:
+            return []
+    return _digests[image_id]
+
+
+def _flag(name: str, default: str = "1") -> bool:
+    return os.environ.get(name, default).lower() in ("1", "true", "yes", "on")
+
+
 def container_record(inspect: dict, hide_paths: bool = False) -> dict:
     """Convert a `docker inspect` document into a sanitized ServChart record.
 
@@ -171,6 +192,13 @@ def collect(client: DockerClient | None = None, hostname: str | None = None) ->
         except Exception:  # container vanished between list and inspect
             continue
     containers = [container_record(i, hide_paths) for i in inspected]
+    for rec, doc in zip(containers, inspected):
+        rec["image_digests"] = image_digests(client, doc.get("Image"))
+    if _flag("SERVCHART_STATS"):
+        by_id = stats.collect(client, [d.get("Id") for d in inspected if (d.get("State") or {}).get("Running")])
+        for rec, doc in zip(containers, inspected):
+            if doc.get("Id") in by_id:
+                rec["stats"] = by_id[doc["Id"]]
     networks = [network_record(n) for n in client.networks()]
 
     host = {
@@ -185,6 +213,8 @@ def collect(client: DockerClient | None = None, hostname: str | None = None) ->
         # on-demand log viewing, opt-in per host (SERVCHART_ALLOW_LOGS=1)
         "logs": "on" if os.environ.get("SERVCHART_ALLOW_LOGS", "0").lower() in ("1", "true", "yes", "on") else "off",
     }
+    if _flag("SERVCHART_HEALTH"):
+        host["health"] = system.health(info.get("DockerRootDir"))
     snapshot = {
         "schema": SCHEMA_VERSION,
         "agent_version": __version__,
@@ -194,6 +224,13 @@ def collect(client: DockerClient | None = None, hostname: str | None = None) ->
         "networks": networks,
     }
 
+    docker_disk = storage.collect(client)
+    if docker_disk is not None:
+        snapshot["storage"] = docker_disk
+    backup_status = backups.collect()
+    if backup_status is not None:
+        snapshot["backups"] = backup_status
+
     # The host's own addresses let the hub resolve other hosts' connections to this one.
     # Readable only when we see the host's /proc (native, or --pid host); else SERVCHART_HOST_IPS.
     subnets = [s for n in networks for s in n.get("subnets") or []]

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/servchart_agent/connections.py

@@ -77,6 +77,11 @@ def is_reportable(ip: str, include_public: bool = False) -> bool:
     return addr.is_private or (addr.version == 4 and addr in CGNAT)
 
 
+# Public addresses the hub asked about (your own public IPs, behind your router): reported even
+# though they're public, so connections through your port forwards can be resolved.
+EXTRA_IPS: set[str] = set()
+
+
 def outbound(rows, exclude_ips=(), include_public: bool = False) -> list[dict]:
     """Aggregate outbound established connections: [{"ip", "port", "count"}].
 
@@ -88,7 +93,7 @@ def outbound(rows, exclude_ips=(), include_public: bool = False) -> list[dict]:
     for _lip, lport, rip, rport, st in rows:
         if st != TCP_ESTABLISHED or lport in listening:
             continue
-        if rip in exclude or not is_reportable(rip, include_public):
+        if rip in exclude or not (is_reportable(rip, include_public) or rip in EXTRA_IPS):
             continue
         counts[(rip, rport)] += 1
     out = [{"ip": ip, "port": port, "count": n} for (ip, port), n in counts.items()]

servchart_agent-0.4.0/servchart_agent/stats.py

@@ -0,0 +1,72 @@
+"""Per-container CPU and memory, from Docker's stats endpoint (read-only, one-shot).
+
+`one-shot=true` answers immediately with a single sample, so CPU use is computed against
+the sample taken at the previous report. Memory excludes the page cache, the way
+`docker stats` shows it.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+_prev: dict[str, tuple[int, int]] = {}  # container id -> (container cpu ns, system cpu ns)
+
+
+def _mem_used(mem: dict) -> int | None:
+    usage = mem.get("usage")
+    if usage is None:
+        return None
+    st = mem.get("stats") or {}
+    cache = st.get("inactive_file", st.get("total_inactive_file", st.get("cache", 0))) or 0
+    return max(0, usage - cache)
+
+
+def _sum(items, key):
+    return sum((i or {}).get(key) or 0 for i in items or [])
+
+
+def parse(cid: str, s: dict, prev: dict | None = None) -> dict:
+    """One container's stats document -> {cpu_pct, mem_used, mem_limit, pids, net_rx, net_tx, ...}."""
+    prev = _prev if prev is None else prev
+    cpu = s.get("cpu_stats") or {}
+    total = (cpu.get("cpu_usage") or {}).get("total_usage")
+    system = cpu.get("system_cpu_usage")
+    cpus = cpu.get("online_cpus") or len((cpu.get("cpu_usage") or {}).get("percpu_usage") or []) or 1
+    cpu_pct = None
+    if total is not None and system is not None:
+        before = prev.get(cid)
+        pre = s.get("precpu_stats") or {}
+        if before is None and pre.get("system_cpu_usage"):  # a streamed sample carries its own baseline
+            before = ((pre.get("cpu_usage") or {}).get("total_usage") or 0, pre["system_cpu_usage"])
+        if before and system > before[1] and total >= before[0]:
+            cpu_pct = round(100.0 * (total - before[0]) / (system - before[1]) * cpus, 1)
+        prev[cid] = (total, system)
+    mem = s.get("memory_stats") or {}
+    limit = mem.get("limit")
+    nets = (s.get("networks") or {}).values()
+    blk = (s.get("blkio_stats") or {}).get("io_service_bytes_recursive") or []
+    return {
+        "cpu_pct": cpu_pct,
+        "mem_used": _mem_used(mem),
+        "mem_limit": limit if limit and limit < 2**60 else None,  # "no limit" is a huge number
+        "pids": (s.get("pids_stats") or {}).get("current"),
+        "net_rx": _sum(nets, "rx_bytes") if nets else None,
+        "net_tx": _sum(nets, "tx_bytes") if nets else None,
+        "blk_read": sum(b.get("value") or 0 for b in blk if (b.get("op") or "").lower() == "read") if blk else None,
+        "blk_write": sum(b.get("value") or 0 for b in blk if (b.get("op") or "").lower() == "write") if blk else None,
+    }
+
+
+def collect(client, running_ids: list[str]) -> dict[str, dict]:
+    """container id -> stats, for running containers. Failures are skipped silently."""
+    out = {}
+    for cid in running_ids:
+        try:
+            doc = client.get(f"/containers/{quote(cid)}/stats?stream=false&one-shot=true")
+        except Exception:
+            continue
+        if isinstance(doc, dict):
+            out[cid] = parse(cid, doc)
+    for gone in set(_prev) - set(running_ids):
+        _prev.pop(gone, None)
+    return out

servchart_agent-0.4.0/servchart_agent/storage.py

@@ -0,0 +1,65 @@
+"""Docker disk usage (images, container layers, volumes, build cache) from `GET /system/df`.
+
+Docker has to measure every volume to answer, which can take a while on big hosts, so the
+result is cached and refreshed every SERVCHART_DF_INTERVAL seconds (default 1 hour;
+0 turns it off).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+MAX_VOLUMES = 500
+_cache: dict = {"at": 0.0, "data": None}
+
+
+def interval() -> int:
+    try:
+        return int(os.environ.get("SERVCHART_DF_INTERVAL", "3600"))
+    except ValueError:
+        return 3600
+
+
+def summarize(df: dict) -> dict:
+    images = df.get("Images") or []
+    containers = df.get("Containers") or []
+    volumes = df.get("Volumes") or []
+    cache = df.get("BuildCache") or []
+    vols = []
+    for v in volumes:
+        usage = v.get("UsageData") or {}
+        size = usage.get("Size")
+        vols.append({"name": v.get("Name"), "size": size if isinstance(size, int) and size >= 0 else None, "refs": usage.get("RefCount")})
+    vols.sort(key=lambda v: -(v["size"] or 0))
+    return {
+        "images_bytes": df.get("LayersSize"),
+        "images_count": len(images),
+        "images_unused": sum(1 for i in images if not i.get("Containers")),
+        "containers_rw_bytes": sum(c.get("SizeRw") or 0 for c in containers),
+        "volumes_bytes": sum(v["size"] or 0 for v in vols),
+        "volumes_count": len(vols),
+        "volumes_unused": sum(1 for v in vols if v["refs"] == 0),
+        "build_cache_bytes": sum(b.get("Size") or 0 for b in cache if not b.get("Shared")),
+        "volumes": vols[:MAX_VOLUMES],
+        "measured_at": int(time.time()),
+    }
+
+
+def collect(client) -> dict | None:
+    every = interval()
+    if every <= 0:
+        return None
+    now = time.time()
+    if now - _cache["at"] >= every:
+        try:
+            slow = client
+            if hasattr(client, "docker_host"):  # measuring volumes can take minutes on big hosts
+                from .docker_api import DockerClient
+
+                slow = DockerClient(client.docker_host, timeout=180)
+            _cache["data"] = summarize(slow.get("/system/df"))
+            _cache["at"] = now
+        except Exception:
+            _cache["at"] = now - every + 300  # retry in 5 minutes
+    return _cache["data"]

servchart_agent-0.4.0/servchart_agent/system.py

@@ -0,0 +1,180 @@
+"""Server health: CPU, memory, load, uptime and disk usage, read from the kernel.
+
+/proc/stat, /proc/meminfo, /proc/loadavg and /proc/uptime describe the whole machine even
+inside a container, so they need nothing special. Disks are different: a container only
+sees its own mounts. The agent reports
+
+  * every real filesystem of the host when it can see the host's root: natively, or in a
+    container with the host's / mounted read-only (`-v /:/host:ro` + SERVCHART_HOST_ROOT=/host);
+  * otherwise just the filesystem holding Docker's data (the agent container's own root
+    lives there), which is usually the one that fills up.
+
+Nothing here reads file contents; only sizes and mount points are reported.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+from .connections import PROC, _in_container
+
+# Filesystems worth reporting; pseudo, overlay and squashfs (snaps) are skipped.
+REAL_FS = {
+    "ext2", "ext3", "ext4", "xfs", "btrfs", "zfs", "f2fs", "jfs", "reiserfs", "vfat", "exfat",
+    "ntfs", "ntfs3", "fuseblk", "nfs", "nfs4", "cifs", "smb3", "ceph", "glusterfs", "fuse.mergerfs",
+    "fuse.sshfs", "apfs", "hfs", "hfsplus",
+}
+SKIP_PREFIXES = ("/proc", "/sys", "/dev", "/run", "/snap", "/var/lib/docker", "/var/lib/containerd", "/var/snap")
+MAX_DISKS = 30
+
+_prev_cpu: tuple[int, int] | None = None  # (busy, total) jiffies from the last report
+
+
+def _read(path: str) -> str | None:
+    try:
+        with open(path) as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
+def cpu_times(text: str | None = None) -> tuple[int, int] | None:
+    """(busy, total) jiffies from the first line of /proc/stat."""
+    text = text if text is not None else _read(f"{PROC}/stat")
+    if not text:
+        return None
+    parts = text.splitlines()[0].split()
+    if parts[0] != "cpu":
+        return None
+    values = [int(v) for v in parts[1:]]
+    idle = values[3] + (values[4] if len(values) > 4 else 0)  # idle + iowait
+    total = sum(values[:8])  # guest time is already counted in user/nice
+    return total - idle, total
+
+
+def cpu_percent() -> float | None:
+    """Average CPU use since the previous report (or over a short sample on the first one)."""
+    global _prev_cpu
+    now = cpu_times()
+    if now is None:
+        return None
+    before = _prev_cpu
+    if before is None:
+        time.sleep(0.5)
+        before, now = now, cpu_times() or now
+    _prev_cpu = now
+    busy, total = now[0] - before[0], now[1] - before[1]
+    return round(100.0 * busy / total, 1) if total > 0 else None
+
+
+def meminfo(text: str | None = None) -> dict:
+    text = text if text is not None else _read(f"{PROC}/meminfo") or ""
+    kb = {}
+    for line in text.splitlines():
+        key, _, rest = line.partition(":")
+        fields = rest.split()
+        if fields and fields[0].isdigit():
+            kb[key] = int(fields[0]) * 1024
+    total = kb.get("MemTotal")
+    available = kb.get("MemAvailable", kb.get("MemFree"))
+    return {
+        "mem_total": total,
+        "mem_available": available,
+        "swap_total": kb.get("SwapTotal"),
+        "swap_free": kb.get("SwapFree"),
+    }
+
+
+def loadavg(text: str | None = None) -> list[float] | None:
+    text = text if text is not None else _read(f"{PROC}/loadavg")
+    try:
+        return [float(v) for v in text.split()[:3]]
+    except (AttributeError, ValueError):
+        return None
+
+
+def uptime(text: str | None = None) -> int | None:
+    text = text if text is not None else _read(f"{PROC}/uptime")
+    try:
+        return int(float(text.split()[0]))
+    except (AttributeError, ValueError, IndexError):
+        return None
+
+
+def host_root() -> str | None:
+    """Where the host's filesystem is visible: "/" natively, SERVCHART_HOST_ROOT in a container."""
+    configured = os.environ.get("SERVCHART_HOST_ROOT")
+    if configured:
+        return configured.rstrip("/") or "/"
+    return None if _in_container() else "/"
+
+
+def parse_mounts(text: str) -> list[tuple[str, str, str]]:
+    """(device, mount point, fs type) of real filesystems, one per device, shortest mount point first."""
+    seen, out = set(), []
+    rows = []
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        device, mount, fstype = parts[0], parts[1].replace("\\040", " "), parts[2]
+        if fstype not in REAL_FS or mount.startswith(SKIP_PREFIXES):
+            continue
+        rows.append((device, mount, fstype))
+    for device, mount, fstype in sorted(rows, key=lambda r: (len(r[1]), r[1])):
+        if device in seen:  # bind mounts of the same filesystem
+            continue
+        seen.add(device)
+        out.append((device, mount, fstype))
+    return out[:MAX_DISKS]
+
+
+def _usage(path: str) -> tuple[int, int] | None:
+    try:
+        st = os.statvfs(path)
+    except OSError:
+        return None
+    total = st.f_blocks * st.f_frsize
+    if total <= 0:
+        return None
+    used = (st.f_blocks - st.f_bfree) * st.f_frsize
+    return total, used
+
+
+def _disk(mount: str, fstype: str, usage: tuple[int, int]) -> dict:
+    total, used = usage
+    # percentage as df shows it: used / (used + available to users)
+    return {"mount": mount, "fs": fstype, "total": total, "used": used, "pct": round(100.0 * used / total, 1)}
+
+
+def disks(docker_root: str | None = None) -> tuple[list[dict], str]:
+    """(disks, source). source is "host" (all real filesystems) or "docker" (Docker's data only)."""
+    root = host_root()
+    if root:
+        text = _read(f"{PROC}/1/mounts") or _read(os.path.join(root, "proc/1/mounts")) or _read("/proc/mounts") or ""
+        out = []
+        for _device, mount, fstype in parse_mounts(text):
+            path = mount if root == "/" else root + mount
+            usage = _usage(path)
+            if usage:
+                out.append(_disk(mount, fstype, usage))
+        if out:
+            return out, "host"
+    # In a container without the host's root: our own "/" sits on Docker's data filesystem.
+    usage = _usage("/")
+    if usage:
+        return [_disk(docker_root or "/var/lib/docker", "docker", usage)], "docker"
+    return [], "none"
+
+
+def health(docker_root: str | None = None) -> dict:
+    disk_list, source = disks(docker_root)
+    return {
+        "cpu_pct": cpu_percent(),
+        "load": loadavg(),
+        "uptime_s": uptime(),
+        **meminfo(),
+        "disks": disk_list,
+        "disk_source": source,
+    }

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/tests/test_collect.py

@@ -2,6 +2,7 @@ import json
 import os
 import sys
 import unittest
+from unittest import mock
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
@@ -98,3 +99,37 @@ class CollectTests(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class StatsClient(FakeClient):
+    def inspect_container(self, cid):
+        doc = json.loads(json.dumps(INSPECT))
+        doc["Image"] = "sha256:" + "b" * 64
+        doc["State"]["Running"] = True
+        return doc
+
+    def get(self, path):
+        if path.startswith("/images/"):
+            return {"RepoDigests": ["vaultwarden/server@sha256:" + "a" * 64]}
+        if "/stats" in path:
+            return {"cpu_stats": {"cpu_usage": {"total_usage": 1}, "system_cpu_usage": 10, "online_cpus": 1},
+                    "memory_stats": {"usage": 2048, "limit": 4096, "stats": {}}}
+        raise RuntimeError(path)
+
+
+class CollectV04Tests(unittest.TestCase):
+    def test_health_stats_and_digests(self):
+        with mock.patch.dict(os.environ, {"SERVCHART_STATUS_DIR": "/nonexistent"}):
+            snap = collect(StatsClient())
+        self.assertIn("mem_total", snap["host"]["health"])
+        self.assertIn(snap["host"]["health"]["disk_source"], ("host", "docker", "none"))
+        c = snap["containers"][0]
+        self.assertEqual(c["image_digests"], ["vaultwarden/server@sha256:" + "a" * 64])
+        self.assertEqual(c["stats"]["mem_used"], 2048)
+        self.assertNotIn("backups", snap)
+
+    def test_health_can_be_turned_off(self):
+        with mock.patch.dict(os.environ, {"SERVCHART_HEALTH": "0", "SERVCHART_STATS": "0"}):
+            snap = collect(StatsClient())
+        self.assertNotIn("health", snap["host"])
+        self.assertNotIn("stats", snap["containers"][0])

{servchart_agent-0.3.1 → servchart_agent-0.4.0}/tests/test_connections.py

@@ -130,3 +130,17 @@ class ObserveTests(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class ExtraIpTests(unittest.TestCase):
+    def test_hub_listed_public_ip_is_reported(self):
+        from servchart_agent import connections as c
+        from servchart_agent.__main__ import apply_hub_hints
+
+        rows = [("10.0.0.5", 50000, "73.173.202.24", 8843, "01"), ("10.0.0.5", 50001, "8.8.8.8", 443, "01")]
+        self.assertEqual(c.outbound(rows), [])
+        apply_hub_hints({"observe_ips": ["73.173.202.24", "not-an-ip"]})
+        try:
+            self.assertEqual(c.outbound(rows), [{"ip": "73.173.202.24", "port": 8843, "count": 1}])
+        finally:
+            apply_hub_hints({"observe_ips": []})

servchart_agent-0.4.0/tests/test_health.py

@@ -0,0 +1,107 @@
+import json
+import os
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from servchart_agent import backups, stats, storage, system  # noqa: E402
+
+MOUNTS = """/dev/sda2 / ext4 rw,relatime 0 0
+proc /proc proc rw 0 0
+overlay /var/lib/docker/overlay2/abc/merged overlay rw 0 0
+/dev/sda1 /boot/efi vfat rw 0 0
+/dev/sda2 /home/user/bind ext4 rw 0 0
+/dev/loop3 /snap/core/1 squashfs ro 0 0
+nas:/export /mnt/my\\040nas nfs4 rw 0 0
+tmpfs /run tmpfs rw 0 0
+"""
+
+
+class SystemTests(unittest.TestCase):
+    def test_cpu_times(self):
+        busy, total = system.cpu_times("cpu  100 0 50 800 50 0 0 0 0 0\ncpu0 1 2 3 4\n")
+        self.assertEqual((busy, total), (150, 1000))
+
+    def test_meminfo_load_uptime(self):
+        m = system.meminfo("MemTotal:  1000 kB\nMemAvailable:  250 kB\nSwapTotal: 0 kB\n")
+        self.assertEqual((m["mem_total"], m["mem_available"]), (1024000, 256000))
+        self.assertEqual(system.loadavg("0.50 1.00 2.00 1/100 42"), [0.5, 1.0, 2.0])
+        self.assertEqual(system.uptime("3600.55 100.0"), 3600)
+
+    def test_parse_mounts_keeps_real_filesystems_once(self):
+        rows = system.parse_mounts(MOUNTS)
+        self.assertEqual([r[1] for r in rows], ["/", "/boot/efi", "/mnt/my nas"])
+
+    def test_docker_fallback_in_container(self):
+        with mock.patch.object(system, "host_root", return_value=None):
+            disks, source = system.disks("/var/lib/docker")
+        self.assertEqual(source, "docker")
+        self.assertEqual(disks[0]["mount"], "/var/lib/docker")
+
+
+class StatsTests(unittest.TestCase):
+    DOC = {
+        "cpu_stats": {"cpu_usage": {"total_usage": 2_000_000}, "system_cpu_usage": 20_000_000, "online_cpus": 4},
+        "precpu_stats": {},
+        "memory_stats": {"usage": 300, "limit": 2**63, "stats": {"inactive_file": 100}},
+        "pids_stats": {"current": 7},
+        "networks": {"eth0": {"rx_bytes": 10, "tx_bytes": 20}},
+    }
+
+    def test_cpu_from_previous_sample_and_memory_without_cache(self):
+        prev = {}
+        first = stats.parse("c1", self.DOC, prev)
+        self.assertIsNone(first["cpu_pct"])  # nothing to compare with yet
+        self.assertEqual(first["mem_used"], 200)
+        self.assertIsNone(first["mem_limit"])  # no limit
+        nxt = json.loads(json.dumps(self.DOC))
+        nxt["cpu_stats"]["cpu_usage"]["total_usage"] = 3_000_000
+        nxt["cpu_stats"]["system_cpu_usage"] = 30_000_000
+        self.assertEqual(stats.parse("c1", nxt, prev)["cpu_pct"], 40.0)  # 1/10 of the machine x 4 cpus
+
+
+class StorageTests(unittest.TestCase):
+    def test_summarize(self):
+        df = {
+            "LayersSize": 5000,
+            "Images": [{"Containers": 1}, {"Containers": 0}],
+            "Containers": [{"SizeRw": 10}, {"SizeRw": None}],
+            "Volumes": [{"Name": "small", "UsageData": {"Size": 1, "RefCount": 1}}, {"Name": "big", "UsageData": {"Size": 900, "RefCount": 0}}],
+            "BuildCache": [{"Size": 7, "Shared": False}],
+        }
+        s = storage.summarize(df)
+        self.assertEqual(s["volumes"][0]["name"], "big")
+        self.assertEqual((s["images_unused"], s["volumes_unused"], s["volumes_bytes"], s["containers_rw_bytes"]), (1, 1, 901, 10))
+
+    def test_disabled(self):
+        with mock.patch.dict(os.environ, {"SERVCHART_DF_INTERVAL": "0"}):
+            self.assertIsNone(storage.collect(object()))
+
+
+class BackupTests(unittest.TestCase):
+    def test_missing_dir_means_not_set_up(self):
+        with mock.patch.dict(os.environ, {"SERVCHART_STATUS_DIR": "/nonexistent/servchart"}):
+            self.assertIsNone(backups.collect())
+
+    def test_mark_and_read(self):
+        with tempfile.TemporaryDirectory() as d, mock.patch.dict(os.environ, {"SERVCHART_STATUS_DIR": d}):
+            backups.mark("kopia", message="1 GB", max_age_hours=26)
+            backups.mark("restic", ok=False, message="repo locked")
+            open(os.path.join(d, "borg-nightly"), "w").close()  # plain file: mtime counts
+            with open(os.path.join(d, "bad name!.json"), "w") as fh:
+                fh.write("{}")
+            got = {b["name"]: b for b in backups.collect()}
+        self.assertEqual(sorted(got), ["borg-nightly", "kopia", "restic"])
+        self.assertTrue(got["kopia"]["ok"])
+        self.assertEqual(got["kopia"]["max_age_hours"], 26)
+        self.assertFalse(got["restic"]["ok"])
+        self.assertTrue(got["borg-nightly"]["ok"])
+        with self.assertRaises(ValueError):
+            backups.mark("../etc/passwd")
+
+
+if __name__ == "__main__":
+    unittest.main()