How to Monitor Your Medusa.js Headless Commerce Backend with Vigilmon

Medusa.js is an open-source headless commerce platform built on Node.js. When your Medusa backend goes down, your storefront can't fetch products, process orders, or handle payments. This guide shows how to monitor your Medusa instance with Vigilmon.

What Breaks When Medusa Goes Down

Medusa provides the backend API for your storefront:

• Product catalog and inventory
• Customer authentication
• Cart and checkout
• Order management
• Payment processing (Stripe, etc.)

When Medusa is unavailable, your store shows errors or serves stale data.

Step 1: Monitor Medusa's Built-In Health Endpoint

Medusa includes a health check endpoint at /health:

GET https://your-medusa-backend.com/health

Response when healthy: { "message": "ok" }

In Vigilmon:

• URL: https://your-medusa-backend.com/health
• Check interval: 1 minute
• Multi-region: enabled

Step 2: Add a Database Health Check

The default /health endpoint doesn't verify the database:

// src/api/routes/health/get-health.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(req: MedusaRequest, res: MedusaResponse): Promise<void> {
  try {
    const query = req.scope.resolve("query");
    await query.graph({ entity: "store", fields: ["id"], filters: {} });

    res.json({ status: "ok", database: "connected", timestamp: new Date().toISOString() });
  } catch (error) {
    res.status(503).json({ status: "error", database: "disconnected", message: error.message });
  }
}

Step 3: Monitor the Full Stack

What	URL	Interval
Medusa backend	/health	1 min
Storefront	https://yourstore.com	1 min
Admin panel	https://admin.yourstore.com	5 min

Step 4: Monitor Medusa's Event Bus Workers

Medusa uses an event bus for async operations. Add heartbeat monitoring:

// src/jobs/heartbeat.ts
import type { MedusaContainer } from "@medusajs/framework/types";

export default async function heartbeatJob(container: MedusaContainer) {
  const heartbeatUrl = process.env.VIGILMON_HEARTBEAT_URL;
  if (heartbeatUrl) {
    await fetch(heartbeatUrl).catch(() => {});
  }
}

export const config = {
  name: "vigilmon-heartbeat",
  schedule: "* * * * *", // every minute
};

Create a Vigilmon heartbeat monitor with a 2-minute period.

Step 5: Medusa on Render or Railway

• Render free tier spins down after inactivity — Vigilmon's ping acts as a keepalive
• Railway restarts on deploy — brief expected outage window during deploys

Add VIGILMON_HEARTBEAT_URL as an environment variable in your hosting dashboard.

What Vigilmon Catches for Medusa

Failure	Detection
Medusa crashed	HTTP health returns connection refused
PostgreSQL lost	Custom DB health endpoint returns 503
Event bus down	Heartbeat job stops running
OOM kill	Downtime detected by multi-region
Bad plugin broke startup	Server fails to start, monitor alerts

Summary

1. Monitor /health for basic Medusa availability
2. Add a custom endpoint that verifies database connectivity
3. Add heartbeat monitoring for the event bus workers
4. Monitor your storefront URL separately
5. Set up Slack/email alerts

---

Vigilmon — uptime and heartbeat monitoring for Medusa.js and every Node.js backend. Free plan available.