Monitoring Your Prism API Mock Server with Vigilmon

Your Prism mock server is the contract between your frontend team and the backend API. When it goes down, everything that depends on your OpenAPI spec breaks — integration tests, developer environments, CI pipelines.

By the end of this tutorial you'll have:

A health probe for your Prism server
HTTP uptime monitoring with Vigilmon
Alerts when Prism stops responding or starts rejecting valid requests
Heartbeat monitoring for the Prism process

Setup takes under 15 minutes.

Step 1: Start Prism and identify your health probe

Prism doesn't have a built-in /health route, but it will return 200 for any route defined in your OpenAPI spec and 404 (or a validation error) for routes that aren't. You can use any stable GET endpoint from your spec as the health probe.

Install Prism CLI:

npm install -g @stoplight/prism-cli

Start a mock server from your OpenAPI spec:

prism mock ./openapi.yaml --port 4010

Or from a URL:

prism mock https://raw.githubusercontent.com/your-org/api-spec/main/openapi.yaml --port 4010

Pick a stable GET endpoint from your spec to use as the health check — for example, if your spec includes GET /ping or GET /status:

curl http://localhost:4010/ping

If your spec doesn't have a dedicated health route, add one:

# In your openapi.yaml
paths:
  /health:
    get:
      summary: Health check
      operationId: getHealth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

Prism will auto-generate a 200 response with example data from the schema.

Step 2: Run Prism as a persistent service

For CI or shared environments, run Prism under a process manager.

With PM2:

npm install -g pm2
pm2 start "prism mock ./openapi.yaml --port 4010" --name prism-mock
pm2 save
pm2 startup

With Docker:

FROM node:20-alpine
RUN npm install -g @stoplight/prism-cli
WORKDIR /app
COPY openapi.yaml .
EXPOSE 4010
CMD ["prism", "mock", "./openapi.yaml", "--port", "4010", "--host", "0.0.0.0"]

docker build -t prism-mock .
docker run -d -p 4010:4010 --name prism-mock prism-mock

With docker-compose:

services:
  prism:
    image: stoplight/prism:4
    command: mock /tmp/openapi.yaml --host 0.0.0.0 -p 4010
    ports:
      - "4010:4010"
    volumes:
      - ./openapi.yaml:/tmp/openapi.yaml:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4010/health"]
      interval: 30s
      timeout: 5s
      retries: 3

Step 3: Set up HTTP monitoring in Vigilmon

With Prism running, connect it to Vigilmon:

Sign up at vigilmon.online (free, no card required)
Click New Monitor → HTTP
Enter http://prism.yourdomain.com/health
Set check interval: 1 minute (paid) or 5 minutes (free)
Under Expected status code, set 200
Save

Add additional monitors for routes your CI pipeline depends on:

http://prism.yourdomain.com/health    → server alive
http://prism.yourdomain.com/users     → users endpoint reachable
http://prism.yourdomain.com/products  → products endpoint reachable

Prism returns different status codes depending on whether a request matches the spec. A 422 from Prism means your spec changed and a request that used to be valid no longer is — worth alerting on.

To monitor for unexpected 422 responses, create a monitor for a specific well-known endpoint and set Expected status code to 200. A 422 triggers an alert.

Step 4: Heartbeat monitoring for the Prism process

HTTP monitoring catches when Prism is unreachable. Heartbeat monitoring catches when the process crashes and restarts repeatedly without ever being fully down.

Create check-prism.sh:

#!/bin/bash
PRISM_URL="http://localhost:4010/health"
HEARTBEAT_URL="${VIGILMON_PRISM_HEARTBEAT}"

# Check Prism responds with 200
status=$(curl -s -o /dev/null -w "%{http_code}" "$PRISM_URL")

if [ "$status" = "200" ]; then
  curl -s "$HEARTBEAT_URL" > /dev/null
  echo "$(date): Prism healthy (HTTP $status)"
else
  echo "$(date): Prism health check failed (HTTP $status)"
  exit 1
fi

Add to cron:

*/5 * * * * /usr/local/bin/check-prism.sh >> /var/log/prism-health.log 2>&1

In Vigilmon, create a Heartbeat Monitor:

Click New Monitor → Heartbeat
Set expected interval to 10 minutes
Copy the ping URL into VIGILMON_PRISM_HEARTBEAT

Step 5: Validate your spec is being served correctly

One Prism-specific failure mode: Prism starts fine but the spec file it loaded was corrupted, truncated, or empty. The server runs but all routes return 404.

Add a route-level sanity check to your CI pipeline:

#!/bin/bash
PRISM_URL="http://localhost:4010"

check_route() {
  local path=$1
  local expected=$2
  local actual=$(curl -s -o /dev/null -w "%{http_code}" "${PRISM_URL}${path}")
  
  if [ "$actual" = "$expected" ]; then
    echo "OK: $path → $actual"
  else
    echo "FAIL: $path expected $expected got $actual"
    exit 1
  fi
}

check_route "/health" "200"
check_route "/users" "200"
check_route "/products" "200"
check_route "/nonexistent-route-xyzzy" "404"

Run this after starting Prism to verify the spec loaded correctly before CI proceeds.

Step 6: Slack alerts and status page

In Vigilmon, go to Notifications → New Channel → Slack and paste your webhook URL.

When Prism goes down:

🔴 DOWN: prism.yourdomain.com/health
Status: Connection refused
Region: US-East
2 minutes ago

For teams that share the Prism instance, a public status page removes "is the mock server down?" from every investigation:

Status Pages → New Status Page
Add all your Prism monitors
Share the URL with frontend, mobile, and QA teams

What you've built

| What | How | |------|-----| | Health probe | Stable GET /health route in OpenAPI spec | | Process supervision | PM2 or Docker with restart policy | | HTTP uptime monitoring | Vigilmon HTTP monitor | | Process heartbeat | Cron script + Vigilmon heartbeat monitor | | Spec validation sanity | CI route-level checks post-startup | | Slack alerts | Vigilmon Slack notification channel | | Shared status page | Vigilmon public status page |

Prism is infrastructure for your API contract. Monitor it like infrastructure.

Next steps

Add a Vigilmon monitor for the upstream spec URL (if Prism loads from a remote URL) — if the spec becomes unreachable, Prism can't reload it
Monitor response time trends — Prism serving large specs can get slow under load
Add a Vigilmon HTTP monitor for your actual API server alongside the mock, so you can compare mock vs real behavior

Get started free at vigilmon.online.