Server Health Checks

By the end of this lesson you can:

• Read CPU, memory, and disk usage with psutil.
• Check an HTTP endpoint's health and a TCP port's reachability.
• Turn raw metrics into a status (OK / WARN / CRITICAL) via thresholds.
• Produce a structured health report ready to alert on.

"Is the server OK?" breaks into concrete, checkable questions:

Resource   healthy?            check with
CPU        not pegged          psutil.cpu_percent()
memory     room to spare       psutil.virtual_memory()
disk       not nearly full     psutil.disk_usage()
service    HTTP 200            requests.get(/health)
port       accepting conns     socket.connect_ex()

pip install psutil

System metrics with psutil

import psutil

cpu = psutil.cpu_percent(interval=1)        # % over a 1-second sample
print(f"CPU: {cpu}%")

mem = psutil.virtual_memory()
print(f"Memory: {mem.percent}% used ({mem.available // 1_000_000} MB free)")

disk = psutil.disk_usage("/")
print(f"Disk: {disk.percent}% used ({disk.free // 1_000_000_000} GB free)")

print(f"Boot: {psutil.boot_time()}  procs: {len(psutil.pids())}")

• cpu_percent(interval=1) samples for a second — a single instant reading is meaningless.
• virtual_memory() and disk_usage(path) both expose a .percent plus raw bytes.
• Works identically on Windows, macOS, and Linux — no OS-specific commands.

Checking a service endpoint

import requests

def http_ok(url: str, timeout: int = 5) -> tuple[bool, str]:
    try:
        r = requests.get(url, timeout=timeout)
        return r.status_code == 200, f"HTTP {r.status_code}"
    except requests.RequestException as e:
        return False, str(e)

A /health endpoint returning 200 is the classic "is the app alive?" check — far better than just "is the port open," because it proves the app actually responds.

Checking a TCP port

import socket

def port_open(host: str, port: int, timeout: int = 3) -> bool:
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        s.settimeout(timeout)
        return s.connect_ex((host, port)) == 0   # 0 = connected

connect_ex returns 0 if it can open a connection — a lightweight "is something listening on this port?" check (e.g. is the database on 5432 up?).

Classifying against thresholds

def classify(value: float, warn: float, crit: float) -> str:
    if value >= crit:
        return "critical"
    if value >= warn:
        return "warning"
    return "ok"

print(classify(92, warn=80, crit=90))    # critical
print(classify(85, warn=80, crit=90))    # warning
print(classify(40, warn=80, crit=90))    # ok

Two thresholds turn a number into a verdict. Pick them deliberately: WARN = "look into it soon," CRITICAL = "act now." These map straight onto the alert levels from Lesson 34.

Goal: run a suite of checks, classify each, roll up an overall status, and return a structured report — the thing you'd schedule and feed to your alert system.

import psutil, requests, socket, logging
from datetime import datetime

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
log = logging.getLogger("health")

def classify(value, warn, crit):
    return "critical" if value >= crit else "warning" if value >= warn else "ok"

def run_checks() -> dict:
    checks = []

    cpu = psutil.cpu_percent(interval=1)
    checks.append({"name": "cpu", "value": cpu,
                   "status": classify(cpu, 80, 95), "unit": "%"})

    mem = psutil.virtual_memory().percent
    checks.append({"name": "memory", "value": mem,
                   "status": classify(mem, 80, 95), "unit": "%"})

    disk = psutil.disk_usage("/").percent
    checks.append({"name": "disk", "value": disk,
                   "status": classify(disk, 80, 90), "unit": "%"})

    # service check
    try:
        ok = requests.get("http://localhost:8000/health", timeout=5).status_code == 200
    except requests.RequestException:
        ok = False
    checks.append({"name": "web", "value": ok,
                   "status": "ok" if ok else "critical", "unit": ""})

    # roll-up: worst status wins
    order = {"ok": 0, "warning": 1, "critical": 2}
    overall = max((c["status"] for c in checks), key=lambda s: order[s])

    report = {"time": datetime.now().isoformat(),
              "overall": overall, "checks": checks}
    for c in checks:
        log.info("%-7s %s %s  → %s", c["name"], c["value"], c["unit"], c["status"])
    log.info("OVERALL: %s", overall.upper())
    return report

report = run_checks()
# hand off to the alert system (Lesson 34):
# if report["overall"] != "ok":
#     alert(f"Health {report['overall']}: {report['checks']}", report['overall'])

INFO cpu     12.4 %  → ok
INFO memory  47.0 %  → ok
INFO disk    91.0 %  → critical
INFO web     True   → ok
INFO OVERALL: CRITICAL

Read the code

Each check returns the same shape — name, value, status — so they're uniform to log, roll up, and alert on. The overall status is simply the worst of all checks (a single critical makes the box critical). Notice the seam at the bottom: when overall isn't OK, you call the Lesson 34 alert() with the matching level — health checks produce events, the alert system routes them. Schedule this every few minutes (Lesson 35/36) and you have continuous monitoring.

Health monitoring is measure → compare → classify. psutil gives cross-platform CPU (cpu_percent(interval=1)), memory, and disk metrics; requests checks an HTTP /health endpoint and socket.connect_ex checks a port. Turn each number into OK/WARN/CRITICAL with two thresholds, give every check a uniform result shape, and roll up to the worst status. psutil reads the local box; for remote, SSH in (Lesson 41) or hit a health endpoint. The report feeds straight into the alert system (Lesson 34) and runs on a schedule (35/36) — continuous monitoring, assembled from parts you already have.