tutorial

Monitoring Process Compose with Vigilmon

Process Compose orchestrates your local dev processes — but when its API goes dark, a worker crash-loops, or a readiness probe silently times out, you won't know until something breaks. Here's how to monitor every critical signal with Vigilmon.

Process Compose is an open source process supervisor and orchestrator that lets developers define and run multiple processes together — API servers, background workers, database migrations, file watchers — using a single process-compose.yaml file. It's designed as a more developer-friendly alternative to Foreman, Procfile runners, and Docker Compose for local process management, providing a terminal UI, REST API, and web UI for viewing logs and managing process lifecycle. Vigilmon gives you continuous visibility into Process Compose's API health, individual process status, restart counts, and readiness probe outcomes — so you catch failures before they cascade.

What You'll Set Up

  • HTTP uptime monitor for the Process Compose REST API and web UI (port 8080)
  • Cron heartbeats for individual process health and restart counts
  • Heartbeat for readiness probe success
  • Log storage disk space alert

Prerequisites

  • Process Compose installed and running (process-compose up or as a managed service)
  • REST API accessible at http://localhost:8080
  • A free Vigilmon account

Why Monitoring Process Compose Matters

Process Compose manages the full lifecycle of your development processes, so its failure modes span the entire application:

  • API / web UI down: If the Process Compose server on port 8080 crashes, you lose programmatic control of all processes and visibility into their status.
  • Silent process crashes: A worker process that exits unexpectedly may be restarted by Process Compose — but if it hits its max restart count, it stops restarting and dies silently.
  • Dependency resolution failure: Process Compose starts processes in dependency order. A circular dependency or a failed upstream process blocks dependents from ever starting.
  • Readiness probe timeouts: When one process must be ready before another starts, a slow or broken readiness probe silently blocks the entire startup chain.
  • Log disk exhaustion: Process Compose aggregates logs from all processes into a log directory. On verbose workloads, this fills the disk and eventually causes write errors.
  • Config errors on reload: Reloading process-compose.yaml with a syntax error or invalid field stops the reload silently, leaving stale configuration in place.

Step 1: Monitor the REST API and Web UI

The Process Compose REST API and web UI share port 8080. The API is the control plane for all programmatic process management — stopping, starting, and restarting processes. When it's down, you can't query status or interact with any running process.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Set URL to http://localhost:8080/ (or the LAN IP of your dev machine).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

For a more precise health check, use the Process Compose API's process list endpoint:

http://localhost:8080/api/v1/processes

This returns a JSON list of all defined processes with their current state. A 200 response confirms the API engine is healthy and can enumerate running processes.

If Vigilmon's probes can't reach your localhost directly, run a local polling script that posts heartbeats to Vigilmon's inbound API instead — see Step 2 for the pattern.

Step 2: Monitor Individual Process Health

Process Compose exposes a REST API for querying the status of each defined process. Poll it to detect unexpected exits or stuck processes.

#!/bin/bash
# process-compose-health.sh — run every minute

API="http://localhost:8080/api/v1/processes"
RESPONSE=$(curl -sf "$API")

if [ -z "$RESPONSE" ]; then
  exit 1  # API unreachable — don't ping heartbeat
fi

# Count processes in a non-running state (stopped, error, dead)
UNHEALTHY=$(echo "$RESPONSE" | jq '[.[] | select(.status != "Running")] | length')

if [ "$UNHEALTHY" = "0" ]; then
  curl -sf https://vigilmon.online/heartbeat/pc-all-processes-xyz
fi
  1. In Vigilmon, add a Cron Heartbeat with interval 5 minutes.
  2. Schedule the script every minute: * * * * * /path/to/process-compose-health.sh

When any process exits unexpectedly, the heartbeat stops arriving and Vigilmon alerts you within 5 minutes.

For critical processes that must be individually monitored, add a dedicated heartbeat per process:

#!/bin/bash
# Check a single process by name
PROCESS_NAME="api-server"
STATUS=$(curl -sf "http://localhost:8080/api/v1/process/$PROCESS_NAME" | jq -r '.status')

if [ "$STATUS" = "Running" ]; then
  curl -sf https://vigilmon.online/heartbeat/pc-api-server-xyz
fi

Step 3: Monitor Process Restart Count

A process that keeps crashing and restarting hits its max restart count, then stops being restarted. The window between "crashing repeatedly" and "permanently dead" is silent. Monitor restart counts to catch crash loops early.

#!/bin/bash
# process-compose-restarts.sh — run every 5 minutes

API="http://localhost:8080/api/v1/processes"
RESPONSE=$(curl -sf "$API")

if [ -z "$RESPONSE" ]; then
  exit 1
fi

# Alert if any process has restarted more than 3 times
HIGH_RESTARTS=$(echo "$RESPONSE" | jq '[.[] | select(.restarts > 3)] | length')

if [ "$HIGH_RESTARTS" = "0" ]; then
  curl -sf https://vigilmon.online/heartbeat/pc-restart-count-xyz
fi
  1. Add a Cron Heartbeat in Vigilmon with interval 15 minutes.
  2. Schedule the script every 5 minutes.

Tune the threshold (> 3) to match your process's expected restart behavior on startup.

Step 4: Readiness Probe Health

