Monitoring FaunaDB with Vigilmon: Serverless Database Health, Query Availability & Worker Heartbeats

FaunaDB is a globally distributed serverless document database that removes infrastructure management entirely — no connection pools, no server sizing, no regional failover to configure. But "serverless" doesn't mean "failure-free." Rate limiting (throttled queries), token expiration, schema conflicts, and transient ABAC permission errors can all degrade your application while Fauna's own dashboard shows no incidents. Vigilmon adds an independent external layer: HTTP health checks on your Fauna-connected services that probe real query availability and alert before users encounter errors.

This tutorial shows you how to build meaningful uptime monitoring for Fauna-backed applications using Vigilmon.

What You'll Build

• A health endpoint that runs a lightweight Fauna query to verify real connectivity
• A Vigilmon HTTP monitor with appropriate timeout and JSON assertion settings
• Cron heartbeat monitoring for background Fauna workers
• An alerting strategy tuned to Fauna's serverless failure modes

Prerequisites

• A FaunaDB account with at least one database and collection
• A Fauna secret (API key) for your database
• An application service that talks to Fauna (Node.js, Python, or similar)
• A free account at vigilmon.online

Step 1: Add a Health Endpoint to Your Fauna Service

Add a /health route that executes a lightweight Fauna query — this verifies authentication, network reachability, and query availability end-to-end.

Node.js (fauna v4 driver)

// routes/health.js
import { Client, fql } from 'fauna';

const client = new Client({ secret: process.env.FAUNA_SECRET });

export async function healthHandler(req, res) {
  const checks = {};
  let ok = true;
  const start = Date.now();

  try {
    // Lightweight ping: read current time from Fauna
    const result = await client.query(fql`Time.now()`);
    checks.query = 'ok';
    checks.latencyMs = Date.now() - start;
    checks.serverTime = result.data?.toString();
  } catch (err) {
    checks.query = `error: ${err.message}`;
    checks.code = err.code ?? 'unknown';
    ok = false;
  }

  res.status(ok ? 200 : 503).json({
    status: ok ? 'ok' : 'degraded',
    service: 'fauna-service',
    checks,
  });
}

Python (fauna driver)

# routers/health.py
import os, time
from fauna import faunadb
from fauna.client import Client
from fauna.query import fql
from fastapi import APIRouter

router = APIRouter()

_client = Client(secret=os.environ['FAUNA_SECRET'])

@router.get("/health")
async def health():
    checks = {}
    ok = True
    start = time.monotonic()

    try:
        # Lightweight ping: read server time
        result = _client.query(fql("Time.now()"))
        latency_ms = int((time.monotonic() - start) * 1000)
        checks['query'] = 'ok'
        checks['latencyMs'] = latency_ms
        checks['serverTime'] = str(result.data)
    except Exception as e:
        checks['query'] = f'error: {e}'
        ok = False

    return {
        'status': 'ok' if ok else 'degraded',
        'service': 'fauna-service',
        'checks': checks,
    }

Extended health check: verify a real collection exists

For a richer probe that also confirms your schema is intact, read one document from a sentinel collection instead of using Time.now():

// Node.js — verify collection availability
const result = await client.query(fql`
  Collection.byName("healthcheck")?.exists() ?? false
`);
checks.collectionAccessible = result.data === true;

Create an empty healthcheck collection in your Fauna database and use it as a no-op probe target. This confirms both connectivity and access permissions without touching production data.

Step 2: Configure the Vigilmon HTTP Monitor

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: your service's health endpoint (e.g. https://api.example.com/health).
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. JSON assertion: path status, expected value ok.
7. Click Save.

Tip: Fauna's serverless model can exhibit cold-start latency spikes on infrequently used databases. If your database is rarely queried, set the response timeout to 15 seconds to avoid false-positive alerts on cold-start warm-up.

Add a second assertion on checks.latencyMs to catch silent slowdowns — if your Fauna queries normally complete in under 200 ms but suddenly take 2 seconds, that's a degradation worth knowing about even when status is technically ok.

Step 3: Heartbeat Monitoring for Background Fauna Workers

Fauna is often used in serverless background jobs — scheduled functions, event processors, and data migration workers — that have no HTTP endpoint to probe. Use Vigilmon's Heartbeat monitor to confirm these workers are running on schedule.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your job frequency (e.g. 60 minutes for an hourly worker).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Ping the heartbeat URL at the end of each successful job run:

// Node.js — scheduled Fauna worker
import fetch from 'node-fetch';
import { Client, fql } from 'fauna';

const client = new Client({ secret: process.env.FAUNA_SECRET });

export async function runDataSync() {
  try {
    // Your Fauna work here
    const result = await client.query(fql`
      Items.where(.status == "pending").map(item => {
        item.update({ status: "processed" })
      })
    `);

    // Signal success to Vigilmon
    await fetch(process.env.VIGILMON_HEARTBEAT_URL, { method: 'POST' });
    console.log('Data sync complete — heartbeat sent.');
  } catch (err) {
    console.error('Data sync failed — heartbeat NOT sent:', err.message);
    // Vigilmon will alert when the grace period expires
  }
}

# Python — scheduled Fauna worker
import os, requests
from fauna.client import Client
from fauna.query import fql

_client = Client(secret=os.environ['FAUNA_SECRET'])

def run_data_sync():
    try:
        # Your Fauna work here
        _client.query(fql(
            'Items.where(.status == "pending").map(item => item.update({ status: "processed" }))'
        ))

        # Signal success to Vigilmon
        requests.post(os.environ['VIGILMON_HEARTBEAT_URL'], timeout=5)
        print('Data sync complete — heartbeat sent.')
    except Exception as e:
        print(f'Data sync failed — heartbeat NOT sent: {e}')

Set the heartbeat grace period to 3× your expected job interval. If the worker runs every 30 minutes, set the grace period to 90 minutes. If the job errors and never pings, Vigilmon alerts after the grace period.

Step 4: Alert Routing

| Monitor type | Target | Alert channel | Priority | |---|---|---|---| | HTTP | /health (query ping) | Email + Slack | Critical | | HTTP | /health (latency assertion) | Slack | Warning | | Cron Heartbeat | Scheduled worker | Email + PagerDuty | Critical | | HTTP | API gateway in front of Fauna service | Slack | Warning |

Configure consecutive failures to 2 on the HTTP monitor before alerting — a single probe timeout during a Fauna cold-start is not a real outage. Two consecutive failures separated by 60 seconds indicate a genuine availability problem.

What Vigilmon Catches That Fauna's Dashboard Misses

| Scenario | Fauna Dashboard | Vigilmon | |---|---|---| | Rate-limited query returns 429 | May show metric but no alert | Health endpoint catches — 503 fires | | Expired Fauna secret causes 401 | Not surfaced as application alert | Health endpoint probe fails immediately | | Worker crashed silently mid-run | No job-level visibility | Heartbeat grace period expires → alert | | Latency spike on cold-start database | No SLO tracking per service | Latency assertion on health endpoint | | Regional network issue to Fauna servers | Internal Fauna metric only | Vigilmon external probe is independent |

FaunaDB's serverless model is powerful, but external health checks give you the independent signal that serverless metrics alone cannot provide. Monitoring your Fauna-connected services with Vigilmon means you know before your users do.

Start monitoring your Fauna applications in under 5 minutes — register free at vigilmon.online.