Monitoring Mathesar with Vigilmon

Mathesar is an open-source web application that gives non-technical users a spreadsheet-like interface for exploring and manipulating PostgreSQL databases. Built on Python/Django with a TypeScript frontend, it runs on port 8000 and depends on PostgreSQL, Redis, and Celery workers for background task processing. When Mathesar goes down, database access for non-technical team members stops, import pipelines stall, and scheduled data sync jobs silently fail. Vigilmon keeps every Mathesar component under continuous observation so your PostgreSQL workflows stay reliable.

What You'll Set Up

• Web server availability monitor
• PostgreSQL database connectivity monitor
• Django application server health check
• Celery background worker health monitor
• Redis cache connectivity monitor
• Database schema sync service monitor
• Table import/export pipeline health check
• API endpoint response time monitor
• User authentication service monitor
• Scheduled data synchronization job monitor

Prerequisites

• Mathesar deployed (Docker Compose or manual install) accessible on port 8000
• PostgreSQL running and accessible
• Redis running for Celery task queue
• A free Vigilmon account

Step 1: Monitor Web Server Availability

Mathesar's Django web server is the entry point for all user activity. Start with a basic HTTP availability check:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Mathesar URL: https://mathesar.yourdomain.com/.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Mathesar should return a 200 for the root path (which serves the web application). If you have authentication configured, it may redirect to a login page — in that case, monitor the login page URL directly or use the API health endpoint.

Step 2: Monitor PostgreSQL Connectivity

Mathesar is a PostgreSQL interface — its core function requires an active database connection. Monitor both the application-level database health and the raw TCP connectivity to PostgreSQL:

Application-level check

If Mathesar exposes a health or status endpoint, use it. Otherwise, use the API endpoint to verify database connectivity:

curl -s https://mathesar.yourdomain.com/api/v0/databases/ \
  -H "Authorization: Token YOUR_API_TOKEN" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print('ok' if len(d.get('results',[])) >= 0 else 'error')"

TCP-level check

1. Add a TCP monitor in Vigilmon.
2. Host: your-postgres-host, Port: 5432.
3. Interval: 1 minute.

A TCP failure at the PostgreSQL port means Mathesar cannot read or write any data, and all user operations will fail immediately.

Step 3: Monitor the Django Application Server

Mathesar runs a Django application server (gunicorn or uvicorn) behind a web server (nginx or Caddy). Probe the Django admin interface to verify the app server is handling requests correctly:

1. Add an HTTP / HTTPS monitor.
2. URL: https://mathesar.yourdomain.com/admin/.
3. Expected status: 200 or 302 (redirect to login — either is acceptable).
4. Interval: 1 minute.

Additionally, monitor the API root endpoint, which exercises Django's URL routing and database connection:

1. Add an HTTP / HTTPS monitor.
2. URL: https://mathesar.yourdomain.com/api/v0/.
3. Expected status: 200.
4. Interval: 1 minute.

Step 4: Monitor Celery Worker Health

Mathesar uses Celery workers to process background tasks including table imports, data type inference, schema synchronization, and long-running queries. When workers stall, these operations hang indefinitely.

Add a health check endpoint to your Mathesar deployment or use a heartbeat probe:

# Add to Mathesar's Django URL configuration or a management command
# Option 1: Custom health view that checks Celery
from django.http import JsonResponse
from celery.app.control import Control
from mathesar.celery import app as celery_app

def celery_health(request):
    try:
        control = Control(app=celery_app)
        inspect = control.inspect(timeout=2)
        active = inspect.active()
        status = 'ok' if active is not None else 'no_workers'
    except Exception:
        status = 'error'
    return JsonResponse({'status': status})

If you cannot add a custom endpoint, use a heartbeat that fires from a Celery periodic task:

# In mathesar/celery_tasks.py or equivalent
from celery import shared_task
import requests

@shared_task
def celery_heartbeat():
    requests.get('https://vigilmon.online/heartbeat/CELERY_HEARTBEAT_ID', timeout=5)

Add this task to your Celery beat schedule with a 5 minute interval, then create a matching Cron Heartbeat monitor in Vigilmon.

Step 5: Monitor Redis Cache Connectivity

Redis serves as the Celery broker and cache backend for Mathesar. A Redis failure stalls all background tasks and may degrade response times:

1. Add a TCP monitor in Vigilmon.
2. Host: your-redis-host, Port: 6379.
3. Interval: 1 minute.

For deeper Redis health, use a heartbeat script:

#!/bin/bash
REDIS_PING=$(redis-cli -h your-redis-host -p 6379 ping 2>/dev/null)
if [ "$REDIS_PING" = "PONG" ]; then
  curl -s "https://vigilmon.online/heartbeat/REDIS_HEARTBEAT_ID"
fi

Run this via cron every minute. A failed Redis ping means Celery workers cannot dequeue tasks and all background operations are stalled.

Step 6: Monitor Database Schema Sync

