Monitoring GoAccess with Vigilmon

GoAccess is a fast, open-source web log analyzer that can run as a daemon and stream live stats over a WebSocket connection or generate static HTML reports via a cron job or Nginx/Apache pipeline. Because GoAccess sits outside your application stack and doesn't expose a native health API, it tends to fail silently — the daemon crashes, the WebSocket feed drops, or a log rotation misconfiguration quietly breaks the parsing pipeline. Vigilmon gives you HTTP, TCP, and heartbeat monitors that catch every failure mode before your analytics go dark.

What You'll Set Up

• GoAccess daemon availability check via its WebSocket endpoint
• HTTP monitor for the HTML report rendering endpoint
• TCP port check for the real-time WebSocket server
• Cron heartbeat for scheduled log summary jobs
• SSL certificate monitoring for the Nginx/Apache report server
• Alert channel configuration with sensible thresholds

Prerequisites

• GoAccess installed and running as a daemon (goaccess --real-time-html)
• A web server (Nginx or Apache) serving the GoAccess HTML report
• A free Vigilmon account

Step 1: Monitor the HTML Report Endpoint

GoAccess in daemon mode writes a live-updating HTML file served by your web server. This is the primary user-facing output. Add an HTTP monitor in Vigilmon:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the report URL: https://logs.yourdomain.com/report.html
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword match, enter a string that only appears in a valid GoAccess report — for example goaccess or Unique Visitors.
7. Click Save.

The keyword check ensures Vigilmon catches cases where the web server returns 200 but GoAccess has stopped updating the file or the file has been deleted by a misconfigured log rotation script.

Step 2: Check the WebSocket Real-Time Feed

GoAccess daemon mode runs a WebSocket server (default port 7890) that pushes live log data to the browser. If this port is unreachable, the real-time graph in the HTML report freezes even though the page itself loads. Add a TCP monitor:

1. Click Add Monitor → TCP Port.
2. Enter your server's hostname or IP.
3. Set Port to 7890 (or your configured --port value).
4. Set Check interval to 1 minute.
5. Click Save.

Verify the port is open and not firewalled before configuring:

ss -tlnp | grep goaccess
# tcp  LISTEN 0  128  0.0.0.0:7890  0.0.0.0:*  users:(("goaccess",pid=1234,fd=3))

If GoAccess is running behind Nginx with a WebSocket proxy, monitor the proxy path instead:

location /ws {
    proxy_pass http://127.0.0.1:7890;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Then add an HTTP monitor for https://logs.yourdomain.com/ws — a 101 Switching Protocols or 400 Bad Request response both confirm the proxy route is alive.

Step 3: Verify the Log Parsing Pipeline

GoAccess reads log files continuously. If the log file path changes (due to rotation, a format change, or a symlink being broken), GoAccess silently stops processing new entries. Set up a lightweight probe:

Create a small script that checks the GoAccess PID file and the age of its output file, then pings a Vigilmon heartbeat:

#!/bin/bash
# /usr/local/bin/goaccess-health-ping.sh

REPORT="/var/www/html/report.html"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID"
MAX_AGE_SECONDS=120   # report should update at least every 2 minutes

if [ ! -f "$REPORT" ]; then
  echo "Report file missing" >&2
  exit 1
fi

LAST_MODIFIED=$(stat -c %Y "$REPORT")
NOW=$(date +%s)
AGE=$((NOW - LAST_MODIFIED))

if [ "$AGE" -gt "$MAX_AGE_SECONDS" ]; then
  echo "Report stale: ${AGE}s since last update" >&2
  exit 1
fi

# All checks passed — ping Vigilmon
curl -fsS "$HEARTBEAT_URL" > /dev/null

Run this script every minute via cron:

* * * * * /usr/local/bin/goaccess-health-ping.sh

Create the matching Vigilmon heartbeat monitor (Step 4 below) to catch any failure.

Step 4: Heartbeat Monitoring for the Log Summary Cron Job

If you run GoAccess as a one-shot command on a schedule to generate periodic reports, monitor the cron job with a Vigilmon heartbeat:

1. Click Add Monitor → Cron Heartbeat.
2. Set Expected ping interval to match your cron frequency (e.g. 60 minutes for hourly reports).
3. Set Grace period to 5 minutes to absorb short delays.
4. Copy the heartbeat URL shown in the monitor detail.

Add the curl ping at the end of your cron script:

#!/bin/bash
# /usr/local/bin/generate-report.sh

zcat /var/log/nginx/access.log.*.gz | \
  goaccess - --log-format=COMBINED -o /var/www/html/weekly-report.html

# Signal success to Vigilmon
curl -fsS https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID

If GoAccess exits with a non-zero code due to a malformed log format or a missing file, the heartbeat is never sent and Vigilmon alerts after the interval passes.

Step 5: SSL Certificate Monitoring for the Report Server

Your Nginx or Apache server terminating HTTPS for the GoAccess report endpoint needs valid SSL. Enable certificate monitoring alongside the HTTP monitor:

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

For Let's Encrypt-managed certificates, confirm auto-renewal is working:

certbot renew --dry-run

A Vigilmon SSL alert 21 days before expiry gives you three weeks to fix any renewal failure before the report endpoint becomes inaccessible.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook endpoint.
2. On the HTTP report monitor, set Consecutive failures before alert to 2 — this absorbs transient network hiccups without generating noise.
3. On the TCP WebSocket monitor, set Consecutive failures before alert to 1 — WebSocket port drops are rarely transient.
4. On the heartbeat monitor, the alert fires automatically after one missed interval.

For Slack, use a distinct channel for log analytics alerts so on-call engineers can distinguish GoAccess issues from application-level alerts:

#infra-monitoring → GoAccess report down
#app-alerts       → application errors

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP report endpoint | https://logs.yourdomain.com/report.html | Web server down, report file missing | | Keyword match | Unique Visitors in report HTML | GoAccess stopped writing output | | TCP WebSocket | Port 7890 | Real-time feed process crash | | Cron heartbeat | Heartbeat URL | Log summary job failure or stale output | | SSL certificate | Report server domain | Let's Encrypt renewal failure |

GoAccess gives you powerful log analytics without a SaaS subscription, but self-hosted tools don't monitor themselves. With Vigilmon checking the report endpoint, the WebSocket feed, the parsing pipeline freshness, and your scheduled jobs, you'll know the moment GoAccess goes silent — not when a user notices the dashboard is frozen.