Process Compose can wait for a process to become ready (via HTTP probe, TCP probe, or exec probe) before starting dependent processes. If the readiness probe times out or repeatedly fails, the dependent process never starts and the startup chain stalls.

Monitor readiness probe health by checking that all dependent processes eventually reach Running state within a startup window:

#!/bin/bash
# process-compose-readiness.sh — run once after startup, or periodically

API="http://localhost:8080/api/v1/processes"
RESPONSE=$(curl -sf "$API")

# Check for processes stuck in "Pending" or "Starting" state for over 5 minutes
STUCK=$(echo "$RESPONSE" | jq '[.[] | select(.status == "Pending" or .status == "Starting")] | length')

if [ "$STUCK" = "0" ]; then
  curl -sf https://vigilmon.online/heartbeat/pc-readiness-xyz
fi
  1. Add a Cron Heartbeat in Vigilmon with interval 10 minutes.
  2. Run the script every 2 minutes.

If a process is stuck in Pending state for more than 10 minutes, the heartbeat misses and Vigilmon alerts you.

Step 5: Log Storage Disk Space Alert

Process Compose aggregates logs from all processes. On verbose workloads (heavy debug logging, high-throughput workers), log files can grow rapidly and exhaust disk space.

Monitor the log storage directory:

#!/bin/bash
# pc-log-disk.sh — run every 30 minutes

# Process Compose default log directory — adjust to your config
LOG_DIR="${HOME}/.cache/process-compose"

if [ -d "$LOG_DIR" ]; then
  DISK_USAGE=$(df "$LOG_DIR" | awk 'NR==2 {print $5}' | tr -d '%')
  LOG_SIZE_MB=$(du -sm "$LOG_DIR" | awk '{print $1}')

  if [ "$DISK_USAGE" -lt 85 ] && [ "$LOG_SIZE_MB" -lt 5000 ]; then
    curl -sf https://vigilmon.online/heartbeat/pc-log-disk-xyz
  fi
fi
  1. Add a Cron Heartbeat in Vigilmon with interval 60 minutes.
  2. Schedule the script every 30 minutes.

Implement log rotation to prevent unbounded growth:

# process-compose.yaml
processes:
  api-server:
    command: "./api-server"
    log_configuration:
      rotation:
        max_size_mb: 100
        max_age_days: 7
        max_backups: 3

Step 6: Configuration Validation Health

When process-compose.yaml is reloaded (via API or SIGHUP), an invalid configuration silently leaves the previous configuration in place. Monitor config health on startup and after reloads.

#!/bin/bash
# pc-config-health.sh — run after any config change or on a schedule

# Validate config before applying
if process-compose validate --config process-compose.yaml 2>/dev/null; then
  curl -sf https://vigilmon.online/heartbeat/pc-config-xyz
fi
  1. Add a Cron Heartbeat in Vigilmon with interval 30 minutes.
  2. Run the script every 10 minutes.

Add this validation step to your workflow when editing the config:

# Before reloading
process-compose validate --config process-compose.yaml && \
  curl -X POST http://localhost:8080/api/v1/process/reload

Step 7: Environment Variable Injection Health

Process Compose manages per-process environment variables, including reading from .env files or secret managers. If an env file is missing or malformed, the process may start with incomplete configuration — often leading to subtle runtime failures rather than a startup crash.

#!/bin/bash
# pc-env-health.sh — run every 10 minutes

# Check that all expected .env files are readable
ENV_FILES=(".env" ".env.local" ".env.production")
ALL_OK=true

for f in "${ENV_FILES[@]}"; do
  if [ -f "$f" ] && ! [ -r "$f" ]; then
    ALL_OK=false
    break
  fi
done

if $ALL_OK; then
  curl -sf https://vigilmon.online/heartbeat/pc-env-xyz
fi
  1. Add a Cron Heartbeat in Vigilmon with interval 15 minutes.
  2. Schedule the script every 5 minutes.

Step 8: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon.
  2. Add Slack for team-visible process failure alerts.
  3. For the API / web UI HTTP monitor, set Consecutive failures before alert to 2 — Process Compose restarts within a few seconds on most failure modes.
  4. For individual process heartbeats, set 1 missed ping — a stopped critical process is always urgent.
  5. For disk space and config heartbeats, set 2 missed pings to absorb script execution delays.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP uptime | http://localhost:8080/api/v1/processes | Process Compose API down | | All processes heartbeat | Heartbeat URL (5m interval) | Any process not Running | | Per-process heartbeat | Heartbeat URL (5m interval) | Critical process exit | | Restart count heartbeat | Heartbeat URL (15m interval) | Crash loop detection | | Readiness heartbeat | Heartbeat URL (10m interval) | Stuck startup chain | | Log disk heartbeat | Heartbeat URL (60m interval) | Log storage exhaustion | | Config validation heartbeat | Heartbeat URL (30m interval) | Invalid config after reload | | Env injection heartbeat | Heartbeat URL (15m interval) | Missing or unreadable env files |

Process Compose brings order to the chaos of running multiple local processes — but that order depends on its API being healthy, processes staying alive, and its configuration staying valid. With Vigilmon monitoring every layer, you'll know the moment your development environment starts degrading instead of discovering it when a cascading failure surfaces in your application.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles