How to Monitor Your Convex App with Vigilmon

Convex is the reactive full-stack backend — with real-time database, serverless functions, and file storage all in one. If you're building production apps on Convex, here's how to add uptime monitoring and connect to Vigilmon.

What to Monitor in Convex Apps

Convex manages its own infrastructure, but your app can still have issues:

• Your frontend (Next.js, Vite, etc.) might be down even if Convex backend is up
• HTTP Actions you expose can fail
• External services your Convex functions call can be unavailable
• Scheduled functions (cron jobs) can fail silently

Adding Health Checks to Your Convex App

HTTP Action Health Endpoint

Convex supports HTTP Actions — use these to expose a health endpoint:

// convex/http.ts
import { httpRouter } from 'convex/server';
import { httpAction } from './_generated/server';

const http = httpRouter();

http.route({
  path: '/health',
  method: 'GET',
  handler: httpAction(async (ctx, _request) => {
    try {
      // Optional: verify DB access by running a simple query
      // const count = await ctx.runQuery(api.health.checkDbAccess);

      return new Response(
        JSON.stringify({
          status: 'ok',
          backend: 'convex',
          timestamp: new Date().toISOString(),
        }),
        {
          status: 200,
          headers: { 'Content-Type': 'application/json' },
        }
      );
    } catch (err) {
      return new Response(
        JSON.stringify({
          status: 'error',
          error: err instanceof Error ? err.message : 'unknown',
        }),
        { status: 503 }
      );
    }
  }),
});

export default http;

// convex/health.ts — Query for the health action to run
import { query } from './_generated/server';

export const checkDbAccess = query({
  args: {},
  handler: async (ctx) => {
    // Simple check: count documents in any small table
    const result = await ctx.db.query('users').take(1);
    return result.length >= 0; // always true if DB is accessible
  },
});

Your health endpoint URL:

https://your-deployment.convex.cloud/health

Frontend Health Check (Next.js + Convex)

If you're using Convex with Next.js, also monitor your frontend:

// app/api/health/route.ts
import { NextResponse } from 'next/server';
import { ConvexHttpClient } from 'convex/browser';
import { api } from '@/convex/_generated/api';

const convexClient = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export async function GET() {
  try {
    // Verify Convex connectivity
    const isConnected = await convexClient.query(api.health.checkDbAccess);

    return NextResponse.json({
      status: 'ok',
      convex: isConnected ? 'connected' : 'degraded',
      frontend: 'ok',
      timestamp: new Date().toISOString(),
    });
  } catch (err) {
    return NextResponse.json(
      {
        status: 'error',
        convex: 'disconnected',
        error: err instanceof Error ? err.message : 'unknown',
      },
      { status: 503 }
    );
  }
}

export const dynamic = 'force-dynamic';

Heartbeat Monitoring for Convex Scheduled Functions

Convex supports cron jobs via crons.ts. Add heartbeat pings:

// convex/crons.ts
import { cronJobs } from 'convex/server';
import { internal } from './_generated/api';

const crons = cronJobs();

crons.daily(
  'daily-cleanup',
  { hourUTC: 2, minuteUTC: 0 },
  internal.jobs.runDailyCleanup
);

export default crons;

// convex/jobs.ts
import { internalAction } from './_generated/server';

export const runDailyCleanup = internalAction({
  args: {},
  handler: async (ctx) => {
    // Your cleanup logic
    // ...

    // Send heartbeat to Vigilmon
    const HEARTBEAT_URL = process.env.VIGILMON_HEARTBEAT_URL;
    if (HEARTBEAT_URL) {
      try {
        await fetch(HEARTBEAT_URL, { method: 'POST' });
      } catch (err) {
        console.error('Failed to send heartbeat:', err);
      }
    }
  },
});

Set VIGILMON_HEARTBEAT_URL in your Convex environment variables.

What to Monitor

1. Your Frontend Deployment

Monitor your Next.js / Vite frontend directly:

• https://yourapp.com — main site uptime
• https://yourapp.com/api/health — backend health

2. Convex HTTP Actions

If you expose HTTP endpoints via Convex:

• https://your-deployment.convex.cloud/health

3. SSL Certificate

Monitor your custom domain SSL:

• https://yourapp.com — SSL expiry monitoring

4. Scheduled Functions

Heartbeat monitors for critical cron jobs.

Setting Up Vigilmon for Convex Apps

1. Sign up at vigilmon.online
2. Add monitor for your frontend URL
3. Add monitor for your Convex HTTP Action health endpoint
4. Add SSL monitor for your custom domain
5. Add heartbeat monitor for your scheduled jobs
6. Configure alerts: email + Slack

Monitoring Checklist

• [ ] Frontend health endpoint (/api/health) returning 200
• [ ] Convex HTTP Action health endpoint configured
• [ ] SSL certificate monitor for custom domain
• [ ] Heartbeat monitors for critical scheduled functions
• [ ] Alert channels set up (email + Slack/Discord)
• [ ] Check interval set to 1 or 5 minutes

Start monitoring your Convex app free →