Monitoring Logseq Sync Server with Vigilmon

Logseq is an open-source knowledge management and outliner application that lets teams self-host their own graph sync server. When that sync server goes down, every connected client silently loses the ability to commit changes — often without the user realising until they open the app on another device and find a conflict storm waiting for them. Vigilmon gives you real-time uptime monitoring for every critical sync server endpoint before conflicts accumulate.

What You'll Set Up

• Sync server availability monitor (port 3001)
• WebSocket connection health check
• Graph database sync endpoint monitor
• Authentication service monitor
• Cron heartbeat for the file conflict resolution service
• Storage backend availability check
• API server response time tracking

Prerequisites

• Logseq sync server deployed and accessible (default port 3001)
• A free Vigilmon account

Step 1: Monitor Sync Server Availability

The sync server is the heart of a self-hosted Logseq deployment. A simple HTTP check confirms it is accepting connections.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the sync server URL: https://logseq.yourdomain.com (or http://your-server-ip:3001 for LAN deployments).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

The sync server exposes a root health path that returns 200 when the Clojure process is running. An unexpected 502 or connection timeout means the JVM process has crashed or the reverse proxy is misconfigured.

Step 2: Monitor the WebSocket Endpoint

Logseq clients maintain a persistent WebSocket connection to sync graph changes in real time. HTTP uptime alone won't tell you if the WebSocket upgrade is failing.

Add a second monitor targeting the WebSocket upgrade path:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://logseq.yourdomain.com/ws (or your configured WebSocket path).
3. Set Expected HTTP status to 101 (Switching Protocols).
4. Set Check interval to 2 minutes.
5. Click Save.

If your reverse proxy (nginx / Caddy) is stripping the Upgrade: websocket header, this monitor catches the failure before any user reports "sync not working."

Example nginx configuration that passes WebSocket upgrades correctly:

location /ws {
    proxy_pass http://localhost:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Step 3: Monitor the Graph Sync Endpoint

The graph sync API endpoint handles page-level diff uploads from clients. Monitor it directly to confirm the sync path is accepting writes:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://logseq.yourdomain.com/sync/graph (adjust to match your server's routing).
3. Set Expected HTTP status to 200 or 401 (unauthenticated requests should get 401, not 500 or 503).
4. Set Check interval to 2 minutes.
5. Click Save.

A 401 response from an unauthenticated probe confirms the graph sync route is alive and protected. A 500 or 503 response indicates an internal crash or unavailable dependency.

Step 4: Monitor the Authentication Service

Logseq sync uses token-based authentication. If the auth service crashes, all clients will be locked out even if the WebSocket layer is technically alive.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://logseq.yourdomain.com/auth/status (or your configured auth health path).
3. Set Expected HTTP status to 200.
4. Set Check interval to 2 minutes.
5. Click Save.

If you run authentication through a separate identity provider (e.g. Keycloak, Authentik), add a dedicated monitor for that provider's /health endpoint as well.

Step 5: Heartbeat for the File Conflict Resolution Service

The conflict resolution service runs as a background process that periodically reconciles divergent graph states. Since it has no HTTP interface, use Vigilmon's cron heartbeat.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match the reconciliation schedule (e.g. 30 minutes).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. In your conflict resolution job script, add a ping after each successful run:

#!/bin/bash
# run_conflict_resolver.sh
/usr/local/bin/logseq-conflict-resolver --graph /data/graphs
curl -s https://vigilmon.online/heartbeat/abc123

If the process exits non-zero and never pings, Vigilmon alerts after the expected interval.

Step 6: Monitor Storage Backend Availability

Logseq sync stores graph data on disk (or S3-compatible object storage). A full disk or misconfigured mount silently breaks writes without crashing the server process.

For local disk storage, add a TCP monitor on the server's SSH port to confirm the host is reachable, and pair it with a disk-usage alert from your server monitoring stack. For S3-compatible storage, add an HTTP monitor for the bucket's health check endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://your-s3-endpoint/logseq-bucket?ping (or your object store's health path).
3. Set Expected HTTP status to 200.
4. Set Check interval to 5 minutes.
5. Click Save.

Step 7: Track API Server Response Time

Slow sync is almost as painful as no sync. Vigilmon records response time on every check — set a threshold alert so you catch performance degradation before it becomes an outage:

1. Open the sync server monitor created in Step 1.
2. Under Advanced, enable Alert if response time exceeds.
3. Set the threshold to 2000 ms (Logseq sync calls are lightweight and should resolve well under a second on a healthy server).
4. Click Save.

A gradual climb in response time often signals memory pressure on the JVM or a growing backlog in the sync queue.

Step 8: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the WebSocket and sync endpoint monitors — a single missed probe is normal during a JVM GC pause.
3. Add an On-call escalation policy so alerts page someone after 5 minutes of sustained failure.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Sync server | https://logseq.yourdomain.com | JVM crash, nginx down | | WebSocket | /ws | Proxy misconfiguration, upgrade failure | | Graph sync API | /sync/graph | Sync route unavailable, internal crash | | Auth service | /auth/status | Authentication lockout | | Cron heartbeat | Heartbeat URL | Conflict resolver crash, missed schedule | | Storage backend | S3 health path | Object store unavailable, disk full |

Self-hosting Logseq gives your team full data sovereignty — but that also means you own the availability. With Vigilmon watching every layer of the sync stack, you get early warnings before knowledge workers lose hours of unsaved notes to a silent sync failure.