Feature: extend health memory reporting

- add host total free and available memory to /health
- keep process RSS and computed usage percent in the memory block
- update health pytest coverage for the expanded response shape
- update endpoint and Kubernetes docs for the new memory fields - 2026-03-19 02:46:59

Author: mgarcia01752

docs/api/fast-api/pypnm/system/health.md

@@ -29,7 +29,11 @@ Use this endpoint for:
     "uptime": 65
   },
   "memory": {
-    "rss_bytes": 12582912
+    "rss_bytes": 12582912,
+    "total_bytes": 17179869184,
+    "free_bytes": 8216707072,
+    "available_bytes": 10379091968,
+    "usage_percent": 0.07
   },
   "data": {
     "path": ".data",
@@ -58,13 +62,21 @@ Use this endpoint for:
 | `uptime.starttime` | integer | Service start time as Unix epoch seconds. |
 | `uptime.uptime` | integer | Elapsed uptime in whole seconds since `starttime`. |
 | `memory.rss_bytes` | integer | Current resident memory used by the running PyPNM process, in bytes. |
+| `memory.total_bytes` | integer | Total system memory on the current host, in bytes. |
+| `memory.free_bytes` | integer | Free system memory on the current host, in bytes. |
+| `memory.available_bytes` | integer | Available system memory on the current host, in bytes. |
+| `memory.usage_percent` | number | Resident process memory as a percent of total system memory. |
 | `data.path` | string | Runtime data root path. |
 | `data.size_bytes` | integer | Recursive apparent size of the `.data` directory in bytes. |
 | `data.directories` | object | Recursive apparent sizes for each first-level directory under `.data`. |
 
 ## Notes
 
 - `memory.rss_bytes` is based on Linux resident set size (`VmRSS`).
+- `memory.total_bytes` is based on Linux total memory (`MemTotal`).
+- `memory.free_bytes` is based on Linux free memory (`MemFree`).
+- `memory.available_bytes` is based on Linux available memory (`MemAvailable`).
+- `memory.usage_percent` is computed as `rss_bytes / total_bytes * 100`.
 - `data.size_bytes` is logical file size, not filesystem block allocation.
 - `data.directories` helps identify which artifact classes are consuming disk.
 - This endpoint is intended to stay lightweight and local to the running service.

docs/kubernetes/kind-freelens.md

@@ -52,7 +52,11 @@ Example response:
     "uptime": 1
   },
   "memory": {
-    "rss_bytes": 12582912
+    "rss_bytes": 12582912,
+    "total_bytes": 17179869184,
+    "free_bytes": 8216707072,
+    "available_bytes": 10379091968,
+    "usage_percent": 0.07
   },
   "data": {
     "path": ".data",
@@ -72,6 +76,10 @@ Example response:
 ```
 
 `memory.rss_bytes` reports the current resident memory used by the running PyPNM process in bytes.
+`memory.total_bytes` reports host total memory in bytes.
+`memory.free_bytes` reports host free memory in bytes.
+`memory.available_bytes` reports host available memory in bytes.
+`memory.usage_percent` reports resident process memory as a percent of host total memory.
 
 If the returned `service.version` is older than expected, verify the tag used in the deploy command and confirm the namespace matches the running deployment.
 

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "pypnm-docsis"
-version         = "1.5.8.0"
+version         = "1.5.8.1"
 description     = "DOCSIS 3.x/4.0 Proactive Network Maintenance Toolkit"
 readme          = "README.md"
 requires-python = ">=3.10"

src/pypnm/api/main.py

@@ -90,6 +90,10 @@ class HealthDataModel(BaseModel):
 
 class HealthMemoryModel(BaseModel):
     rss_bytes: int = Field(..., description="Resident memory usage for the running PyPNM process in bytes.")
+    total_bytes: int = Field(..., description="Total system memory available on the current host in bytes.")
+    free_bytes: int = Field(..., description="Free system memory on the current host in bytes.")
+    available_bytes: int = Field(..., description="Available system memory on the current host in bytes.")
+    usage_percent: float = Field(..., description="Resident process memory as a percentage of total system memory.")
 
 
 class HealthResponseModel(BaseModel):
@@ -192,6 +196,63 @@ def _process_rss_bytes() -> int:
     return 0
 
 
+def _system_total_memory_bytes() -> int:
+    """Return total system memory in bytes using Linux procfs."""
+    meminfo_path = pathlib.Path("/proc/meminfo")
+    if not meminfo_path.is_file():
+        return 0
+
+    try:
+        for line in meminfo_path.read_text(encoding="utf-8").splitlines():
+            if not line.startswith("MemTotal:"):
+                continue
+            parts = line.split()
+            if len(parts) < 2:
+                return 0
+            return int(parts[1]) * 1024
+    except (OSError, ValueError):
+        return 0
+
+    return 0
+
+
+def _read_meminfo_bytes(field_name: str) -> int:
+    """Return a specific `/proc/meminfo` field in bytes."""
+    meminfo_path = pathlib.Path("/proc/meminfo")
+    if not meminfo_path.is_file():
+        return 0
+
+    try:
+        for line in meminfo_path.read_text(encoding="utf-8").splitlines():
+            if not line.startswith(f"{field_name}:"):
+                continue
+            parts = line.split()
+            if len(parts) < 2:
+                return 0
+            return int(parts[1]) * 1024
+    except (OSError, ValueError):
+        return 0
+
+    return 0
+
+
+def _system_free_memory_bytes() -> int:
+    """Return free system memory in bytes using Linux procfs."""
+    return _read_meminfo_bytes("MemFree")
+
+
+def _system_available_memory_bytes() -> int:
+    """Return available system memory in bytes using Linux procfs."""
+    return _read_meminfo_bytes("MemAvailable")
+
+
+def _process_memory_usage_percent(rss_bytes: int, total_bytes: int) -> float:
+    """Return process RSS as a percentage of total system memory."""
+    if total_bytes <= 0:
+        return 0.0
+    return round((rss_bytes / total_bytes) * 100.0, 2)
+
+
 def _apply_muted_tag_policy(app_instance: FastAPI) -> None:
     _hard_muted_routes.clear()
     muted_tags = read_env_csv_set(ENV_MUTE_TAGS)
@@ -214,11 +275,21 @@ def health() -> HealthResponseModel:
     """Lightweight health endpoint for probes."""
     uptime_seconds = _service_uptime_seconds()
     data_root = _data_root_path()
+    rss_bytes = _process_rss_bytes()
+    total_memory_bytes = _system_total_memory_bytes()
+    free_memory_bytes = _system_free_memory_bytes()
+    available_memory_bytes = _system_available_memory_bytes()
     return HealthResponseModel(
         status="ok",
         service=HealthServiceModel(name=SERVICE_NAME, version=__version__),
         uptime=HealthUptimeModel(starttime=API_START_EPOCH, uptime=uptime_seconds),
-        memory=HealthMemoryModel(rss_bytes=_process_rss_bytes()),
+        memory=HealthMemoryModel(
+            rss_bytes=rss_bytes,
+            total_bytes=total_memory_bytes,
+            free_bytes=free_memory_bytes,
+            available_bytes=available_memory_bytes,
+            usage_percent=_process_memory_usage_percent(rss_bytes, total_memory_bytes),
+        ),
         data=HealthDataModel(
             path=str(data_root),
             size_bytes=_folder_size_bytes(data_root),

src/pypnm/version.py

@@ -6,4 +6,4 @@
 __all__ = ["__version__"]
 
 # MAJOR.MINOR.MAINTENANCE.BUILD
-__version__: str = "1.5.8.0"
+__version__: str = "1.5.8.1"

tests/test_api_health.py

@@ -15,6 +15,9 @@ def test_health_includes_uptime(monkeypatch) -> None:
     monkeypatch.setattr(api_main, "SERVICE_NAME", "pypnm-docsis")
     monkeypatch.setattr(api_main, "_data_root_path", lambda: Path(".data"))
     monkeypatch.setattr(api_main, "_process_rss_bytes", lambda: 12_582_912)
+    monkeypatch.setattr(api_main, "_system_total_memory_bytes", lambda: 17_179_869_184)
+    monkeypatch.setattr(api_main, "_system_free_memory_bytes", lambda: 8_216_707_072)
+    monkeypatch.setattr(api_main, "_system_available_memory_bytes", lambda: 10_379_091_968)
     monkeypatch.setattr(api_main, "_folder_size_bytes", lambda _: 4096)
     monkeypatch.setattr(api_main, "_first_level_directory_sizes", lambda _: {"pnm": 1024, "json": 2048})
     monkeypatch.setattr(api_main, "monotonic", lambda: 165.9)
@@ -33,6 +36,10 @@ def test_health_includes_uptime(monkeypatch) -> None:
         },
         "memory": {
             "rss_bytes": 12_582_912,
+            "total_bytes": 17_179_869_184,
+            "free_bytes": 8_216_707_072,
+            "available_bytes": 10_379_091_968,
+            "usage_percent": 0.07,
         },
         "data": {
             "path": ".data",