Monitoring TubeSync with Vigilmon

TubeSync automatically mirrors YouTube channels and playlists to your local storage, giving you a self-hosted archive that doesn't depend on YouTube staying up or not removing videos. When it's working, new uploads from subscribed channels appear locally within hours. When it's not — because a Celery worker crashed, Redis lost connectivity, or yt-dlp became outdated — channels stop syncing and you don't notice until you look for a video that was never downloaded. Vigilmon monitors every layer of TubeSync so you know the moment your archive stops growing.

What You'll Set Up

• HTTP uptime monitor for the TubeSync Django web interface (port 4848)
• Celery worker health via heartbeat monitoring
• Redis broker connectivity monitoring
• yt-dlp subprocess health
• YouTube API/RSS reachability
• Download job success rate monitoring
• Local storage write health
• Channel sync scheduler heartbeat
• Database connectivity (SQLite or PostgreSQL)
• SSL certificate expiry alerts

Prerequisites

• TubeSync running and accessible (default port 4848)
• A free Vigilmon account

Step 1: Monitor the TubeSync Web Interface

TubeSync's Django web interface runs on port 4848. Add a Vigilmon HTTP monitor:

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

This verifies Django is up and the reverse proxy is routing correctly. If you have HTTP Basic Auth protecting TubeSync, add your credentials under Authentication in the monitor settings.

Step 2: Monitor Celery Worker Health

Celery workers process every download job in TubeSync. If all workers crash — due to OOM kills, unhandled exceptions, or Redis disconnects — the download queue builds up indefinitely but nothing actually downloads. Channels stop syncing and TubeSync gives no visible error in the UI.

Set up a Celery heartbeat check:

#!/bin/bash
# celery-health.sh — verify at least one Celery worker is alive

# Check active workers via celery inspect
WORKERS=$(celery -A tubesync inspect ping --timeout=5 2>/dev/null | grep -c "pong")

if [ "$WORKERS" -gt 0 ]; then
  curl -s https://vigilmon.online/heartbeat/celery-heartbeat-url
else
  echo "No Celery workers responded to ping" >&2
fi

If TubeSync runs in Docker, exec into the container:

#!/bin/bash
# celery-health-docker.sh
WORKERS=$(docker exec tubesync celery -A tubesync inspect ping --timeout=5 2>/dev/null | grep -c "pong")
if [ "$WORKERS" -gt 0 ]; then
  curl -s https://vigilmon.online/heartbeat/celery-heartbeat-url
fi

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set expected interval to 5 minutes.
3. Schedule with cron: */5 * * * * /opt/tubesync/celery-health.sh.

A missed heartbeat means all Celery workers are down and no downloads are processing.

Step 3: Monitor Redis Broker Connectivity

Celery uses Redis as its task queue backend. If Redis is unavailable, Celery workers can't receive tasks and TubeSync queues downloads indefinitely without processing them.

Add a TCP monitor for Redis:

1. Click Add Monitor → TCP Port.
2. Set Hostname to your Redis host (e.g. localhost or your Redis container name).
3. Set Port to 6379.
4. Set Check interval to 1 minute.
5. Click Save.

For a deeper Redis health check, add a script that actually issues a PING command:

#!/bin/bash
# redis-health.sh
RESPONSE=$(redis-cli -h localhost -p 6379 PING 2>/dev/null)
if [ "$RESPONSE" = "PONG" ]; then
  curl -s https://vigilmon.online/heartbeat/redis-heartbeat-url
else
  echo "Redis did not respond to PING" >&2
fi

1. In Vigilmon, create a Cron Heartbeat with a 2 minute expected interval.
2. Schedule: */2 * * * * /opt/tubesync/redis-health.sh.

Redis can be in a state where the TCP port is open but it's blocking commands due to memory pressure or persistence failures — the PING script catches this where a pure TCP check would not.

Step 4: Monitor yt-dlp Health

TubeSync shells out to yt-dlp for all video downloads. yt-dlp breaks compatibility with YouTube regularly — sometimes within days of a YouTube API change — causing download jobs to fail with extraction errors. A stale yt-dlp is the single most common cause of TubeSync download failures.

Create a yt-dlp health check script:

#!/bin/bash
# ytdlp-health.sh

