Monitoring Tube Archivist with Vigilmon

Tube Archivist (Python/Django, port 8000) lets you download, organize, and stream YouTube content from your own server. What makes it powerful also makes it fragile: downloads run as Celery background tasks, search runs through Elasticsearch, job queuing goes through Redis, and video processing requires ffmpeg. Any one of those layers can fail silently while the Django web UI continues to look healthy. Vigilmon gives you eyes on every layer so you know the moment your archive stops growing.

What You'll Set Up

• Web server availability monitor (port 8000)
• Background video download task heartbeat
• Elasticsearch search backend connectivity check
• Redis message broker health monitor
• ffmpeg transcoding pipeline heartbeat
• Thumbnail generation service heartbeat
• YouTube API integration health check
• Database connectivity monitor
• Scheduled auto-download job heartbeat

Prerequisites

• Tube Archivist running via Docker Compose (standard deployment)
• A free Vigilmon account

Step 1: Monitor Web Server Availability

The Tube Archivist Django web application is the primary interface for browsing and searching your archive. Start with an HTTP availability check:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://tube-archivist.yourdomain.com (or http://your-server:8000).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Tube Archivist exposes a /health endpoint in recent versions — use it if available for a richer check:

1. URL: https://tube-archivist.yourdomain.com/health.
2. Set Expected HTTP status to 200.

The health endpoint confirms the Django process is running and connected to its dependencies.

Step 2: Heartbeat for Background Video Download Tasks

Video downloads are the most critical Tube Archivist function — and they run entirely in Celery worker processes that have no web-facing status. A Celery worker crash stops all downloads silently: the queue fills up but nothing moves.

Use Vigilmon's cron heartbeat to confirm downloads are completing:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 30 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Add a health check to your Celery worker container. In your docker-compose.yml, add a periodic ping to a small wrapper script:

#!/bin/bash
# celery_health_check.sh — run every 30 minutes via cron in the archivist container
# Inspect active Celery workers
ACTIVE=$(celery -A home.tasks inspect active 2>/dev/null | grep -c "worker@")

if [ "$ACTIVE" -gt 0 ]; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi

# docker-compose.yml — add to the archivist service
healthcheck:
  test: ["CMD", "/bin/bash", "/app/celery_health_check.sh"]
  interval: 30m
  timeout: 10s
  retries: 2

If no workers are active, the ping stops and Vigilmon alerts you after 30 minutes.

Step 3: Monitor Elasticsearch Search Backend

Tube Archivist indexes all video metadata in Elasticsearch. Without Elasticsearch, search returns no results and the channel/playlist views break. Monitor the Elasticsearch health endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:9200/_cluster/health (Elasticsearch in Docker typically binds to localhost — use your container network IP or expose the port).
3. Set Expected HTTP status to 200.
4. Set Check interval to 2 minutes.
5. Click Save.

The /_cluster/health endpoint returns a JSON object with a status field (green, yellow, or red). A red status means the cluster is unhealthy and search will fail.

For a more targeted check, use Vigilmon's keyword match feature:

1. Enable Check response body.
2. Set Must contain to "status":"green" or "status":"yellow" (yellow is acceptable for a single-node deployment).
3. Alert if neither matches — this catches a red cluster status without requiring custom scripting.

Step 4: Monitor Redis Message Broker

Tube Archivist uses Redis as the Celery message broker. If Redis goes down, new download tasks cannot be queued and the existing task queue is lost. Monitor the Redis port:

1. Click Add Monitor → TCP Port.
2. Host: your-server, Port: 6379.
3. Set Check interval to 1 minute.
4. Click Save.

A TCP connection failure to Redis port 6379 is unambiguous — add this monitor and set it to alert immediately (Consecutive failures before alert: 1).

Step 5: Heartbeat for the ffmpeg Transcoding Pipeline

Tube Archivist uses ffmpeg to convert downloaded videos to a standardised format for playback. If ffmpeg crashes or is missing from the container, newly downloaded videos will be saved but unplayable.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 60 minutes.
3. Copy the heartbeat URL.
4. Add a transcoding test to your monitoring scripts:

#!/bin/bash
# test_ffmpeg.sh — confirm ffmpeg is installed and functional
ffmpeg -version > /dev/null 2>&1

if [ $? -eq 0 ]; then
  # Also confirm a short probe completes on a known-good file
  ffprobe -v error -show_entries format=duration \
    -of default=noprint_wrappers=1:nokey=1 \
    /app/media/test_probe.mp4 > /dev/null 2>&1
  
  if [ $? -eq 0 ]; then
    curl -s https://vigilmon.online/heartbeat/abc123
  fi
fi

Step 6: Heartbeat for the Thumbnail Generation Service

Tube Archivist generates thumbnail images for videos and channels and stores them in the media directory. Thumbnail generation failures produce broken images in the UI without raising any application error.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 60 minutes.
3. Copy the heartbeat URL.
4. Add a thumbnail availability check:

#!/bin/bash
# test_thumbnails.sh
# Check that recent thumbnails exist and are non-zero size
RECENT_THUMB=$(find /app/media/cache -name "*.jpg" -newer /tmp/last_thumb_check 2>/dev/null | head -1)

if [ -n "$RECENT_THUMB" ] && [ -s "$RECENT_THUMB" ]; then
  touch /tmp/last_thumb_check
  curl -s https://vigilmon.online/heartbeat/abc123
fi

Run this script every hour via cron in the Tube Archivist container.

Step 7: Monitor YouTube API Integration Health

Tube Archivist fetches video metadata, channel information, and download URLs from YouTube. A YouTube API rate limit or response format change will silently stop metadata collection while the downloader continues trying.

Monitor the metadata fetch path by checking the Tube Archivist API:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://tube-archivist.yourdomain.com/api/video/?limit=1 (requires auth header in production, but you can use a read-only API key).
3. Set Expected HTTP status to 200.
4. Set Check interval to 10 minutes.
5. Click Save.

For authenticated monitoring, use Vigilmon's Custom headers feature:

1. Enable Add custom headers.
2. Add header: Authorization: Token YOUR_TUBE_ARCHIVIST_API_TOKEN.

This confirms the API is responding and the database backend is reachable.

Step 8: Monitor Database Connectivity

Tube Archivist stores user settings, task state, and metadata in a PostgreSQL database. A database failure causes login errors and prevents the admin interface from functioning.

1. Click Add Monitor → TCP Port.
2. Host: your-db-server (or localhost if collocated), Port: 5432.
3. Set Check interval to 1 minute.
4. Click Save.

Step 9: Heartbeat for the Scheduled Auto-Download Job

Tube Archivist can be configured to automatically check for and download new videos from subscribed channels on a schedule. This scheduler runs as a Celery beat task — if Celery beat crashes, no new automatic downloads will occur.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your auto-download schedule (e.g. 360 minutes for a 6-hour check).
3. Copy the heartbeat URL.
4. Instrument the auto-download task to ping Vigilmon on completion:

# In your Tube Archivist task file (or a custom task wrapper)
from celery import shared_task
import requests

@shared_task
def auto_download_with_heartbeat():
    # Run the standard auto-download task
    from home.tasks import download_pending
    download_pending()
    
    # Ping Vigilmon on success
    try:
        requests.get('https://vigilmon.online/heartbeat/abc123', timeout=5)
    except Exception:
        pass  # Don't fail the task if the ping fails

Step 10: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 1 on Redis and Elasticsearch monitors — these are hard dependencies.
3. Set Consecutive failures before alert to 2 on the web server monitor — Django restarts can cause brief 502s.
4. Route download-related heartbeat alerts to a low-urgency channel (these are background jobs, not user-facing) and web/search alerts to a high-urgency channel.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web server | Port 8000 HTTP /health | Django crash, container down | | Download tasks | Cron heartbeat (30 min) | Celery worker crash, no downloads | | Elasticsearch | Port 9200 /_cluster/health | Search broken, index unavailable | | Redis | Port 6379 TCP | Task queue unavailable | | ffmpeg pipeline | Cron heartbeat (60 min) | Videos downloaded but unplayable | | Thumbnail service | Cron heartbeat (60 min) | Broken images in UI | | YouTube API | /api/video/?limit=1 | Metadata fetch failures | | Database | Port 5432 TCP | User data and settings unavailable | | Auto-download scheduler | Cron heartbeat (6h) | New videos silently not downloading |

Tube Archivist is an excellent way to build a permanent, searchable archive of YouTube content you care about — but the background pipeline that keeps it growing is invisible by default. With Vigilmon watching every component from Elasticsearch to the Celery workers, you know the moment your archive stops growing instead of discovering it weeks later.