Monitoring Vendure Headless eCommerce with Vigilmon

Vendure is an open-source, TypeScript-native headless eCommerce framework built on NestJS and GraphQL. Its shop API serves customer storefronts, its admin API powers the merchant back-office, and its job queue handles async tasks like email delivery and order fulfillment webhooks — all backed by PostgreSQL. When a GraphQL endpoint degrades or the job queue grows unchecked, customers experience broken checkouts and orders stall silently. Vigilmon gives you continuous coverage across every layer: shop API, admin API, PostgreSQL, job queue, asset storage, and product search latency.

What You'll Set Up

• HTTP uptime monitor for the Vendure shop GraphQL API
• HTTP uptime monitor for the Vendure admin GraphQL API
• PostgreSQL connectivity heartbeat
• GraphQL API latency alert (p95 > 1 s)
• Job queue depth and failure-rate heartbeat
• Asset storage health check
• Product search latency monitor
• Redis health check (if used for job queue)

Prerequisites

• Vendure server running and accessible (default port 3000)
• A free Vigilmon account

Step 1: Monitor the Vendure Shop API

The shop GraphQL API at /shop-api handles every customer-facing operation: product search, add-to-cart, checkout, and order status. A crash here means your storefront stops working entirely.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Vendure shop API URL: http://your-server-ip:3000/shop-api.
4. Set Method to POST and add the header Content-Type: application/json.
5. Set the Request body to a lightweight introspection ping:

{"query": "{ __typename }"}

6. Set Expected HTTP status to 200.
7. Enable Response body must contain and enter __typename.
8. Set Check interval to 1 minute.
9. Click Save.

If Vendure is behind a reverse proxy:

https://your-storefront.com/shop-api

The __typename introspection query is the lightest possible GraphQL health check — it resolves instantly without touching the database and confirms the GraphQL server is accepting connections.

Step 2: Monitor the Vendure Admin API

The admin GraphQL API at /admin-api serves the merchant back-office (product management, order management, customer records). Its failure is less immediately visible to customers but blocks all merchant operations.

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter: http://your-server-ip:3000/admin-api.
3. Set Method to POST and add header Content-Type: application/json.
4. Set Request body to:

{"query": "{ __typename }"}

5. Set Expected HTTP status to 200.
6. Enable Response body must contain and enter __typename.
7. Set Check interval to 2 minutes.
8. Click Save.

Step 3: Monitor PostgreSQL Connectivity

PostgreSQL holds all Vendure data: products, variants, orders, payments, customers, promotions, and plugin data. A database failure brings the entire platform down.

Create a heartbeat script that verifies PostgreSQL is reachable and accepting queries:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected interval to 5 minutes.
3. Copy the heartbeat URL.

#!/bin/bash
# /usr/local/bin/vendure-db-check.sh

DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="vendure"
DB_USER="vendure"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-db-heartbeat"

