Hakatime Monitoring with Vigilmon: Heartbeat Ingestion, Dashboard & Leaderboard Health Checks

Your team's coding activity stopped recording four hours ago. The weekly leaderboard shows stale data. Two engineers are blocked from seeing their daily stats. The Hakatime API process silently OOM-killed itself at 1 AM and nobody got an alert.

Hakatime is an open-source WakaTime-compatible coding statistics server written in Haskell. It listens on port 8080 and accepts heartbeat data from WakaTime-compatible editor plugins — VS Code, Neovim, IntelliJ, Emacs — and serves a dashboard with project breakdowns, language stats, and leaderboards. Self-hosting Hakatime means you own the entire pipeline from editor heartbeat through ingestion, aggregation, and leaderboard rendering — and you own the responsibility of knowing when any part of it fails.

Vigilmon probes your Hakatime installation from outside, the way a real editor plugin would. If the heartbeat endpoint stops accepting data, if the dashboard goes offline, or if the leaderboard computation service stalls, Vigilmon alerts you before your coding metrics have unexplained gaps.

What You'll Build

• An HTTP monitor on the Hakatime API server
• A heartbeat ingestion pipeline health check
• A dashboard web UI availability monitor
• A database connectivity probe via the stats endpoint
• A leaderboard computation service check
• An authentication endpoint health monitor
• Alert channels for your development operations team

Prerequisites

• A self-hosted Hakatime installation (v1.x recommended)
• API server default port: 8080
• A free account at vigilmon.online

Step 1: Monitor the Hakatime API Server

The Hakatime API is the entry point for all editor plugin traffic. If it goes down, every developer on your team stops recording coding activity without knowing it.

Test the API server is responding:

curl -o /dev/null -s -w "%{http_code}" http://your-hakatime-host:8080/

Hakatime returns a 200 or redirect at the root path when the Haskell process is running and bound to port 8080. Any Connection refused or timeout indicates the server process has crashed.

Set up the Vigilmon monitor:

1. Log in to Vigilmon and click New Monitor → HTTP.
2. Set URL to http://your-hakatime-host:8080/.
3. Set Check interval to 60 seconds.
4. Set Expected status code to 200.
5. Save the monitor.

This baseline check catches process crashes and port binding failures before any heartbeat data is lost.

Step 2: Monitor the Heartbeat Ingestion Pipeline

The heartbeat endpoint at /api/v1/users/current/heartbeats.bulk is the most critical path in your Hakatime deployment. Editor plugins POST batches of heartbeat data here every two minutes. If this endpoint fails, coding activity data is silently dropped — the editor plugin will not retry indefinitely.

Test that the ingest endpoint is accessible:

curl -o /dev/null -s -w "%{http_code}" \
  -H "Authorization: Basic $(echo -n 'your-api-key' | base64)" \
  http://your-hakatime-host:8080/api/v1/users/current/heartbeats.bulk

A healthy endpoint returns 405 Method Not Allowed for a GET probe (because it expects POST) or 400 Bad Request — both indicate the route is registered and the Haskell process is handling requests. A 502 or Connection refused means the ingestion route is down.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-hakatime-host:8080/api/v1/users/current/heartbeats.bulk.
3. Set Expected status code to 405.
4. Set Check interval to 60 seconds.
5. Under Advanced → Headers, add:
   • Authorization: Basic YOUR_BASE64_API_KEY
6. Save the monitor.

A failure here means editor plugins are silently discarding heartbeats right now. Every minute of downtime is a gap in your coding statistics that cannot be reconstructed.

Step 3: Monitor the Dashboard Web UI

Hakatime serves a web dashboard at /app that your team uses to review project breakdowns, language statistics, and time tracking reports. If the dashboard is down, developers have no way to access their data.

Test the dashboard endpoint:

curl -o /dev/null -s -w "%{http_code}" http://your-hakatime-host:8080/app

Expected: a 200 response serving the dashboard HTML, or a 302 redirect to the login page.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-hakatime-host:8080/app.
3. Set Check interval to 120 seconds.
4. Set Expected status code to 200.
5. Under Advanced → Keyword check, add:
   • Keyword present: Hakatime
6. Save the monitor.

This detects cases where the Haskell web server is running but the static asset serving or templating layer has failed — a different failure mode from a process crash.

Step 4: Monitor Database Connectivity

Hakatime stores all heartbeat and aggregated statistics data in PostgreSQL. If the database connection pool is exhausted or PostgreSQL becomes unreachable, the API process continues running but returns errors for every write and read.

Probe database connectivity via the stats summary endpoint:

