tutorial

LibreSpeed Monitoring with Vigilmon

"Learn how to monitor LibreSpeed, the open-source self-hosted internet speed test, with Vigilmon — covering web UI availability, backend API health, stats database connectivity, SSL certificate alerts, and automated test pipeline heartbeats."

LibreSpeed Monitoring with Vigilmon

LibreSpeed is a self-hosted HTML5 internet speed test that lets ISPs, corporate networks, and homelabs measure network performance without sending data to third-party services like Speedtest.net. It measures download speed, upload speed, ping, and jitter using the browser's fetch APIs against your own server, storing historical test results for SLA verification and capacity planning.

When LibreSpeed is deployed for ISP or enterprise use, its availability directly affects the ability to diagnose client-side network issues and verify SLA compliance. A broken backend endpoint or a disconnected stats database means test results are not being recorded — making it impossible to identify network degradation trends over time.

This guide covers how to monitor LibreSpeed with Vigilmon.

Why LibreSpeed Needs Monitoring

LibreSpeed failures range from total unavailability to silent data loss:

  • Web server outage — the Go binary or PHP process crashes; users see a connection refused error instead of the speed test page
  • Backend API failure — the download/upload test endpoints stop responding; the test page loads but all measurements fail with network errors
  • Database connectivity failure — the Go/PHP backend cannot write test results; tests appear to complete but no results are stored; the stats page is empty or stale
  • Stats page outage — the results dashboard is inaccessible; network operations teams cannot review historical performance data
  • SSL certificate expiry — for HTTPS LibreSpeed deployments, an expired cert blocks all browser-based speed tests

Vigilmon monitors each layer so failures are caught before they affect diagnostic workflows.

LibreSpeed Architecture Overview

| Component | Go Port | PHP Equivalent | Role | Monitoring Priority | |-----------|---------|---------------|------|---------------------| | Web UI | 8989 | 80 | HTML5 speed test page | Critical | | Download endpoint | /backend/empty | /backend/empty.php | Download test | High | | Upload endpoint | /backend/empty | /backend/empty.php | Upload test (POST) | High | | Garbage endpoint | /backend/garbage | /backend/garbage.php | Random data for download | High | | Stats page | /results | /results/stats.php | Historical results | Medium | | Database | SQLite/MySQL/PostgreSQL | Same | Result persistence | High |

Monitor 1: LibreSpeed Web UI Availability

Monitor the speed test page served by the Go backend or PHP/Apache/Nginx:

  1. Log in to Vigilmon → Monitors → New Monitor
  2. Type: HTTP
  3. Name: LibreSpeed - Web UI
  4. URL: http://your-librespeed-host:8989/ (Go) or http://your-librespeed-host/ (PHP)
  5. Method: GET
  6. Expected status: 200
  7. Keyword check: LibreSpeed
  8. Interval: 1 minute

Test your endpoint:

# Go backend
curl -s http://your-librespeed-host:8989/ | grep -i "librespeed"

# PHP backend
curl -s http://your-librespeed-host/ | grep -i "librespeed"

Monitor 2: LibreSpeed Download Endpoint

The /backend/empty (Go) or /backend/empty.php (PHP) endpoint is the download test endpoint. It returns an empty body with Content-Length: 0. A 200 response confirms the backend API is serving test endpoints:

  1. Type: HTTP
  2. Name: LibreSpeed - Download Endpoint
  3. URL: http://your-librespeed-host:8989/backend/empty (Go) or http://your-librespeed-host/backend/empty.php (PHP)
  4. Method: GET
  5. Expected status: 200
  6. Interval: 2 minutes
# Go
curl -sv http://your-librespeed-host:8989/backend/empty 2>&1 | grep "Content-Length\|< HTTP"
# Expected: HTTP/1.1 200 OK, Content-Length: 0

# PHP
curl -sv http://your-librespeed-host/backend/empty.php 2>&1 | grep "Content-Length\|< HTTP"

Monitor 3: LibreSpeed Garbage (Payload) Endpoint

The /backend/garbage (Go) or /backend/garbage.php (PHP) endpoint returns random data used for download speed measurement. A 200 response confirms the backend can generate test payloads:

  1. Type: HTTP
  2. Name: LibreSpeed - Garbage Endpoint
  3. URL: http://your-librespeed-host:8989/backend/garbage (Go) or http://your-librespeed-host/backend/garbage.php (PHP)
  4. Method: GET
  5. Expected status: 200
  6. Interval: 5 minutes
# Go — limit to 1KB to avoid large transfer in monitoring check
curl -s -r 0-1023 http://your-librespeed-host:8989/backend/garbage | wc -c
# Expected: 1024 bytes

Monitor 4: LibreSpeed Stats Page (Database Health)

The stats page queries the database to return historical speed test results. A 200 response from this endpoint confirms the database connection is healthy and results are being persisted:

  1. Type: HTTP
  2. Name: LibreSpeed - Stats Page / DB Health
  3. URL: http://your-librespeed-host:8989/results (Go) or http://your-librespeed-host/results/stats.php (PHP)
  4. Method: GET
  5. Expected status: 200
  6. Keyword check: Statistics
  7. Interval: 5 minutes
# Go
curl -s http://your-librespeed-host:8989/results | grep -i "statistics\|speed test"

# PHP
curl -s http://your-librespeed-host/results/stats.php | grep -i "statistics\|speed test"

If the stats page returns 200 but keyword check fails, the page may be rendering an error state — investigate the database connection.

Monitor 5: SSL Certificate Alert

LibreSpeed deployed for ISP or corporate use is typically reverse-proxied with HTTPS. An expired certificate blocks all speed tests from browser clients:

  1. Type: HTTP
  2. Name: LibreSpeed - SSL Certificate
  3. URL: https://speedtest.your-domain.com/
  4. SSL certificate expiry alert: 30 days before expiry
  5. Interval: 1 hour

Monitor 6: Test Pipeline Heartbeat

Schedule an automated speed test that verifies the complete pipeline — backend serving, telemetry acceptance, and database writes — using a cron job:

Heartbeat Script

#!/bin/bash
# librespeed-heartbeat.sh — run hourly via cron
set -euo pipefail

LIBRESPEED_URL="http://your-librespeed-host:8989"
VIGILMON_HEARTBEAT="YOUR_HEARTBEAT_ID"

# Step 1: Verify the download endpoint responds
EMPTY_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "${LIBRESPEED_URL}/backend/empty")

if [ "$EMPTY_STATUS" -ne 200 ]; then
  echo "[librespeed-hb] Download endpoint returned $EMPTY_STATUS"
  exit 1
fi

# Step 2: Submit a test result to verify database write pipeline
TELEMETRY_PAYLOAD='{"ispinfo":"","extra":"","ua":"heartbeat-monitor","lang":"","dl":"100.00","ul":"50.00","ping":"5","jitter":"1","log":""}'

TELEMETRY_STATUS=$(curl -s -o /tmp/librespeed_telemetry.json -w "%{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -d "$TELEMETRY_PAYLOAD" \
  "${LIBRESPEED_URL}/backend/results.php" 2>/dev/null || \
  curl -s -o /tmp/librespeed_telemetry.json -w "%{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -d "$TELEMETRY_PAYLOAD" \
  "${LIBRESPEED_URL}/results")

if [ "$TELEMETRY_STATUS" -ne 200 ] && [ "$TELEMETRY_STATUS" -ne 201 ]; then
  echo "[librespeed-hb] Telemetry POST returned $TELEMETRY_STATUS"
  exit 1
fi

# Step 3: Verify the stats page is accessible (confirms DB is readable)
STATS_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "${LIBRESPEED_URL}/results")

if [ "$STATS_STATUS" -ne 200 ]; then
  echo "[librespeed-hb] Stats page returned $STATS_STATUS"
  exit 1
fi

rm -f /tmp/librespeed_telemetry.json
curl -s "https://heartbeat.vigilmon.online/$VIGILMON_HEARTBEAT"
echo "[librespeed-hb] Pipeline healthy"

Add to cron:

# /etc/cron.d/librespeed-heartbeat
0 * * * * librespeed /opt/librespeed/librespeed-heartbeat.sh >> /var/log/librespeed-heartbeat.log 2>&1

In Vigilmon:

  • Type: Heartbeat
  • Name: LibreSpeed - Test Pipeline
  • Expected interval: 1 hour
  • Grace period: 15 minutes

This heartbeat verifies that the download endpoint, the database write pipeline, and the stats read path are all working end-to-end. A missed heartbeat means speed test results may not be persisting — network diagnostics data is being silently lost.

Alert Configuration

| Monitor | Type | Interval | Alert Channel | |---------|------|----------|---------------| | Web UI | HTTP | 1 min | Slack | | Download endpoint | HTTP | 2 min | Slack | | Garbage endpoint | HTTP | 5 min | Slack | | Stats page / DB health | HTTP | 5 min | Email + Slack | | SSL certificate | HTTP | 1 hour | Email + Slack (30-day lead) | | Test pipeline | Heartbeat | 1 hour | Email + Slack |

Status Page

  1. Status Pages → New Page → name it "LibreSpeed Network Test Server"
  2. Add all monitors above
  3. Share with your NOC or network operations team

When a user reports slow network speeds, your team can immediately verify whether LibreSpeed itself is healthy before starting network diagnostics.

Summary

LibreSpeed is the diagnostic tool your team reaches for during network incidents — it must be reliable and recording results continuously. Vigilmon ensures every component stays healthy:

  • HTTP monitors for web UI availability, download/garbage test endpoints, and stats database connectivity
  • SSL certificate monitoring for HTTPS deployments with 30-day lead time
  • Hourly heartbeat that submits a test result and verifies the complete database write pipeline

Get started 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