tutorial

Monitoring Threadfin with Vigilmon

Threadfin proxies M3U playlists and XMLTV EPG data for Plex DVR, Emby, and Jellyfin — but upstream fetch failures and tuner relay issues surface as client errors. Here's how to monitor Threadfin's web UI, EPG refresh service, and stream relay health with Vigilmon.

Threadfin is a self-hosted M3U proxy written in Go that sits between your IPTV provider and media server — acting as a virtual HDHomeRun tuner for Plex DVR, Emby, and Jellyfin. Running on port 34400, it fetches upstream M3U playlists, refreshes XMLTV EPG data, and relays live streams to client devices. When the upstream provider has an outage, or Threadfin's own refresh scheduler stalls, recordings fail silently. Vigilmon gives you proactive monitoring for every layer of that proxy chain so you catch failures before your DVR misses a recording.

What You'll Set Up

  • Web UI availability monitor (port 34400)
  • Upstream M3U playlist fetch health check
  • XMLTV EPG refresh service probe
  • Tuner stream relay health check
  • Channel filter processing verification
  • Client device connectivity monitoring

Prerequisites

  • Threadfin running and accessible on port 34400
  • At least one M3U playlist and XMLTV source configured
  • A free Vigilmon account

Step 1: Monitor the Threadfin Web UI

The Threadfin web interface runs on port 34400 and confirms the Go service is alive:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Threadfin URL: http://YOUR_SERVER_IP:34400/web/.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

If Threadfin is behind a reverse proxy, monitor the proxied URL. A 200 from the web UI path confirms the Go HTTP server is up and the internal router is responding.

Step 2: Monitor the M3U Playlist Output

Threadfin serves a merged, filtered M3U playlist that your media server pulls to populate its channel list. This endpoint reflects both Threadfin's internal state and the last successful upstream fetch:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the m3u URL: http://YOUR_SERVER_IP:34400/m3u/threadfin.m3u.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter #EXTM3U to validate the output is a real playlist.
  5. Set Check interval to 5 minutes.
  6. Click Save.

An empty or error response here means Threadfin has either lost contact with the upstream provider or its internal channel database is inconsistent. Cross-reference with Threadfin's logs:

docker logs threadfin --tail 50
# Look for: "Could not load M3U file" or "Error updating playlist"

Step 3: Monitor the XMLTV EPG Output

Threadfin fetches XMLTV guide data from upstream sources and serves a merged EPG to your media server. Without valid guide data, recordings use empty metadata and scheduled recordings may fail to match:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the XMLTV URL: http://YOUR_SERVER_IP:34400/xmltv/threadfin.xml.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter <tv to confirm a valid XMLTV document.
  5. Set Check interval to 15 minutes.
  6. Click Save.

Threadfin refreshes EPG data on a configurable schedule (default: every 24 hours). The monitor validates the endpoint is serving the cached EPG; a failure indicates the EPG cache is corrupt or the last refresh wrote an invalid file.

Step 4: Monitor Tuner Stream Relay Health

Threadfin relays live streams by forwarding requests to your IPTV provider's stream URLs. You can probe an always-available channel to verify the relay is functioning:

  1. Identify the URL format Threadfin uses for stream relay — check your media server's tuner settings or the Threadfin log for a line like Starting stream for channel.
  2. Click Add Monitor → HTTP / HTTPS.
  3. Enter a stream relay URL for a test channel: http://YOUR_SERVER_IP:34400/stream/YOUR_CHANNEL_ID.
  4. Set Expected HTTP status to 200.
  5. Set Timeout to 15 seconds — stream startup may take a few seconds.
  6. Set Check interval to 5 minutes.
  7. Click Save.

Tip: Choose a news or weather channel that streams 24/7 to avoid false alerts from content that goes offline at night.

A timeout or 5xx response means Threadfin cannot reach the upstream stream URL. This could indicate a provider outage, an expired credential in your M3U URL, or a network routing issue between your server and the provider.

Step 5: Verify the HDHomeRun Device Discovery Endpoint

Plex, Emby, and Jellyfin discover Threadfin as a virtual HDHomeRun tuner via a device discovery endpoint. If this endpoint fails, your media server loses the tuner and can't start recordings:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: http://YOUR_SERVER_IP:34400/device.xml.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter <DeviceType> to confirm a valid HDHomeRun device description is returned.
  5. Set Check interval to 2 minutes.
  6. Click Save.

Also add a monitor for the lineup endpoint that Plex queries to populate its channel guide:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: http://YOUR_SERVER_IP:34400/lineup.json.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter GuideNumber.
  5. Set Check interval to 5 minutes.
  6. Click Save.

Step 6: Configure Alerts for Recording-Critical Events

Threadfin failures often surface as missed recordings, which you only discover after the fact. Front-load alerting to catch issues before scheduled recordings:

  1. Go to Alert Channels in Vigilmon and add email, Slack, PagerDuty, or a webhook.
  2. For the web UI and device discovery monitors, set Consecutive failures before alert to 1 — these are hard failures.
  3. For stream relay monitors, set to 2 — a single upstream hiccup may self-heal before the next probe.
  4. Schedule Maintenance windows around Threadfin updates to suppress restart alerts:
# Open a 5-minute maintenance window before restarting
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 5}'

docker compose restart threadfin

For media servers configured to record overnight, ensure your alert channel delivers notifications even outside business hours — a 2 AM EPG refresh failure that goes unnoticed until morning means the day's recordings have no guide metadata.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | http://HOST:34400/web/ | Go service crash, port unavailable | | M3U playlist | /m3u/threadfin.m3u | Upstream fetch failure, channel DB issue | | XMLTV EPG | /xmltv/threadfin.xml | EPG refresh failure, corrupt cache | | Stream relay | /stream/CHANNEL_ID | Provider outage, expired credentials | | Device discovery | /device.xml | HDHomeRun emulation failure | | Channel lineup | /lineup.json | Channel list unavailable to clients |

Threadfin is the invisible layer that makes self-hosted DVR work — when it's healthy, your media server sees a reliable tuner and recordings happen on schedule. With Vigilmon watching every endpoint in the proxy chain, you'll know the moment an upstream M3U fetch fails or the stream relay stalls, not three hours later when you check whether last night's recording exists.

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