Monitoring Wakapi with Vigilmon

Wakapi is a self-hosted, WakaTime-compatible backend for tracking your coding activity. It records languages, projects, and editors — and feeds that data into personal dashboards or WakaTime-compatible plugins. If it goes down unnoticed, your coding stats are simply lost rather than queued. Vigilmon gives you an independent external layer that watches Wakapi's web UI, health endpoint, and heartbeat ingestion so gaps in your history become alerts, not mysteries.

What You'll Set Up

• HTTP uptime monitor for the Wakapi web UI at port 3000
• Health endpoint check via /api/health
• SSL certificate expiry alerts for the Wakapi domain
• Heartbeat monitor to confirm coding stats are actively being ingested

Prerequisites

• Wakapi deployed and accessible (default port 3000)
• A WakaTime-compatible editor plugin sending heartbeats to your Wakapi instance
• A free Vigilmon account

Step 1: Monitor the Wakapi Web UI

Wakapi's web interface runs on port 3000 by default. This is where you view summaries, configure API keys, and manage leaderboards. Add an uptime monitor so you're alerted immediately if it becomes unreachable:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Wakapi URL: https://wakapi.yourdomain.com (or http://your-server-ip:3000 if not behind a reverse proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If Wakapi is behind nginx or Caddy, use the proxied domain — that validates the full request path, not just the application process.

Step 2: Check the /api/health Endpoint

Wakapi exposes a /api/health endpoint that returns a lightweight status response. Probing it separately from the UI gives a direct signal that the API layer is healthy, which is the critical path for heartbeat ingestion from your editor plugins:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://wakapi.yourdomain.com/api/health
3. Set Check interval to 2 minutes.
4. Under Advanced, set Expected response body contains to "operational":true (adjust if your Wakapi version returns a different body).
5. Click Save.

Verify the expected response first:

curl -s https://wakapi.yourdomain.com/api/health
# {"operational":true}

If the API layer is down while the web UI is still serving cached assets, only this endpoint check will catch it. That matters because editor plugins silently queue heartbeats when the API is unreachable — you want to know before the queue overflows.

Step 3: SSL Certificate Alerts

A lapsed certificate breaks heartbeat submissions from editor plugins immediately — most WakaTime-compatible clients reject TLS errors without a fallback. Add certificate monitoring to catch this before it happens:

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

With Let's Encrypt, a 21-day window gives you three full renewal attempts before expiry. If you're using a reverse proxy like Caddy that auto-renews certificates, this check confirms the renewal is actually working — Caddy failures are silent until the cert expires.

Step 4: Heartbeat Monitor for Coding Stats Ingestion

The most important thing Wakapi does is receive heartbeats from your editor. If ingestion silently stops — because of a bad API key, a plugin misconfiguration, or a Wakapi database issue — your stats degrade without any visible error. A Vigilmon heartbeat monitor detects this by expecting a regular ping correlated with your editing activity.

Create the heartbeat monitor:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Name it Wakapi — Heartbeat Ingestion.
3. Set the expected ping interval to 30 minutes (reasonable for active development days; adjust to your habits).
4. Copy the heartbeat URL: https://vigilmon.online/heartbeat/abc123.

Send a ping after each successful Wakapi submission:

If you have access to the machine running your editor, add a lightweight script that pings Vigilmon after confirming Wakapi received a recent heartbeat. For example, using Wakapi's API to check your last heartbeat timestamp:

#!/bin/bash
# Check if Wakapi received a heartbeat in the last 30 minutes
LAST=$(curl -s -H "Authorization: Basic $(echo -n ':YOUR_API_KEY' | base64)" \
  https://wakapi.yourdomain.com/api/compat/wakatime/v1/users/current/heartbeats \
  | jq -r '.data[-1].time // 0')
NOW=$(date +%s)
if [ $((NOW - ${LAST%.*})) -lt 1800 ]; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi

Run this script every 30 minutes via cron:

*/30 * * * * /home/user/check-wakapi-heartbeat.sh

The ping only reaches Vigilmon when Wakapi has received a recent heartbeat. If ingestion stops — for any reason — the heartbeat goes silent and Vigilmon alerts you.

Step 5: Database Connectivity

Wakapi supports SQLite, PostgreSQL, and MySQL as its backing store. A database failure causes heartbeat writes to fail silently or return 500 errors to editor plugins. The API health check from Step 2 usually catches this since Wakapi's health endpoint verifies database connectivity, but you can add a more explicit check:

1. Add a second HTTP monitor for https://wakapi.yourdomain.com/api/health.
2. Under Advanced, set Expected response body contains to "operational":true.
3. Set the alert to fire on 1 failed check.

This fires immediately on database loss — before queued editor heartbeats begin failing — giving you time to restore connectivity before any stats are permanently lost.

Step 6: Alert Routing

Wakapi downtime means lost coding history. Route these monitors to a channel you'll actually see:

1. Open each monitor and go to Notifications.
2. For the web UI and health endpoint monitors, fire on 1 failed check.
3. For the heartbeat monitor, allow a 2-check grace period to avoid false alarms during natural breaks in coding.
4. Add your preferred channel: email, Slack #dev-alerts, or a push notification.

What You've Built

With this setup, Vigilmon independently monitors every layer of your Wakapi stack: the web UI at :3000, the /api/health endpoint confirming API and database health, SSL certificate validity, and a heartbeat signal confirming that editor plugins are actively submitting coding stats. Gaps in your history become immediate alerts rather than silent data loss.

Get started at vigilmon.online.