tutorial

How to Monitor Gitpod with Vigilmon (Workspace Startup Latency, Prebuild Health + Alerts)

Gitpod is a cloud development environment (CDE) platform that launches fully configured, containerised workspaces in seconds — directly from any Git reposito...

Gitpod is a cloud development environment (CDE) platform that launches fully configured, containerised workspaces in seconds — directly from any Git repository. Whether you're using Gitpod Cloud, Gitpod Dedicated (managed), or Gitpod Self-Hosted on your own Kubernetes cluster, the platform handles workspace orchestration, prebuilds, and IDE proxying so developers can open a browser tab and immediately be productive.

When Gitpod has an incident, the blast radius is enormous: every developer trying to start a workspace or reconnect to a running one is blocked simultaneously. In this tutorial you'll set up external monitoring for Gitpod's critical paths using Vigilmon — free tier, no credit card required.

Why Gitpod needs external monitoring

Gitpod's own status page (status.gitpod.io for Gitpod Cloud) and internal Prometheus/Grafana dashboards tell you what the platform operator knows. External monitoring tells you what your developers see from their network and DNS context.

Common Gitpod failure modes that external monitoring catches first:

  • Workspace startup degradation — workspace boot time spikes from 10 seconds to 3 minutes when Kubernetes node autoscaling is slow or the container registry is rate-limiting image pulls; no alert fires internally until SLO thresholds are breached, but developers notice immediately
  • IDE proxy unavailable — Gitpod proxies VS Code, JetBrains, and Theia connections through its gateway; if the proxy layer degrades, developers see blank IDEs or authentication loops while workspace status shows Running
  • Prebuild pipeline stalled — prebuilds run in the background to warm up workspaces; when the prebuild pipeline backs up, workspace startup latency spikes for everyone affected by the congested template
  • DNS resolution failure — Gitpod Self-Hosted uses wildcard DNS (*.ws.gitpod.example.com); a DNS misconfiguration makes all workspace connections fail even though the cluster is healthy
  • Workspace availability drop — a percentage of running workspaces become unresponsive while Gitpod's control plane doesn't reflect this; users get connection timeouts when reopening

These are the gaps between what a status page shows and what users experience. External monitoring closes them.

What you'll need

  • Access to your Gitpod deployment (Self-Hosted or Dedicated)
  • Your Gitpod domain and API endpoint
  • A free Vigilmon account — sign up takes 30 seconds

Step 1: Monitor the Gitpod dashboard and API availability

The Gitpod dashboard is the entry point for every developer. If it's down, nobody can start, access, or manage workspaces.

Dashboard availability

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. URL: https://gitpod.example.com (your Gitpod Self-Hosted domain) or https://gitpod.io (Gitpod Cloud)
  4. Interval: 1 minute
  5. Expected status code: 200
  6. Save the monitor

API health endpoint

Gitpod Self-Hosted exposes an internal health endpoint:

# Check Gitpod server health
curl -s https://gitpod.example.com/api/version
# {"version":"2024.01.0"}

# Or the liveness probe used by Kubernetes
curl -s https://gitpod.example.com/live
# OK

Add a second HTTP monitor for https://gitpod.example.com/live with expected body containing OK.

Why multi-region consensus matters here

Gitpod Self-Hosted often runs behind a reverse proxy or cloud load balancer. A single probe failure from one Vigilmon region might be a transient network issue on one cloud provider's path — not a real Gitpod outage. Vigilmon uses multi-region consensus: multiple independent probes from different geographic locations must agree that Gitpod is unreachable before an alert fires.

This means you get paged only for real incidents, not for transient network blips affecting a single monitoring probe.

Step 2: Monitor workspace startup latency

Workspace startup latency is the most user-visible performance metric for Gitpod. When it degrades, developers spend more time waiting than working. Set up a probe that times real workspace starts.

Gitpod CLI probe

Gitpod provides a CLI you can use in automated probes:

#!/usr/bin/env bash
# gitpod-startup-probe.sh — run every 10 minutes

GITPOD_URL="https://gitpod.example.com"
GITPOD_TOKEN="${GITPOD_API_TOKEN}"
PROBE_REPO="https://github.com/yourorg/gitpod-probe-repo"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_STARTUP_HEARTBEAT_ID"
MAX_STARTUP_SECONDS=120  # 2-minute SLA for prebuild workspaces

