Monitoring Huey (Python Task Queue) with Vigilmon: Uptime, Heartbeats & Alerts

Huey is a lightweight Python task queue that supports Redis, SQLite, and file-based storage. It's popular for Django and Flask projects that need async task processing without the operational complexity of Celery. But when your Huey worker silently dies — because Redis disconnected, the SQLite file ran out of disk, or the process crashed — periodic tasks stop firing and nobody notices until something breaks visibly. Vigilmon fixes that. This tutorial wires Huey into Vigilmon for uptime monitoring, heartbeat pings, and alert routing in about 20 minutes.

What You'll Build

A health check endpoint that tests the Huey storage backend (Redis or SQLite)
A Vigilmon HTTP monitor pointed at that endpoint
A Vigilmon heartbeat ping sent by each Huey periodic task
Email and Slack webhook alerts

Prerequisites

Python 3.10+
Huey (pip install huey)
Redis 6+ (or SQLite for lightweight setups)
A web framework (Flask or Django) for the health endpoint
A free Vigilmon account

Step 1: Expose a Health Endpoint

Add a /health route to your Flask or Django app that pings the Huey storage backend.

Flask + Redis backend

# health.py
import os
import time
from flask import Flask, jsonify
import redis

app = Flask(__name__)

redis_client = redis.Redis.from_url(os.environ["REDIS_URL"])


@app.get("/health")
def health():
    checks = {}
    status = "ok"

    # Ping Redis
    try:
        redis_client.ping()
        checks["redis"] = "ok"
    except Exception as exc:
        checks["redis"] = f"error: {exc}"
        status = "degraded"

    code = 200 if status == "ok" else 503
    return jsonify({"status": status, "timestamp": time.time(), "checks": checks}), code

Django + SQLite backend

# myapp/views.py
import os
from django.http import JsonResponse
import time


def health(request):
    checks = {}
    status = "ok"

    # Verify SQLite file is accessible
    db_path = os.environ.get("HUEY_SQLITE_PATH", "/var/lib/huey/huey.db")
    try:
        import sqlite3
        conn = sqlite3.connect(db_path, timeout=2)
        conn.execute("SELECT 1")
        conn.close()
        checks["sqlite"] = "ok"
    except Exception as exc:
        checks["sqlite"] = f"error: {exc}"
        status = "degraded"

    code = 200 if status == "ok" else 503
    return JsonResponse(
        {"status": status, "timestamp": time.time(), "checks": checks},
        status=code,
    )

Add a URL route (Django):

# urls.py
from django.urls import path
from myapp.views import health

urlpatterns = [
    path("health", health),
]

Test it locally:

curl -s localhost:8000/health | python -m json.tool
# {
#   "status": "ok",
#   "timestamp": 1751199600.123,
#   "checks": { "redis": "ok" }
# }

Stop Redis and re-run — you'll get 503. Vigilmon treats any non-2xx response as a failure.

Step 2: Create a Vigilmon HTTP Monitor

| Field | Value | |---|---| | URL | https://app.yourdomain.com/health | | Method | GET | | Check interval | 60 seconds | | Expected status | 200 | | Timeout | 10 seconds | | Regions | Select 2–3 for triangulation |

Under Alert Channels, add your email address. You'll add Slack in Step 5.

Click Save — Vigilmon begins polling immediately. Within a minute you'll see the first green tick.

Step 3: Heartbeat Monitoring for Periodic Tasks

Huey supports @huey.periodic_task decorators that fire on a cron-like schedule. An HTTP monitor tells you the backend is reachable, but it doesn't verify that periodic tasks are actually executing. Heartbeat monitoring closes that gap.

Get your Heartbeat URL from Vigilmon (Dashboard → Heartbeat Monitors → New):

https://vigilmon.online/api/heartbeats/YOUR-UUID/ping

Set the period to 1.5× the task's schedule interval — for a task every 5 minutes, use a 7- or 8-minute period.

Wiring the heartbeat into a periodic task

# tasks.py
import os
import logging
import requests
from huey import RedisHuey
from huey.api import crontab

huey = RedisHuey("myapp", url=os.environ["REDIS_URL"])
logger = logging.getLogger(__name__)

VIGILMON_HEARTBEAT_URL = os.environ.get("VIGILMON_HEARTBEAT_URL", "")


def _ping_vigilmon():
    if not VIGILMON_HEARTBEAT_URL:
        return
    try:
        resp = requests.get(VIGILMON_HEARTBEAT_URL, timeout=5)
        logger.info("[heartbeat] pinged, status %d", resp.status_code)
    except Exception as exc:
        logger.warning("[heartbeat] ping failed: %s", exc)


@huey.periodic_task(crontab(minute="*/5"))
def generate_report():
    # --- actual task logic here ---
    _do_report_work()

    # Ping Vigilmon only on successful completion
    _ping_vigilmon()


def _do_report_work():
    pass  # replace with real logic

The key rule: only ping on success. If the task raises an exception, Huey retries it and no ping is sent — Vigilmon detects the silence and alerts you.

Store the heartbeat URL in the environment:

VIGILMON_HEARTBEAT_URL=https://vigilmon.online/api/heartbeats/YOUR-UUID/ping

Run your Huey worker as usual:

huey_consumer tasks.huey --workers 4

Step 4: Monitor Queue Depth (Advanced)

A growing queue depth means your workers can't keep up. For Redis-backed Huey, check the queue length via the Redis connection:

# health.py (add to your existing health check)
try:
    queue_key = "huey.redis.myapp"  # matches your HueyRedis name
    depth = redis_client.llen(queue_key)
    if depth > 500:
        checks["queue_depth"] = f"warning: {depth} pending tasks"
        status = "degraded"
    else:
        checks["queue_depth"] = f"ok ({depth} pending)"
except Exception as exc:
    checks["queue_depth"] = f"unknown: {exc}"

This surfaces backlog pressure in your Vigilmon dashboard.

Step 5: Monitor the Huey Worker Process

For production deployments managed by systemd or supervisor, add a TCP port monitor in Vigilmon if your worker exposes a management port, or use an additional heartbeat sent from the worker's startup probe:

# worker_startup.py — run once when the worker starts
import os
import requests

STARTUP_HEARTBEAT_URL = os.environ.get("VIGILMON_STARTUP_HEARTBEAT_URL", "")
if STARTUP_HEARTBEAT_URL:
    requests.get(STARTUP_HEARTBEAT_URL, timeout=5)

Call this from your worker launch script before handing off to huey_consumer. If the worker crashes and systemd restarts it, the startup ping resets the Vigilmon heartbeat clock.

Step 6: Alert Routing

Email Alerts

Already configured in Step 2. Vigilmon alerts when:

The /health endpoint returns non-2xx (backend unreachable or disk full)
The endpoint times out
The heartbeat window expires (periodic task stopped firing)

Slack Webhook Alerts

Create a Slack incoming webhook (Slack docs)
In Vigilmon → Alert Channels → Add Channel → Webhook
Paste the Slack webhook URL
Assign to your Huey monitors

Alert payload:

{
  "text": "🔴 *app.yourdomain.com/health* is DOWN\nStatus: 503 | Region: us-east-1\nDuration: 6m 30s"
}

Step 7: Test the Full Loop

Simulate Redis failure: stop Redis and curl /health — expect 503.
Verify Vigilmon detects it: within one check interval the dashboard goes red and an alert fires.
Test heartbeat silence: comment out _ping_vigilmon() from your periodic task, let the worker run, and wait for the heartbeat period to expire — you receive an alert.
Recover: restore Redis and uncomment the ping. Vigilmon auto-recovers and sends a "back online" notification.

Production Checklist

[ ] /health checks the Huey storage backend (Redis PING or SQLite query)
[ ] Queue depth check included for backlog visibility
[ ] Heartbeat URL stored in environment variable
[ ] Heartbeat period set to 1.5× the periodic task interval
[ ] Heartbeat ping sent only on successful task completion
[ ] Alert channels tested end-to-end

Wrapping Up

You now have production-grade monitoring for your Huey task queue:

Uptime monitoring that catches backend failures (Redis/SQLite) within 60 seconds
Queue depth visibility to surface worker backlog before tasks time out
Heartbeat monitoring that catches silent periodic-task failures

If you hit issues or have questions, drop a comment below. Happy monitoring!