tutorial

Monitoring Invidious with Vigilmon: Web UI, Stats API, Video Proxy, SSL Certificates & Instance Availability

How to monitor your self-hosted Invidious YouTube frontend with Vigilmon — web availability checks, /api/v1/stats health endpoint, video proxy response monitoring, SSL certificate alerts, and instance availability tracking.

Invidious is the self-hosted YouTube frontend proxy that lets you watch YouTube videos, subscribe to channels, and manage playlists without Google tracking your viewing habits. It intercepts YouTube's APIs, strips out ads and tracking, and delivers clean video streams through your own server. When Invidious goes down, your users either go without video or fall back to tracked YouTube — the exact outcome the self-hosted instance was meant to prevent. Vigilmon monitors Invidious's web interface, health stats API, video proxy response, and SSL certificate so you're notified within 60 seconds of any failure.

What You'll Build

  • An HTTP monitor for Invidious web UI availability
  • A health monitor on the /api/v1/stats endpoint
  • A video proxy response monitor
  • SSL certificate monitoring for your Invidious domain

Prerequisites

  • A running Invidious instance (e.g., https://invidious.example.com)
  • HTTPS configured via reverse proxy (nginx, Caddy, etc.)
  • A free account at vigilmon.online

Step 1: Verify Invidious Web UI Availability

Invidious serves its web interface from the root path. A healthy response confirms the Crystal application is running and the reverse proxy is routing traffic correctly:

curl -I https://invidious.example.com
# Expected: HTTP/2 200

The root path returns the Invidious HTML homepage with a search bar. A 502 Bad Gateway means the Crystal/Kemal server is down or unreachable behind the proxy.

Step 2: Create a Vigilmon HTTP Monitor for Web Availability

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://invidious.example.com.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: Invidious.
  7. Label: Invidious Web UI.
  8. Click Save.

Note on timeout: Invidious makes outbound requests to YouTube's APIs during page load. Cold starts and high-traffic periods can cause 5–10 second response times before a full 15-second timeout is needed.

This monitor catches:

  • Invidious Crystal process crashes or container exits
  • Database (PostgreSQL) connection failures that prevent the application from starting
  • Reverse proxy misconfigurations
  • YouTube API changes that cause Invidious to fail on startup
  • Port conflicts or OOM kills

Step 3: Monitor the /api/v1/stats Health Endpoint

Invidious exposes a public stats endpoint specifically designed for health checking and instance monitoring:

curl https://invidious.example.com/api/v1/stats
# Expected: HTTP 200 with JSON body

A typical healthy response:

{
  "version": "2.20240825.0",
  "software": {
    "name": "invidious",
    "version": "2.20240825.0",
    "branch": "master"
  },
  "openRegistrations": false,
  "usage": {
    "users": {"total": 1, "activeHalfYear": 1, "activeMonth": 1}
  },
  "metadata": {
    "updatedAt": 1719748800,
    "lastChannelRefreshedAt": 1719748750
  }
}

This endpoint is lightweight, doesn't require YouTube API calls, and confirms the Invidious application and database are both responsive.

  1. Add Monitor → HTTP.
  2. URL: https://invidious.example.com/api/v1/stats.
  3. Check interval: 2 minutes.
  4. Expected status: 200.
  5. Keyword: version.
  6. Label: Invidious Stats API.
  7. Click Save.

Why the stats endpoint? Unlike the web UI, /api/v1/stats doesn't require YouTube API calls to return successfully. It only queries the local database. This means it distinguishes between two critical failure modes: (1) the Invidious application is down vs. (2) YouTube is blocking or rate-limiting your instance. If the stats endpoint returns 200 but the web UI monitor fires, YouTube connectivity is the likely culprit.

Step 4: Monitor Video Proxy Response

Invidious proxies video streams through its own server — this is the core feature that keeps your viewing private. The video proxy endpoint serves video content under /videoplayback. You can verify it's responding by checking a known lightweight video URL or using Invidious's own proxy health endpoint:

curl -I "https://invidious.example.com/api/v1/videos/jNQXAC9IVRw"
# Expected: HTTP 200 with JSON video metadata

The video metadata endpoint (/api/v1/videos/:videoId) fetches video information from YouTube without streaming the actual video file — making it safe to use as a regular monitoring check without consuming significant bandwidth.

  1. Add Monitor → HTTP.
  2. URL: https://invidious.example.com/api/v1/videos/jNQXAC9IVRw (the first YouTube video — a reliable, permanent ID).
  3. Check interval: 10 minutes.
  4. Expected status: 200.
  5. Keyword: title.
  6. Label: Invidious Video Proxy.
  7. Click Save.

Video ID note: jNQXAC9IVRw is "Me at the zoo," the first ever YouTube video. It has been available since 2005 and makes a stable monitoring target. If you prefer to avoid external YouTube calls in your monitor, use the stats endpoint from Step 3 as your primary health signal and skip this step.

YouTube rate limiting: If Invidious gets rate-limited by YouTube, this endpoint will fail even when Invidious is running correctly. If this monitor fires but /api/v1/stats stays green, YouTube connectivity or rate limiting is the problem, not your Invidious instance.

Step 5: Monitor SSL Certificates

Invidious is a privacy-focused service — an expired SSL certificate creates a browser security warning that undermines the trust your users place in the instance. Many Invidious users are privacy-conscious and may not report a certificate error; they'll simply stop using the instance.

  1. Add Monitor → SSL Certificate.
  2. Domain: invidious.example.com.
  3. Alert when expiry is within: 30 days.
  4. Alert again: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

Step 6: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Web UI | Non-200 or keyword missing | Check Invidious container; inspect Crystal process logs | | Stats API | Non-200 or keyword missing | Check PostgreSQL connection; restart Invidious if needed | | Video Proxy | Non-200 or keyword missing | Check YouTube connectivity; investigate rate limiting | | SSL Certificate | < 30 days to expiry | Renew certificate; verify ACME auto-renewal |

Alert after: 2 consecutive failures for HTTP monitors. Invidious can have transient failures due to YouTube API changes or rate limiting — two consecutive failures confirm a real issue.

Diagnosing Invidious-Specific Failures

Invidious failures fall into two categories: instance failures (your server is down) and YouTube connectivity failures (your server is up but can't reach YouTube). The monitoring setup in this tutorial helps distinguish between them:

| Monitors firing | Likely cause | |---|---| | Web UI + Stats API + Video Proxy | Invidious process crashed or PostgreSQL is down | | Web UI only | Reverse proxy issue; Crystal process may be healthy | | Video Proxy only, Stats API green | YouTube rate limiting or API change | | SSL monitor only | Certificate renewal failed; check ACME logs | | All monitors simultaneously | DNS misconfiguration or complete server outage |

Common Invidious Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Crystal process crash | Web UI and Stats API monitors fire | | PostgreSQL database down | Stats API and Web UI monitors fire | | YouTube rate limiting instance | Video proxy monitor fires; Stats API stays green | | YouTube API response format change | Web UI returns errors; Stats API may still return 200 | | Container OOM kill | All HTTP monitors fire simultaneously | | SSL certificate expires | SSL monitor alerts at 30 days | | Reverse proxy TLS termination failure | All monitors fire with connection error | | DNS misconfiguration | All monitors fire simultaneously | | Instance running but completely blocked by YouTube | Video proxy fails; stats endpoint stays green |

Your Invidious instance is your users' private window to YouTube. Whether it's a Crystal process crash, a database outage, or YouTube throttling your instance's API access, Vigilmon distinguishes between them — so you know whether to restart your container, check your database, or investigate YouTube connectivity rather than spending time diagnosing the wrong layer.

Start monitoring Invidious in under 5 minutes — register free at vigilmon.online.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles