Monitoring SurrealDB with Vigilmon: HTTP API Health, Query Engine Availability, SSL Certificates & Uptime Checks

SurrealDB is a next-generation multi-model database that combines document, graph, key-value, and relational capabilities in a single engine — increasingly adopted in modern applications for its flexible data model and built-in real-time query streaming. Like any database infrastructure, SurrealDB exposes a surface area that can fail independently of your application: the HTTP API can become unreachable, authentication can break due to misconfiguration, the WebSocket endpoint for live queries can degrade, and TLS certificates can expire silently. Vigilmon gives you an external, independent monitoring layer for SurrealDB: HTTP API availability, query engine health, authentication smoke tests, and SSL certificate expiry — all checked from outside your infrastructure.

What You'll Build

• An HTTP monitor on the SurrealDB health endpoint confirming the server is running
• An API availability check verifying the SurrealDB REST API is responding
• An authenticated query smoke test confirming the query engine and auth layer are functional
• SSL certificate monitoring for your SurrealDB endpoint domain
• Alerting configured appropriate for a database-critical system

Prerequisites

• SurrealDB (v1.x or v2.x) running and accessible via HTTPS
• A SurrealDB namespace, database, and credentials for the monitoring user
• A free account at vigilmon.online

Step 1: Monitor the SurrealDB Health Endpoint

SurrealDB exposes a /health endpoint that returns the server status without requiring authentication. This is the fastest way to detect whether the SurrealDB process is running and able to accept connections:

curl -I https://your-surrealdb.example.com/health

A healthy SurrealDB instance returns 200 OK. Any process crash, OOM kill, or port binding failure will cause this check to fail before your application notices. Add the monitor:

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://your-surrealdb.example.com/health.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Label: SurrealDB - Health Check.
6. Click Save.

Default port: SurrealDB listens on port 8000 by default. If you have not placed it behind a reverse proxy, your URL will be https://your-host:8000/health. Using a reverse proxy (Nginx, Caddy) at port 443 is recommended for production deployments.

Step 2: Monitor the SurrealDB HTTP API

SurrealDB's REST API is the primary interface for SQL queries and record operations. A degraded HTTP layer — misconfigured reverse proxy, exhausted connection pool, or crashed worker — can leave the health endpoint green while the API itself fails. Verify the API responds independently:

curl https://your-surrealdb.example.com/status

A healthy SurrealDB server returns 200 OK with a plain-text "OK" body. Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-surrealdb.example.com/status.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Keyword: OK.
6. Label: SurrealDB - API Status.
7. Click Save.

Why separately from /health: The /health endpoint can return 200 while the query processing layer is degraded. The /status endpoint confirms the full SurrealDB request pipeline is operational.

Step 3: Add an Authenticated Query Smoke Test

The health and status checks confirm the SurrealDB process is alive, but they do not verify that authentication is working or that the query engine can execute SQL. Add an authenticated smoke test using the SurrealDB SQL endpoint:

First, create a read-only monitoring user in SurrealDB:

curl -X POST https://your-surrealdb.example.com/sql \
  -H "Accept: application/json" \
  -H "NS: your-namespace" \
  -H "DB: your-database" \
  -u "root:your-root-password" \
  --data "DEFINE USER vigilmon ON DATABASE PASSWORD 'monitoring-password' ROLES VIEWER;"

Then verify the smoke test query works:

curl -X POST https://your-surrealdb.example.com/sql \
  -H "Accept: application/json" \
  -H "NS: your-namespace" \
  -H "DB: your-database" \
  -u "vigilmon:monitoring-password" \
  --data "SELECT * FROM information WHERE id = 'none' LIMIT 1;"

A healthy response returns a JSON array — even an empty result confirms the query engine executed the statement successfully:

[{"result":[],"status":"OK","time":"123µs"}]

Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-surrealdb.example.com/sql.
3. Method: POST.
4. Request headers:
   • Accept: application/json
   • NS: your-namespace
   • DB: your-database
   • Authorization: Basic <base64(vigilmon:monitoring-password)>
5. Request body: SELECT 1;
6. Check interval: 5 minutes.
7. Expected status: 200.
8. Keyword: "status":"OK".
9. Label: SurrealDB - Query Engine Smoke Test.
10. Click Save.