Mathesar maintains its own representation of your PostgreSQL schema. When the schema sync service falls behind, Mathesar's UI shows stale column types, missing tables, or incorrect constraint information.

Add a schema sync health check using the Mathesar API:

#!/bin/bash
# Check if the schema reflection is up to date by querying a known table
STATUS=$(curl -s \
  -H "Authorization: Token YOUR_API_TOKEN" \
  "https://mathesar.yourdomain.com/api/v0/tables/?database=YOUR_DB_ID" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print('ok' if 'results' in d else 'error')")

if [ "$STATUS" = "ok" ]; then
  curl -s "https://vigilmon.online/heartbeat/SCHEMA_SYNC_HEARTBEAT_ID"
fi

1. Add a Cron Heartbeat monitor with a 10 minute interval.
2. Run the script from cron.

Step 7: Monitor Table Import/Export Pipeline

Table imports — particularly CSV imports — go through the Celery task queue. A stalled import pipeline means data loading operations never complete.

Create a lightweight end-to-end import probe:

#!/bin/bash
# Upload a minimal CSV via the Mathesar API and check the response
IMPORT_RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST "https://mathesar.yourdomain.com/api/v0/tables/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "probe_import_check", "schema": YOUR_SCHEMA_ID, "import_target": {"id": null}}')

# A 201 means the table creation endpoint is accepting requests
if [ "$IMPORT_RESPONSE" = "201" ]; then
  curl -s "https://vigilmon.online/heartbeat/IMPORT_HEARTBEAT_ID"
fi

Alternatively, monitor the task queue length in Redis to detect import job backlogs:

QUEUE_LENGTH=$(redis-cli -h your-redis-host llen celery)
if [ "$QUEUE_LENGTH" -lt 100 ]; then
  curl -s "https://vigilmon.online/heartbeat/IMPORT_QUEUE_HEARTBEAT_ID"
fi

Step 8: Monitor API Response Times

The Mathesar REST API powers every user interaction — table reads, filters, row edits, and schema browsing. Slow API responses degrade the user experience significantly.

1. Open the API endpoint monitor created in Step 3.
2. Enable Response time alerting.
3. Set the threshold: 2000ms — Mathesar API calls that take over 2 seconds indicate PostgreSQL query performance issues or resource exhaustion.

For more granular monitoring, add a specific endpoint monitor for a known fast query:

https://mathesar.yourdomain.com/api/v0/databases/

This lightweight endpoint should respond in under 200ms. If it doesn't, the Django application layer is under pressure.

Step 9: Monitor User Authentication

Mathesar's authentication service controls all user access. A broken auth service locks out all users immediately:

1. Add an HTTP / HTTPS monitor.
2. URL: https://mathesar.yourdomain.com/auth/login/.
3. Expected status: 200.
4. Add a keyword check: Sign In or Log in (any text from the login form).
5. Interval: 5 minutes.

Also test that authenticated API calls work end-to-end with the heartbeat script from Step 6, which uses a real API token.

Step 10: Monitor Scheduled Data Sync Jobs

If you use Mathesar's data import pipelines on a schedule, verify they are completing successfully with a cron heartbeat:

# Add to your scheduled import management command
import requests

class Command(BaseCommand):
    def handle(self, *args, **options):
        try:
            run_scheduled_imports()
            requests.get(
                'https://vigilmon.online/heartbeat/SCHEDULED_SYNC_HEARTBEAT_ID',
                timeout=5
            )
        except Exception as e:
            self.stderr.write(f"Import failed: {e}")

1. Add a Cron Heartbeat monitor with an interval matching your sync schedule.
2. If a sync job crashes or times out, the heartbeat goes silent and Vigilmon alerts.

Step 11: Configure Alerts and Summary

In Vigilmon, go to Alert Channels and add Slack or email notifications. Recommended thresholds:

• Consecutive failures before alert: 2 for the web UI.
• Consecutive failures before alert: 1 for the Celery worker heartbeat — stalled workers affect all background operations.
• Response time alert: 2000ms for the API endpoint.

| Monitor | Target | What It Catches | |---|---|---| | Web server | Root URL | Mathesar process down | | PostgreSQL TCP | :5432 | Database connectivity lost | | Django API | /api/v0/ | Application server failure | | Celery heartbeat | Heartbeat URL | Background worker stalled | | Redis TCP | :6379 | Cache/broker unavailable | | Schema sync | Tables API heartbeat | Schema reflection broken | | Import pipeline | Queue heartbeat | CSV imports stalling | | API response time | API endpoint | Database slowness, resource exhaustion | | Authentication | Login page | User lockout | | Scheduled sync | Heartbeat URL | Scheduled import jobs failing |

Mathesar bridges the gap between raw PostgreSQL and non-technical users — when it fails, your team loses database access and data pipelines stop. With Vigilmon watching every layer from the PostgreSQL TCP socket to the Celery worker heartbeat, you'll catch Mathesar failures before users notice the spreadsheet stopped updating.