# Run a lightweight query and ping on success
RESULT=$(psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER" -d "$DB_NAME" \
  -c "SELECT 1;" -t -A 2>/dev/null)

if [ "$RESULT" = "1" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "ERROR: PostgreSQL connectivity check failed"
fi

Make executable and schedule every 5 minutes:

chmod +x /usr/local/bin/vendure-db-check.sh
crontab -e
# Add:
*/5 * * * * /usr/local/bin/vendure-db-check.sh

Set the heartbeat Grace period to 6 minutes so a single slow cron execution does not trigger a false alert.

Step 4: Monitor GraphQL API Latency

Vendure's shop API must stay fast — a p95 response time above 1 second causes cart abandonment. Set a latency threshold on the shop API monitor:

1. Open the shop API monitor created in Step 1.
2. Enable Alert if response time exceeds and set it to 1000 ms.
3. Click Save.

For deeper p95 tracking, add a heartbeat script that measures actual query latency against a real product search:

#!/bin/bash
# /usr/local/bin/vendure-latency-check.sh

SHOP_API="http://localhost:3000/shop-api"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-latency-heartbeat"
MAX_MS=1000

QUERY='{"query":"{ search(input: { take: 1 }) { totalItems } }"}'

START=$(date +%s%3N)
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 5 \
  -X POST "$SHOP_API" \
  -H "Content-Type: application/json" \
  -d "$QUERY")
END=$(date +%s%3N)

ELAPSED=$(( END - START ))

if [ "$HTTP_CODE" = "200" ] && [ "$ELAPSED" -le "$MAX_MS" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "WARNING: shop API latency ${ELAPSED}ms (limit ${MAX_MS}ms), HTTP $HTTP_CODE"
fi

Schedule every 5 minutes:

*/5 * * * * /usr/local/bin/vendure-latency-check.sh

Step 5: Monitor Job Queue Health

Vendure's job queue (backed by the database or Bull/Redis) handles email delivery, order fulfillment webhooks, product imports, and plugin async tasks. A growing queue or high failure rate means async operations are stalling — orders are processed but confirmation emails never arrive, or fulfillment webhooks fail silently.

Add a heartbeat that checks the Vendure job queue via its admin API:

1. In Vigilmon, create a Cron Heartbeat with a 10 minute expected interval.
2. Copy the heartbeat URL.

#!/bin/bash
# /usr/local/bin/vendure-queue-check.sh

ADMIN_API="http://localhost:3000/admin-api"
ADMIN_TOKEN="YOUR_VENDURE_ADMIN_TOKEN"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-queue-heartbeat"
MAX_QUEUE_DEPTH=100
MAX_FAILURE_RATE=5  # percent

QUERY='{"query":"{ jobQueue { jobs(options: { filter: { state: { eq: PENDING } } }) { totalItems } } }"}'

RESPONSE=$(curl -s -m 10 \
  -X POST "$ADMIN_API" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d "$QUERY" 2>/dev/null)

PENDING=$(echo "$RESPONSE" | python3 -c "
import json, sys
try:
    d = json.load(sys.stdin)
    print(d['data']['jobQueue']['jobs']['totalItems'])
except:
    print(-1)
")

if [ "$PENDING" -ge 0 ] && [ "$PENDING" -le "$MAX_QUEUE_DEPTH" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "WARNING: Job queue depth $PENDING (limit $MAX_QUEUE_DEPTH)"
fi

Schedule every 10 minutes:

*/10 * * * * /usr/local/bin/vendure-queue-check.sh

Alert threshold: if the Vigilmon heartbeat is missed for more than 15 minutes, pages your on-call channel immediately — a growing queue typically escalates into order processing failures within the hour.

Step 6: Monitor Asset Storage Health

Vendure stores product images and asset files in local filesystem or cloud storage (S3, Google Cloud Storage) via the AssetStorageStrategy. A failed asset storage means product images return 404 and new uploads fail — damaging catalog presentation and blocking content managers.

Local filesystem

1. In Vigilmon, create a Cron Heartbeat with a 15 minute expected interval.
2. Copy the heartbeat URL.

#!/bin/bash
# /usr/local/bin/vendure-assets-check.sh

ASSET_DIR="/path/to/vendure/static/assets"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-assets-heartbeat"
DISK_THRESHOLD=80  # percent

# Check disk usage
USAGE=$(df "$ASSET_DIR" | awk 'NR==2 {print $5}' | tr -d '%')

if [ "$USAGE" -lt "$DISK_THRESHOLD" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "WARNING: Asset storage disk usage ${USAGE}% (limit ${DISK_THRESHOLD}%)"
fi

S3 asset storage

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter the S3 bucket URL for a known test asset file.
3. Set Expected HTTP status to 200.
4. Set Check interval to 10 minutes.
5. Click Save.

Step 7: Monitor Product Search Latency

Vendure's product search GraphQL query is the most-used storefront operation. A p95 above 2 seconds means customers are waiting on product list pages — a direct conversion-rate impact.

1. Open the shop API monitor created in Step 1.
2. Enable Alert if response time exceeds and set it to 2000 ms.

Pair this with the dedicated search latency heartbeat:

#!/bin/bash
# /usr/local/bin/vendure-search-latency.sh

SHOP_API="http://localhost:3000/shop-api"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-search-heartbeat"
MAX_MS=2000

QUERY='{"query":"{ search(input: { term: \"test\", take: 10 }) { totalItems items { productName } } }"}'

START=$(date +%s%3N)
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
  -X POST "$SHOP_API" \
  -H "Content-Type: application/json" \
  -d "$QUERY")
END=$(date +%s%3N)

ELAPSED=$(( END - START ))

if [ "$HTTP_CODE" = "200" ] && [ "$ELAPSED" -le "$MAX_MS" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "WARNING: search latency ${ELAPSED}ms (limit ${MAX_MS}ms)"
fi

Schedule every 5 minutes:

*/5 * * * * /usr/local/bin/vendure-search-latency.sh

Step 8: Monitor Redis (If Used for Job Queue)

If Vendure is configured to use Bull/Redis for its job queue instead of the database-backed default, Redis availability becomes critical — a Redis failure halts all async processing.

1. In Vigilmon, click Add Monitor → TCP Port.
2. Enter your Redis server hostname and port 6379.
3. Set Check interval to 1 minute.
4. Click Save.

For a richer check, use the Redis PING command:

#!/bin/bash
# /usr/local/bin/vendure-redis-check.sh

REDIS_HOST="localhost"
REDIS_PORT="6379"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/your-redis-heartbeat"

RESULT=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" PING 2>/dev/null)

if [ "$RESULT" = "PONG" ]; then
    curl -s "$HEARTBEAT_URL"
else
    echo "ERROR: Redis PING failed (got: $RESULT)"
fi

Schedule every 2 minutes:

*/2 * * * * /usr/local/bin/vendure-redis-check.sh

Step 9: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the shop API and admin API monitors — a brief NestJS restart takes a few seconds.
3. Set Consecutive failures before alert to 1 on the database and Redis monitors — any database interruption is immediately critical.

Route monitors to urgency channels:

• Shop API, DB, Redis failures → Slack #commerce-critical (immediate, wake on-call)
• Job queue depth alerts → Slack #commerce-ops (urgent within 30 minutes)
• Asset disk usage, search latency → email (investigate at next shift)

Summary

| Monitor | Target | What It Catches | |---|---|---| | Shop API | POST /shop-api + __typename | Storefront GraphQL down | | Admin API | POST /admin-api + __typename | Merchant back-office down | | PostgreSQL heartbeat | SELECT 1 every 5 min | Database connectivity loss | | Shop API latency | Alert > 1 s | Slow storefronts causing cart abandonment | | Job queue heartbeat | Admin API queue depth | Async tasks stalling (email, fulfillment) | | Asset storage | Disk usage or S3 URL | Product images 404, uploads failing | | Search latency | Search GraphQL p95 > 2 s | Catalog browsing degraded | | Redis TCP | Port 6379 | Job queue halted (Bull mode) |

Vendure's composable architecture makes it powerful — but that same modularity means failures at any layer (GraphQL server, database, job queue, storage) are isolated and silent. Vigilmon closes that observability gap so you learn about problems before your customers do.