start_time=$(date +%s)

# Start a workspace (Gitpod API v1)
workspace_id=$(curl -s -X POST \
  -H "Authorization: Bearer $GITPOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"contextUrl\": \"$PROBE_REPO\", \"startSpec\": {}}" \
  "${GITPOD_URL}/api/gitpod.v1.WorkspaceService/CreateAndStartWorkspace" | \
  jq -r '.workspaceId')

if [ -z "$workspace_id" ] || [ "$workspace_id" = "null" ]; then
  echo "Failed to create workspace"
  exit 1
fi

echo "Created workspace: $workspace_id"

# Poll until running or timeout
while true; do
  elapsed=$(( $(date +%s) - start_time ))
  if [ $elapsed -gt $MAX_STARTUP_SECONDS ]; then
    echo "Startup timed out after ${elapsed}s"
    # Stop the probe workspace
    curl -s -X POST \
      -H "Authorization: Bearer $GITPOD_TOKEN" \
      "${GITPOD_URL}/api/gitpod.v1.WorkspaceService/StopWorkspace" \
      -d "{\"workspaceId\": \"$workspace_id\"}"
    exit 1
  fi

  status=$(curl -s \
    -H "Authorization: Bearer $GITPOD_TOKEN" \
    "${GITPOD_URL}/api/gitpod.v1.WorkspaceService/GetWorkspace?workspaceId=${workspace_id}" | \
    jq -r '.workspace.status.phase')

  echo "Status after ${elapsed}s: $status"

  if [ "$status" = "PHASE_RUNNING" ]; then
    echo "Workspace started in ${elapsed}s"
    break
  fi

  sleep 5
done

# Send success heartbeat
curl -s "$HEARTBEAT_URL" -d "startup_seconds=$(( $(date +%s) - start_time ))"

# Stop the probe workspace
curl -s -X POST \
  -H "Authorization: Bearer $GITPOD_TOKEN" \
  "${GITPOD_URL}/api/gitpod.v1.WorkspaceService/StopWorkspace" \
  -d "{\"workspaceId\": \"$workspace_id\"}"

Set up a cron job to run this probe every 10 minutes from a host outside your Gitpod cluster:

*/10 * * * * /opt/probes/gitpod-startup-probe.sh >> /var/log/gitpod-probe.log 2>&1

In Vigilmon, create a Heartbeat monitor for this probe with a 15-minute grace window. A missed heartbeat means workspace startup is broken or exceeding your SLA.

Step 3: Monitor the prebuild pipeline

Gitpod prebuilds run workspace initialization tasks in the background so workspaces start instantly. A stalled prebuild pipeline means developers wait through the full setup time — sometimes 5–10 minutes — instead of the expected 10 seconds.

Check prebuild status via API

#!/usr/bin/env bash
# gitpod-prebuild-probe.sh

GITPOD_URL="https://gitpod.example.com"
GITPOD_TOKEN="${GITPOD_API_TOKEN}"
PREBUILD_HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_PREBUILD_HEARTBEAT_ID"

# Check status of recent prebuilds
recent_prebuilds=$(curl -s \
  -H "Authorization: Bearer $GITPOD_TOKEN" \
  "${GITPOD_URL}/api/gitpod.v1.PrebuildService/ListPrebuilds" | \
  jq '.prebuilds[:10]')

# Count failed prebuilds
failed_count=$(echo "$recent_prebuilds" | jq '[.[] | select(.status.phase == "PHASE_FAILED")] | length')
queued_count=$(echo "$recent_prebuilds" | jq '[.[] | select(.status.phase == "PHASE_QUEUED")] | length')

if [ "$failed_count" -gt 3 ]; then
  echo "Too many failed prebuilds: $failed_count"
  exit 1
fi

if [ "$queued_count" -gt 10 ]; then
  echo "Prebuild queue backlogged: $queued_count waiting"
  exit 1
fi

curl -s "$PREBUILD_HEARTBEAT_URL"

Create a second Heartbeat monitor in Vigilmon with a 15-minute grace window for prebuild health. If the prebuild pipeline backs up or consistently fails, the heartbeat stops and you get alerted before developers start complaining about slow workspace starts.

Step 4: Monitor workspace availability and IDE proxy responsiveness

