Lightweight Proxy Health Checks with Python Stdlib
November 16, 2026
Why Lightweight Health Checks Matter
Rotating proxies are only useful if they actually work. A proxy that returns 5xx errors, times out, or leaks the wrong exit IP can break scrapers, cause failed API calls, and waste budget. Heavy monitoring stacks (Prometheus, Grafana, custom agents) add operational overhead and are overkill for many teams. A small, self‑contained health check that runs on the same machines as your scrapers gives you immediate feedback with zero extra infrastructure.
Design Goals
- Zero external dependencies – only Python’s standard library.
- Fast execution – each check should finish in under a second for healthy proxies.
- Clear signals – distinguish between connection failure, high latency, and unexpected exit IP.
- Rotation awareness – detect whether a sticky proxy has kept its IP or a timed proxy has rotated as expected.
- Easy scheduling – run from cron, systemd timers, or a simple loop.
Prerequisites
- Python 3.8 or newer (for
time.perf_counterandhttp.client). - Network access to the proxy gateway and to
https://api.ipify.org. - Proxy credentials: gateway host, HTTP port, username, password. If you are using RoProxy, set the gateway host, port, username, and password as provided.
Building the Checker
1. Proxy Configuration
Store the connection details in constants so the script stays readable.
GATEWAY_HOST = "GATEWAY_HOST"
HTTP_PORT = 8080 # replace with actual port
USERNAME = "USERNAME"
PASSWORD = "PASSWORD"
PROXY_URL = f"http://{USERNAME}:{PASSWORD}@{GATEWAY_HOST}:{HTTP_PORT}"
2. Core Function: test_proxy
The function opens a connection through the proxy, sends a HEAD request to a reliable endpoint, measures round‑trip time, and returns a structured result.
import http.client
import socket
import time
import json
from urllib.parse import urlparse
def test_proxy(proxy_url: str, target_url: str = "https://api.ipify.org?format=json", timeout: float = 5.0) -> dict:
"""Return a dict with keys: ok, latency_ms, exit_ip, error."""
parsed = urlparse(proxy_url)
proxy_host = parsed.hostname
proxy_port = parsed.port or 80
proxy_user = parsed.username
proxy_pass = parsed.password
# Build the CONNECT tunnel for HTTPS target
conn = http.client.HTTPConnection(proxy_host, proxy_port, timeout=timeout)
conn.set_tunnel(target_url.split("://")[1].split("/")[0], headers={
"Proxy-Authorization": "Basic " +
__import__("base64").b64encode(f"{proxy_user}:{proxy_pass}".encode()).decode()
})
start = time.perf_counter()
try:
conn.request("HEAD", target_url)
resp = conn.getresponse()
latency_ms = (time.perf_counter() - start) * 1000
# Read body to get exit IP (ipify returns JSON)
body = resp.read().decode()
data = json.loads(body)
exit_ip = data.get("ip")
ok = 200 <= resp.status < 300
return {"ok": ok, "latency_ms": round(latency_ms, 2), "exit_ip": exit_ip, "error": None}
except (socket.timeout, ConnectionRefusedError, http.client.HTTPException, json.JSONDecodeError) as e:
latency_ms = (time.perf_counter() - start) * 1000
return {"ok": False, "latency_ms": round(latency_ms, 2), "exit_ip": None, "error": str(e)}
finally:
conn.close()
Why HEAD? It avoids downloading a full response body, keeping the check fast while still exercising the TLS handshake and proxy authentication.
3. Measuring Latency
time.perf_counter() provides sub‑millisecond resolution. The returned latency_ms lets you set alerts (e.g., > 800 ms) without needing a separate metrics system.
4. Verifying Exit IP
The script calls https://api.ipify.org?format=json, which returns {"ip": "<exit‑ip>"}. Comparing this value across runs tells you whether the proxy rotated.
5. Handling Rotation Modes
- Sticky proxies keep the same IP until a manual rotate or failure. Expect the same
exit_ipon consecutive checks. - Timed proxies change IP after a configured interval. If you know the interval, you can assert that
exit_ipdiffers after that period.
The checker itself does not enforce rotation logic; it merely reports the observed IP. Your orchestration layer decides when to call the rotation API.
6. Putting It Together: a Runnable Script
#!/usr/bin/env python3
"""Lightweight proxy health check – run once or in a loop."""
import argparse
import sys
import time
from test_proxy import test_proxy # assume the function above lives in test_proxy.py
def main() -> int:
parser = argparse.ArgumentParser(description="Check a rotating proxy")
parser.add_argument("--proxy", default=PROXY_URL, help="Proxy URL with credentials")
parser.add_argument("--interval", type=int, default=0, help="Seconds between checks (0 = single run)")
parser.add_argument("--latency-threshold", type=float, default=800.0, help="Max acceptable latency in ms")
args = parser.parse_args()
last_ip = None
while True:
result = test_proxy(args.proxy)
timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
if result["ok"]:
status = "OK"
if result["latency_ms"] > args.latency_threshold:
status = "HIGH_LATENCY"
ip_msg = f"IP={result['exit_ip']}"
if last_ip and result["exit_ip"] != last_ip:
ip_msg += f" (changed from {last_ip})"
last_ip = result["exit_ip"]
print(f"{timestamp} {status} latency={result['latency_ms']}ms {ip_msg}")
else:
print(f"{timestamp} FAIL error={result['error']}")
if args.interval <= 0:
break
time.sleep(args.interval)
return 0
if __name__ == "__main__":
sys.exit(main())
Save as check_proxy.py and make it executable (chmod +x check_proxy.py). Run a single check:
./check_proxy.py --proxy http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
Or run continuously every 60 seconds:
./check_proxy.py --interval 60 --latency-threshold 800
Running the Check Periodically
- cron:
* * * * * /path/check_proxy.py --proxy $PROXY_URL >> /var/log/proxy_health.log 2>&1(runs every minute). - systemd timer: create a service and timer unit for more control over logging and restart policy.
- Embedded loop: the script’s
--intervalflag is handy for container sidecars.
Choose the method that matches your deployment model. The script writes one line per check, making it trivial to tail, grep, or feed into a log aggregator.
Interpreting Results
| Output | Meaning |
|---|---|
OK latency=120ms IP=203.0.113.45 |
Proxy healthy, low latency, IP as expected. |
HIGH_LATENCY latency=950ms IP=203.0.113.45 |
Proxy works but latency exceeds threshold – consider rotating or switching. |
FAIL error=timed out |
Connection failed – proxy may be down, credentials wrong, or network issue. |
OK latency=130ms IP=198.51.100.12 (changed from 203.0.113.45) |
IP rotated – expected for timed proxies; for sticky proxies this signals an unplanned rotation. |
Set alerts on FAIL and HIGH_LATENCY. Track IP changes to verify that your rotation strategy (manual API call or timed interval) behaves as designed.
Extending the Checker
- Structured logging – output JSON lines for ingestion by Loki, Elasticsearch, or Splunk.
- Alerting – pipe
FAILlines to a webhook (Slack, PagerDuty) with a small wrapper script. - Multiple proxies – iterate over a list of
PROXY_URLs and run checks in parallel withconcurrent.futures.ThreadPoolExecutor. - TLS verification – add
ssl.create_default_context()to enforce certificate validation if your proxy terminates TLS. - Metrics export – push latency and success counters to a Prometheus Pushgateway for dashboarding without a full Prometheus server.
All extensions stay optional; the core script remains a single file with no third‑party packages.
Conclusion
A tiny, standard‑library health check gives you immediate visibility into proxy reliability, latency, and rotation behavior. It runs anywhere Python runs, needs no extra services, and integrates cleanly with existing scheduling tools.