Back to all posts
Lightweight Proxy Health Checks with Python Stdlib

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_counter and http.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_ip on consecutive checks.
  • Timed proxies change IP after a configured interval. If you know the interval, you can assert that exit_ip differs 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 --interval flag 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 FAIL lines to a webhook (Slack, PagerDuty) with a small wrapper script.
  • Multiple proxies – iterate over a list of PROXY_URLs and run checks in parallel with concurrent.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.