Feature: extend health endpoint metrics

- add resident memory reporting to /health
- document the health endpoint response schema
- update Kubernetes health example payload
- add pytest coverage for memory response fields - 2026-03-18 23:35:19

Author: mgarcia01752

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

@@ -0,0 +1,70 @@
+# Health
+
+Returns lightweight service health and runtime sizing details for the running
+PyPNM API instance.
+
+**GET** `/health`
+
+## Purpose
+
+Use this endpoint for:
+
+- readiness and liveness checks
+- verifying the running package version
+- checking process uptime
+- checking current resident memory usage
+- monitoring `.data` growth by first-level directory
+
+## Response Example
+
+```json
+{
+  "status": "ok",
+  "service": {
+    "name": "pypnm-docsis",
+    "version": "1.4.3.0"
+  },
+  "uptime": {
+    "starttime": 1773640097,
+    "uptime": 65
+  },
+  "memory": {
+    "rss_bytes": 12582912
+  },
+  "data": {
+    "path": ".data",
+    "size_bytes": 1761579619,
+    "directories": {
+      "json": 1728244816,
+      "xlsx": 0,
+      "pnm": 17349665,
+      "csv": 2819493,
+      "png": 2805111,
+      "db": 3388387,
+      "archive": 6968882,
+      "msg_rsp": 3265
+    }
+  }
+}
+```
+
+## Response Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | string | Top-level health status. Expected value is `ok` when the API is ready. |
+| `service.name` | string | Package/service name loaded from `pyproject.toml`. |
+| `service.version` | string | Running PyPNM version. |
+| `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. |
+| `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`).
+- `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/api/fast-api/pypnm/system/index.md

@@ -2,5 +2,6 @@
 
 |  Reference | Description |
 |------------|-------------|
+| [Health](health.md)                   | Service health, uptime, memory, and `.data` sizing |
 | [Log](download-log.md)                | PyPNM Log         |
 | [WebService](reload-web-service.md)   | PyPNM Web Service |

docs/kubernetes/kind-freelens.md

@@ -45,12 +45,15 @@ Example response:
   "status": "ok",
   "service": {
     "name": "pypnm-docsis",
-    "version": "1.4.2.0"
+    "version": "1.4.3.0"
   },
   "uptime": {
     "starttime": 1773640097,
     "uptime": 1
   },
+  "memory": {
+    "rss_bytes": 12582912
+  },
   "data": {
     "path": ".data",
     "size_bytes": 1761579619,
@@ -68,6 +71,8 @@ Example response:
 }
 ```
 
+`memory.rss_bytes` reports the current resident memory used by the running PyPNM process in bytes.
+
 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.
 
 ## Connect with FreeLens

src/pypnm/api/main.py

@@ -88,10 +88,15 @@ class HealthDataModel(BaseModel):
     directories: dict[str, int] = Field(default_factory=dict, description="Recursive apparent sizes for first-level directories under the data root.")
 
 
+class HealthMemoryModel(BaseModel):
+    rss_bytes: int = Field(..., description="Resident memory usage for the running PyPNM process in bytes.")
+
+
 class HealthResponseModel(BaseModel):
     status: str = Field(..., description="Top-level health status for readiness probes.")
     service: HealthServiceModel = Field(..., description="Service identity and version metadata.")
     uptime: HealthUptimeModel = Field(..., description="Service process start time and uptime.")
+    memory: HealthMemoryModel = Field(..., description="Process memory usage for the running PyPNM service.")
     data: HealthDataModel = Field(..., description="Runtime data directory sizing details.")
 
 
@@ -167,6 +172,26 @@ def _first_level_directory_sizes(folder_path: pathlib.Path) -> dict[str, int]:
     return sizes
 
 
+def _process_rss_bytes() -> int:
+    """Return resident memory for the current process in bytes using Linux procfs."""
+    status_path = pathlib.Path("/proc/self/status")
+    if not status_path.is_file():
+        return 0
+
+    try:
+        for line in status_path.read_text(encoding="utf-8").splitlines():
+            if not line.startswith("VmRSS:"):
+                continue
+            parts = line.split()
+            if len(parts) < 2:
+                return 0
+            return int(parts[1]) * 1024
+    except (OSError, ValueError):
+        return 0
+
+    return 0
+
+
 def _apply_muted_tag_policy(app_instance: FastAPI) -> None:
     _hard_muted_routes.clear()
     muted_tags = read_env_csv_set(ENV_MUTE_TAGS)
@@ -193,6 +218,7 @@ def health() -> 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()),
         data=HealthDataModel(
             path=str(data_root),
             size_bytes=_folder_size_bytes(data_root),

tests/test_api_health.py

@@ -14,6 +14,7 @@ def test_health_includes_uptime(monkeypatch) -> None:
     monkeypatch.setattr(api_main, "API_START_EPOCH", 1_741_709_200)
     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, "_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)
@@ -30,6 +31,9 @@ def test_health_includes_uptime(monkeypatch) -> None:
             "starttime": 1_741_709_200,
             "uptime": 65,
         },
+        "memory": {
+            "rss_bytes": 12_582_912,
+        },
         "data": {
             "path": ".data",
             "size_bytes": 4096,