What this catches that the status check does not: Storage engine corruption, WAL issues, or a failed schema migration can leave the HTTP layer fully operational while query execution fails. This smoke test is the earliest external signal for those failure modes.

Step 4: Monitor SSL Certificates

SurrealDB in production should be served over TLS. An expired certificate breaks every client connection — application code, developer tooling, and monitoring dashboards all fail simultaneously:

curl -v https://your-surrealdb.example.com/health 2>&1 | grep -i "expire"

Add SSL monitoring:

1. Add Monitor → SSL Certificate.
2. Domain: your-surrealdb.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

Auto-renewal gaps: If you use Let's Encrypt via Certbot or Caddy, renewal usually happens automatically at 30 days. The Vigilmon SSL alert at 30 days catches the case where auto-renewal fails silently — giving you a full month to intervene before the certificate expires.

Step 5: Monitor the WebSocket Endpoint (Live Queries)

SurrealDB's live query feature uses WebSocket connections. If your application depends on real-time data streaming, add a keyword-based HTTP check on the WebSocket upgrade path to detect if the endpoint is accepting connections:

curl -I https://your-surrealdb.example.com/rpc

The response to an HTTP request on the WebSocket path returns 200 with an Upgrade header. Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-surrealdb.example.com/rpc.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Label: SurrealDB - RPC/WebSocket Endpoint.
6. Click Save.

Step 6: Configure Alerting

In Vigilmon under Settings → Notifications, configure alert channels for your team:

| Monitor | Trigger | Action | |---|---|---| | SurrealDB - Health Check | Non-200 or timeout | SurrealDB process down; check systemd/Docker service status and OOM logs | | SurrealDB - API Status | Non-200 or OK keyword missing | Request pipeline degraded; check reverse proxy and SurrealDB error logs | | SurrealDB - Query Engine Smoke Test | Non-200 or "status":"OK" missing | Auth or query engine failure; check credentials and storage engine health | | SurrealDB - RPC/WebSocket | Non-200 | Live query subscriptions broken; check WebSocket proxy configuration | | SSL Certificate | < 30 days to expiry | Certificate renewal failed; renew manually or fix auto-renewal configuration |

Alert sensitivity: Set database monitors to alert after 2 consecutive failures (one transient check bounce does not warrant a 3am page). For the authenticated query smoke test, alert after 1 failure — a query engine that cannot execute SELECT 1 is a severity-1 incident.

Escalation channel: Route SurrealDB alerts to your on-call channel. Database unavailability causes application errors immediately and almost always requires human intervention.

Common SurrealDB Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | SurrealDB process OOM-killed | Health Check fires | | Reverse proxy misconfiguration after update | API Status fires; Health Check may stay green if direct port is accessible | | Storage engine corruption or WAL failure | Query Engine Smoke Test fires; Health and Status may stay green | | Authentication config change breaking credentials | Query Engine Smoke Test fires | | TLS certificate expires | SSL monitor alerts at 30-day threshold; all HTTPS monitors fail together | | Disk full on SurrealDB host | Query engine fails; Smoke Test fires | | Network partition | All monitors fire simultaneously | | SurrealDB version upgrade breaks API schema | API Status or Smoke Test fires with unexpected response format | | WebSocket proxy failure (Nginx upgrade config missing) | RPC endpoint monitor fires | | Namespace or database deletion | Smoke Test fires with authentication or database-not-found error |

Why Monitor SurrealDB with an External Tool

SurrealDB's internal instrumentation (metrics, logs, traces) depends on the SurrealDB process being healthy enough to emit them. When the process crashes or the network partitions, your internal observability stack goes silent at exactly the moment you need it most. Vigilmon gives you an independent external signal: a check that runs from outside your infrastructure and delivers alerts through a separate channel — email, Slack, PagerDuty — regardless of whether SurrealDB itself is reachable.

This external layer is especially important for SurrealDB deployments because the multi-model nature of the engine means a single process is handling workloads that would normally span multiple specialized databases. A single failure point has broader application impact than a traditional single-purpose database.

SurrealDB is powerful database infrastructure, but no database is immune to process crashes, storage failures, or certificate expiry. Vigilmon provides the external monitoring layer that SurrealDB cannot provide for itself: process health, API availability, query engine smoke tests, and SSL certificate expiry — all checked from outside your network.

Start monitoring SurrealDB in under 5 minutes — register free at vigilmon.online.