A Gitpod workspace reports Running but the IDE might be completely unreachable if the proxy layer is having issues. Monitor actual IDE proxy endpoints.

IDE proxy health check

When a Gitpod workspace is running and serves a web server on port 3000, the workspace URL format is typically:

https://3000-<workspace-id>.<cluster-hostname>

You can monitor the proxy's health by checking whether workspace-routed URLs resolve and respond correctly.

Create a workspace that serves a tiny health endpoint permanently:

# .gitpod.yml in your probe repository
tasks:
  - init: npm install
    command: |
      node -e "
        const http = require('http');
        const server = http.createServer((req, res) => {
          if (req.url === '/health') {
            res.writeHead(200, {'Content-Type': 'application/json'});
            res.end(JSON.stringify({status: 'ok', ts: Date.now()}));
          } else {
            res.writeHead(404);
            res.end();
          }
        });
        server.listen(3000, () => console.log('Health probe listening on :3000'));
      "

ports:
  - port: 3000
    visibility: public

Once this probe workspace is running, note its URL and add it to Vigilmon:

  1. Go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. URL: https://3000-your-probe-workspace-id.ws.gitpod.example.com/health
  4. Interval: 1 minute
  5. Expected body: "status":"ok"
  6. Save

This monitor validates that the entire Gitpod path — DNS, proxy, workspace agent, and application — is working end-to-end from an external vantage point.

Configure alert channels

In Vigilmon, go to Alert Channels → Add Channel:

  • Email — platform team on-call address for immediate notification
  • Webhook — Slack #gitpod-alerts or PagerDuty for escalation

Step 5: Monitor DNS for wildcard workspace routing

Gitpod Self-Hosted uses wildcard DNS (*.ws.gitpod.example.com) to route workspace connections. A DNS misconfiguration silently breaks all workspace access while the cluster appears healthy.

DNS health check

The simplest way to validate wildcard DNS is to check that workspace URLs resolve:

# Run this as a periodic check from outside your cluster
nslookup test-workspace.ws.gitpod.example.com
# Expects to resolve to your ingress controller or load balancer IP

# Or with dig
dig +short any-workspace.ws.gitpod.example.com
# Should return your ingress IP

Set up a probe script:

#!/usr/bin/env bash
# gitpod-dns-probe.sh

DOMAIN="test.ws.gitpod.example.com"
EXPECTED_IP="203.0.113.1"  # Your ingress controller IP
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_DNS_HEARTBEAT_ID"

resolved_ip=$(dig +short "$DOMAIN" | head -1)

if [ "$resolved_ip" != "$EXPECTED_IP" ]; then
  echo "DNS resolution failed: expected $EXPECTED_IP, got $resolved_ip"
  exit 1
fi

curl -s "$HEARTBEAT_URL"

Run this every 5 minutes from a host outside your network (so it uses public DNS, not your internal resolver):

*/5 * * * * /opt/probes/gitpod-dns-probe.sh >> /var/log/gitpod-dns.log 2>&1

Putting it all together

| Monitor | Type | What it catches | |---------|------|-----------------| | https://gitpod.example.com | HTTP | Dashboard availability, load balancer health | | https://gitpod.example.com/live | HTTP | Core API service health | | Workspace startup latency heartbeat | Heartbeat | Startup SLA breaches, scheduler failures | | Prebuild pipeline heartbeat | Heartbeat | Pipeline backlog, build failures | | https://3000-probe-ws.ws.gitpod.example.com/health | HTTP | End-to-end workspace + proxy health | | DNS wildcard resolution heartbeat | Heartbeat | Wildcard DNS misconfiguration |

Use 1-minute intervals for HTTP monitors and 10–15-minute grace windows for heartbeat monitors.

What's next

  • SSL certificate monitoring — Gitpod Self-Hosted uses wildcard TLS certificates for workspace routing; a lapsed wildcard cert breaks all workspace connections simultaneously. Vigilmon monitors certificate expiry and alerts you 30 days before expiry
  • Status page for developers — publish a Vigilmon status page with all your Gitpod monitors grouped by component; give developers a URL to check themselves before filing platform tickets
  • Multi-cluster monitoring — if you run Gitpod across multiple Kubernetes clusters for geographic distribution or isolation, set up separate Vigilmon monitors per cluster with dedicated alert channels

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.

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