# Confirm yt-dlp is executable
VERSION=$(yt-dlp --version 2>/dev/null)
if [ -z "$VERSION" ]; then
  echo "yt-dlp not found" >&2
  exit 1
fi

# Test extraction on a known-good short video (no download, just metadata)
yt-dlp --simulate --no-warnings \
  'https://www.youtube.com/watch?v=dQw4w9WgXcQ' >/dev/null 2>&1

if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/ytdlp-heartbeat-url
else
  echo "yt-dlp extraction failed — yt-dlp may be outdated" >&2
fi

1. In Vigilmon, create a Cron Heartbeat with a 30 minute expected interval.
2. Schedule: */30 * * * * /opt/tubesync/ytdlp-health.sh.

Also configure an auto-updater to keep yt-dlp current:

# Update yt-dlp daily at 2 AM
0 2 * * * pip install --upgrade yt-dlp >> /var/log/ytdlp-update.log 2>&1

Step 5: Monitor YouTube Reachability

TubeSync queries YouTube's public RSS feeds and API to discover new videos on subscribed channels. If your server has outbound connectivity issues or YouTube temporarily blocks your IP, channel syncs fail to find new content.

Add HTTP monitors for YouTube's endpoints:

1. Click Add Monitor → HTTP / HTTPS.
2. Set URL to https://www.youtube.com/feeds/videos.xml?channel_id=UCxxxxxx (replace with a real channel ID from your subscriptions).
3. Set Expected HTTP status to 200.
4. Set Check interval to 5 minutes.

Also add a general YouTube connectivity check:

1. Add another monitor for https://www.youtube.com.
2. Set Expected HTTP status to 200.
3. Set Check interval to 5 minutes.

If these monitors alert while Cobalt or other YouTube tools work fine, check whether TubeSync's server IP is being rate-limited or geo-blocked by YouTube.

Step 6: Monitor Download Job Success Rate

TubeSync processes downloads as Celery tasks. A high failure rate — even if workers are running — indicates yt-dlp errors, storage issues, or content that YouTube is restricting. Monitor this by querying TubeSync's task failure count:

#!/bin/bash
# download-success-rate.sh
# Query TubeSync's admin or database for recent task failures

