Monitoring Piped with Vigilmon

Piped gives you and your users a privacy-respecting YouTube experience without Google tracking — video streaming, subscriptions, SponsorBlock, and search, all proxied through your own server. But Piped's multi-service architecture (Java/Spring Boot API backend, Vue.js frontend, and several proxy layers) means a single failed component can break everything from search to video playback. Vigilmon monitors every layer so you know the moment something goes wrong.

What You'll Set Up

• API backend availability monitor (port 8080)
• Frontend web server monitor (port 3000)
• YouTube data proxy endpoint check
• Video streaming proxy health monitor
• Search functionality endpoint monitor
• Subscription feed refresh heartbeat
• SponsorBlock integration health check
• Database connectivity monitor

Prerequisites

• Piped deployed with the standard API + frontend + proxy setup
• A free Vigilmon account

Step 1: Monitor the API Backend

The Piped API backend (Spring Boot, port 8080) is the core of the deployment — it fetches YouTube data, handles user accounts, and serves playlist/subscription data to the frontend.

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

The /healthcheck endpoint returns a simple JSON object when the Spring Boot application is healthy. A 503 or connection refused means the JVM process crashed or is restarting.

Step 2: Monitor the Frontend Web Server

The Vue.js frontend is served by a static web server (typically nginx, port 3000). Add a dedicated monitor for it separate from the API:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://piped.yourdomain.com (or http://your-server:3000).
3. Set Check interval to 1 minute.
4. Set Expected HTTP status to 200.
5. Click Save.

The frontend failing independently (e.g. an nginx crash or a bad container restart) will show a broken page to users while the API continues running — this monitor catches that split failure.

Step 3: Monitor the YouTube Data Proxy Endpoint

Piped proxies YouTube API responses through its backend to strip tracking parameters. Test a real proxy request to confirm the YouTube data pipeline is working end-to-end:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://piped-api.yourdomain.com/trending?region=US.
3. Set Expected HTTP status to 200.
4. Set Check interval to 5 minutes.
5. Click Save.

A 502 or empty response here means Piped cannot reach YouTube's data API — this can happen if your server's outbound IP is rate-limited or blocked by YouTube, or if a dependency update broke the extraction logic.

Step 4: Monitor the Video Streaming Proxy

Piped proxies video streams through a companion service (piped-proxy, written in Rust) that rewrites streaming URLs to avoid sending the client's IP to Google. This proxy is completely separate from the API backend.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://piped-proxy.yourdomain.com/ (your configured proxy domain).
3. Set Expected HTTP status to 200 or 403 (the proxy root may return 403 to direct requests but should not return 502 or 503).
4. Set Check interval to 2 minutes.
5. Click Save.

If the proxy returns 502 consistently, video playback will fail for all users even though the frontend and API appear healthy.

Step 5: Monitor Search Functionality

Search is the most frequently used Piped feature. Monitor the search endpoint directly to confirm the YouTube data extraction is working for search queries:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://piped-api.yourdomain.com/search?q=test&filter=all.
3. Set Expected HTTP status to 200.
4. Set Check interval to 5 minutes.
5. Click Save.

YouTube regularly changes its internal response format, which can break Piped's extraction library (NewPipe Extractor). A failed search endpoint is often the first symptom of an extractor compatibility issue after a YouTube update.

Step 6: Heartbeat for Subscription Feed Refresh

Piped refreshes subscription feeds for registered users on a background schedule. This job has no HTTP endpoint — use a cron heartbeat to confirm it is running:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 60 minutes (or your configured refresh interval).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. In your Piped deployment, add the ping to the subscription refresh job. If you're running Piped via Docker Compose, add a health-check wrapper script:

#!/bin/bash
# Run by cron or a scheduler alongside Piped's internal feed refresh
# Check that the feed endpoint returns data for a known channel
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
  "https://piped-api.yourdomain.com/feed/unauthenticated?channels=UCVHFbw7woebKtfnjKzmvRng")

if [ "$RESPONSE" = "200" ]; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi

If the feed refresh job silently stops running, users will see stale subscription feeds with no error message.

Step 7: Monitor SponsorBlock Integration

Piped integrates with the SponsorBlock API to automatically skip sponsored segments in videos. If the SponsorBlock API is unreachable from your server, this feature silently degrades. Monitor your server's ability to reach the SponsorBlock API:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://sponsor.ajay.app/api/status (or your configured SponsorBlock API endpoint).
3. Set Expected HTTP status to 200.
4. Set Check interval to 10 minutes.
5. Click Save.

This is an outbound connectivity check — a failure here means either the SponsorBlock API is down or your server's outbound traffic is blocked.

Step 8: Monitor Database Connectivity

Piped stores user accounts, subscriptions, playlists, and watch history in PostgreSQL. A database failure locks out all registered users.

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

Pair this with an HTTP monitor on the user login endpoint to catch application-level database errors:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://piped-api.yourdomain.com/user/feed.
3. Set Expected HTTP status to 401 (unauthenticated requests should get 401, not 500).
4. Set Check interval to 2 minutes.
5. Click Save.

A 500 response on this endpoint is a reliable indicator of database connectivity failure.

Step 9: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the trending and search monitors — YouTube occasionally rate-limits requests briefly, which can cause single-probe misses.
3. Set Consecutive failures before alert to 1 on the API backend and video proxy monitors — these should be highly available at all times.

Summary

| Monitor | Target | What It Catches | |---|---|---| | API backend | /healthcheck | Spring Boot crash, JVM OOM | | Frontend | https://piped.yourdomain.com | nginx crash, container down | | YouTube data proxy | /trending?region=US | Extractor broken, IP blocked | | Video streaming proxy | Proxy domain root | piped-proxy crash | | Search | /search?q=test | NewPipe Extractor incompatibility | | Feed refresh | Cron heartbeat | Stale subscription feeds | | SponsorBlock | External API status | Outbound connectivity issue | | Database | Port 5432 TCP | User data unavailable |

Piped gives your users YouTube without the surveillance — but the privacy guarantee only holds if the proxy stack is running. With Vigilmon watching each service independently, you catch the difference between "the frontend is down" and "YouTube changed their API again" before your users notice.