curl -s \
  -H "Authorization: Basic YOUR_BASE64_API_KEY" \
  http://your-hakatime-host:8080/api/v1/users/current/stats/last_7_days

A healthy response returns a JSON object with data containing language and project breakdown fields. A database connectivity failure returns a 500 Internal Server Error or an empty data object — the Haskell process is alive but all queries are failing.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-hakatime-host:8080/api/v1/users/current/stats/last_7_days.
3. Set Expected status code to 200.
4. Under Advanced → Headers, add:
   • Authorization: Basic YOUR_BASE64_API_KEY
5. Under Advanced → Keyword check, add:
   • Keyword present: data
   • Keyword absent: error
6. Set Check interval to 300 seconds.
7. Save the monitor.

This is the most important database health probe because the stats endpoint exercises the full read path — connection pool, query execution, and JSON serialization.

Step 5: Monitor the Leaderboard Computation Service

Hakatime's leaderboard ranks users by coding activity. The computation runs on an internal schedule and serves results through the leaderboard API. If the aggregation job stalls or the leaderboard endpoint returns stale or empty data, team visibility into collective coding effort breaks silently.

Test the leaderboard endpoint:

curl -s \
  -H "Authorization: Basic YOUR_BASE64_API_KEY" \
  http://your-hakatime-host:8080/api/v1/leaders

A healthy response returns a JSON array of user rankings. An empty array [] when you have multiple active users indicates the aggregation job has not run recently. A 500 indicates the leaderboard query itself has failed.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-hakatime-host:8080/api/v1/leaders.
3. Set Expected status code to 200.
4. Under Advanced → Headers, add:
   • Authorization: Basic YOUR_BASE64_API_KEY
5. Under Advanced → Keyword check, add:
   • Keyword absent: error
6. Set Check interval to 300 seconds.
7. Save the monitor.

Step 6: Monitor the Authentication Endpoint

Hakatime handles authentication through its login API. If authentication is broken, developers cannot log in to view their data, and editor plugins using API key authentication may start receiving 401 Unauthorized responses and stop sending heartbeats.

Test the auth endpoint is reachable:

curl -o /dev/null -s -w "%{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"probe","password":"probe"}' \
  http://your-hakatime-host:8080/auth/login

Expected: 401 Unauthorized (credentials are wrong, but the endpoint is alive and processing). A 500 or Connection refused indicates the authentication middleware has failed.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-hakatime-host:8080/auth/login.
3. Set Method to POST.
4. Set Expected status code to 401.
5. Under Advanced → Body, set body to {"username":"probe","password":"probe"}.
6. Under Advanced → Headers, add:
   • Content-Type: application/json
7. Set Check interval to 120 seconds.
8. Save the monitor.

A 401 on a probe login is exactly what you want — it confirms the auth stack is running and processing requests correctly.

Step 7: Alert Channels

Go to Notifications → New Channel in Vigilmon and configure:

• Email — immediate alerts to your development operations team
• Webhook — Slack or Discord for team-wide visibility into coding statistics outages

A failing heartbeat ingestion alert looks like:

🔴 DOWN: hakatime-heartbeat-ingestion (HTTP monitor)
Expected status 405, got 502 Bad Gateway
Region: EU-Central
Triggered: 2026-07-13 02:14 UTC

When the pipeline recovers:

✅ RECOVERED: hakatime-heartbeat-ingestion
Downtime: 23 minutes

Set critical severity for the API server and heartbeat ingestion monitors — these directly impact data completeness. Use warning severity for the leaderboard and dashboard monitors. Enable Alerting → Escalation to page your infrastructure contact if the heartbeat endpoint is down for more than 10 minutes; heartbeat data lost during an outage cannot be reconstructed from editor plugins.

What You've Built

| Scenario | How Vigilmon catches it | |---|---| | Haskell process crash | HTTP monitor on :8080 fails with connection refused | | Heartbeat ingestion broken | /heartbeats.bulk endpoint returns non-405 or times out | | PostgreSQL connection pool exhausted | Stats endpoint returns 500 or error in body | | Leaderboard aggregation job stalled | /leaders endpoint returns error | | Dashboard serving failure | /app keyword check fails | | Authentication middleware broken | /auth/login POST returns non-401 | | Server OOM killed | All monitors fail simultaneously |

Gaps in your coding statistics are invisible until a developer asks why their time tracker shows three empty days. External monitoring with Vigilmon gives you a real-time signal when your Hakatime heartbeat pipeline, dashboard, or authentication layer breaks — before a gap in the data becomes something you have to explain to your team.

Start monitoring your Hakatime server today — register free at vigilmon.online.