# Check Celery Flower (if deployed) for failed task count
FAILED=$(curl -sf http://localhost:5555/api/tasks?state=FAILURE&limit=100 | jq '.tasks | length' 2>/dev/null)

# Alert if more than 10% of recent tasks are failing
# For a simpler check, just ping if failure count is low
if [ "${FAILED:-0}" -lt 5 ]; then
  curl -s https://vigilmon.online/heartbeat/download-rate-heartbeat-url
else
  echo "High download failure rate: $FAILED failures in recent tasks" >&2
fi

1. In Vigilmon, create a Cron Heartbeat with a 15 minute expected interval.
2. Schedule: */15 * * * * /opt/tubesync/download-success-rate.sh.

If you deploy Celery Flower (the Celery monitoring UI), you can also add a Vigilmon HTTP monitor for the Flower dashboard itself to confirm the monitoring layer is running.

Step 7: Monitor Local Storage Write Health

TubeSync writes downloaded videos, thumbnails, and metadata to a configured local directory. If the disk fills up, the mount drops, or permissions change, downloads fail at the final write step — after yt-dlp has already processed the entire video.

Add a write-health heartbeat:

#!/bin/bash
# storage-health.sh
MEDIA_DIR="/path/to/tubesync/downloads"
TEST_FILE="$MEDIA_DIR/.vigilmon_write_test"

# Check free space (alert if less than 5 GB free)
FREE_BYTES=$(df -B1 "$MEDIA_DIR" | awk 'NR==2 {print $4}')
MIN_BYTES=$((5 * 1024 * 1024 * 1024))

if [ "$FREE_BYTES" -lt "$MIN_BYTES" ]; then
  echo "Low disk space: $FREE_BYTES bytes free on $MEDIA_DIR" >&2
  exit 1
fi

# Check write permissions
if touch "$TEST_FILE" 2>/dev/null && rm "$TEST_FILE" 2>/dev/null; then
  curl -s https://vigilmon.online/heartbeat/storage-heartbeat-url
else
  echo "Cannot write to $MEDIA_DIR" >&2
fi

1. In Vigilmon, create a Cron Heartbeat with a 5 minute expected interval.
2. Schedule: */5 * * * * /opt/tubesync/storage-health.sh.

The 5 GB threshold catches disk-full conditions before TubeSync starts failing downloads. Adjust the threshold to match your disk capacity.

Step 8: Monitor the Channel Sync Scheduler

TubeSync periodically checks subscribed channels for new content. If the scheduler stops firing — due to a Django process crash or APScheduler failure — subscriptions go stale and new videos are never discovered even though Celery workers are ready.

Add a sync scheduler heartbeat. You can hook into TubeSync's sync task using a Django management command wrapper:

#!/bin/bash
# sync-health.sh — verify sync tasks are running on schedule

# Check when the last sync task ran via TubeSync's database
LAST_SYNC=$(sqlite3 /path/to/tubesync/db.sqlite3 \
  "SELECT MAX(last_checked) FROM sync_sources WHERE last_checked IS NOT NULL;" 2>/dev/null)

# Convert to epoch and check if it was within the last 2 hours
LAST_EPOCH=$(date -d "$LAST_SYNC" +%s 2>/dev/null)
NOW_EPOCH=$(date +%s)
AGE=$((NOW_EPOCH - LAST_EPOCH))

if [ "$AGE" -lt 7200 ]; then
  curl -s https://vigilmon.online/heartbeat/scheduler-heartbeat-url
else
  echo "Last channel sync was $AGE seconds ago — scheduler may have stalled" >&2
fi

1. In Vigilmon, create a Cron Heartbeat with a 2 hour expected interval.
2. Schedule: 0 * * * * /opt/tubesync/sync-health.sh.

Adjust the SQL table and column names to match your TubeSync version's schema.

Step 9: Monitor Database Connectivity

TubeSync supports both SQLite (default) and PostgreSQL for storing channel subscriptions, video metadata, and download state. If the database becomes inaccessible, TubeSync can't record download progress or find new videos to sync.

For SQLite:

#!/bin/bash
# sqlite-health.sh
DB_PATH="/path/to/tubesync/db.sqlite3"
RESULT=$(sqlite3 "$DB_PATH" "SELECT 1;" 2>/dev/null)
if [ "$RESULT" = "1" ]; then
  curl -s https://vigilmon.online/heartbeat/db-heartbeat-url
fi

For PostgreSQL:

1. Add a TCP Port monitor pointing to your PostgreSQL host on port 5432.
2. Also add a query heartbeat script similar to the one in the storage section above.

Schedule the database health script every 2 minutes.

Step 10: SSL Certificate Expiry Alerts

Add SSL monitoring to the TubeSync web interface monitor:

1. Open the TubeSync HTTP monitor from Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Step 11: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and configure Slack, email, or webhook.
2. Set Consecutive failures before alert to 2 on the Django web UI monitor.
3. Set Consecutive failures to 1 on all heartbeat monitors — a missed heartbeat from Celery, Redis, or yt-dlp is always meaningful.
4. For YouTube reachability monitors, set Consecutive failures to 3 — brief transient failures are common.
5. Use Maintenance windows when upgrading TubeSync to suppress alerts during planned downtime.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://tubesync.yourdomain.com | Django crash, proxy failure | | Celery workers | Heartbeat every 5 min | Worker crash, queue frozen | | Redis TCP | Port 6379 | Redis process down | | Redis PING | Heartbeat every 2 min | Redis unresponsive to commands | | yt-dlp | Heartbeat every 30 min | Outdated yt-dlp, subprocess crash | | YouTube RSS | Channel RSS feed URL | Server IP blocked, outbound failure | | Download success rate | Heartbeat every 15 min | High failure rate, yt-dlp errors | | Local storage | Heartbeat every 5 min | Disk full, read-only filesystem | | Channel sync scheduler | Heartbeat every 2 hours | Scheduler stall, no new syncs | | Database (SQLite/PostgreSQL) | Heartbeat every 2 min | DB unavailable or corrupted | | SSL certificate | TubeSync domain | Let's Encrypt renewal failure |

TubeSync gives you a YouTube-independent archive of the content you care about — Vigilmon makes sure the archiving never quietly stops. With Celery worker heartbeats, yt-dlp health checks, and storage monitors in place, you'll know about sync failures before you discover a gap in your archive.