Monitoring KrakenD with Vigilmon

KrakenD is a stateless, ultra-high-performance API gateway written in Go that aggregates, transforms, and proxies requests to your backend microservices. It processes millions of requests per second with near-zero latency overhead — but when a misconfigured deployment, OOM kill, or upstream backend change takes the gateway down, every API consumer is affected simultaneously. Vigilmon provides the external availability layer that KrakenD itself cannot: independent health checks from multiple geographic regions, endpoint-level probes, and instant alerting when your gateway stops serving traffic.

What You'll Set Up

• HTTP health probe for the KrakenD gateway process
• Endpoint-level monitor for a critical API route
• TCP port check for the gateway listener
• Heartbeat to confirm end-to-end request processing
• Alerting recommendations for API gateway failure modes

Prerequisites

• KrakenD CE or EE deployed (Docker, Kubernetes, or bare metal)
• KrakenD exposed on a reachable hostname or IP
• A free Vigilmon account

Step 1: Enable and Probe the KrakenD Health Endpoint

KrakenD exposes a /__health endpoint on the same port as the API (default: 8080). It returns HTTP 200 with a JSON body when the gateway is running:

curl http://localhost:8080/__health
# {"agents":{},"now":"2024-01-15T10:23:00Z","status":"ok"}

If you deploy KrakenD with TLS or behind a reverse proxy, the health endpoint is available at the same host:

curl https://api.yourdomain.com/__health

Add a monitor in Vigilmon:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter https://api.yourdomain.com/__health.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Optionally set Response body contains to "status":"ok".
7. Click Save.

For Kubernetes deployments, expose /__health through your Ingress or LoadBalancer. KrakenD's health endpoint is served on the same port as the API — no separate port needed.

# KrakenD deployment health probe alignment
livenessProbe:
  httpGet:
    path: /__health
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /__health
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 5

Vigilmon's external probe catches failures that Kubernetes liveness probes miss: DNS resolution failures, load balancer routing issues, and TLS certificate expiry.

Step 2: Monitor a Critical API Endpoint

The /__health check tells you the gateway process is alive. But it doesn't tell you whether a specific route is configured correctly and the upstream backend is reachable. Add a monitor for your most critical API endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL of a critical read-only endpoint: https://api.yourdomain.com/v1/products (or any stable GET endpoint).
3. Set Expected HTTP status to 200.
4. Set Check interval to 1 minute.
5. Click Save.

This catches a class of failures that /__health misses: KrakenD is running but a configuration reload removed or broke a specific route, or an upstream backend the route depends on is down.

Choosing the right endpoint to monitor:

• Pick a GET endpoint with no side effects
• Choose one that exercises a representative upstream call
• Avoid endpoints that require authentication (or configure Vigilmon with the required Authorization header under Advanced → Custom headers)

Step 3: TCP Port Monitoring

Add a TCP monitor as a lightweight, low-overhead check that the KrakenD listener port is open. This is faster than HTTP and catches OS-level failures (port binding lost after a crash) before the HTTP probe fires:

1. Click Add Monitor → TCP Port.
2. Enter your gateway hostname and port 8080 (or 443 if TLS-terminated).
3. Set Check interval to 1 minute.
4. Click Save.

TCP and HTTP checks together give you a faster mean-time-to-detect: if the TCP check fires but HTTP doesn't, the gateway process is partially degraded. If TCP is healthy but HTTP returns errors, you have an application-level issue.

Step 4: Heartbeat for Configuration Reloads

KrakenD EE supports hot reloads via SIGHUP or the /__reload endpoint. A misconfigured reload can take the gateway down without triggering its own health endpoint (the process restarts before the health probe fires). Set up a heartbeat monitor that your deployment pipeline pings after every successful reload:

In your CI/CD pipeline (GitHub Actions example):

- name: Reload KrakenD config
  run: |
    kubectl rollout restart deployment/krakend -n api-gateway
    kubectl rollout status deployment/krakend -n api-gateway --timeout=120s

- name: Ping Vigilmon heartbeat
  run: |
    curl -fsS https://vigilmon.online/api/heartbeat/<YOUR_HEARTBEAT_ID>

In Vigilmon:

1. Click Add Monitor → Heartbeat.
2. Set Expected interval to match your deployment frequency (e.g., 1 hour if you deploy hourly, 1 day for daily).
3. Set Grace period to 30 minutes.
4. Paste the heartbeat URL into your deployment pipeline.

If a deployment fails mid-way and the heartbeat stops arriving on schedule, Vigilmon alerts — giving you confidence that every successful deployment is recorded externally.

Step 5: Configure Notifications

1. In Vigilmon, go to Settings → Notifications.
2. Add your Slack webhook, PagerDuty integration key, or on-call email.
3. Assign the notification channel to all monitors.
4. Recommended alert delays:
   • /__health HTTP check: 1 minute (gateway process down affects all API consumers)
   • Critical endpoint check: 2 minutes (allow for transient upstream errors)
   • TCP port check: 1 minute
   • Deployment heartbeat: match your deployment cadence + 30 minutes grace

Example Vigilmon webhook payload when /__health goes down:

{
  "monitor_name": "KrakenD /__health",
  "status": "down",
  "url": "https://api.yourdomain.com/__health",
  "started_at": "2024-01-15T10:23:00Z",
  "duration_seconds": 62
}

Route this payload to your incident management system with the gateway hostname pre-filled for faster runbook execution.

KrakenD-Specific Failure Modes to Watch

| Failure mode | Detected by | |---|---| | Gateway process crash | /__health HTTP monitor | | Load balancer / DNS routing failure | /__health from multiple regions | | Route configuration broken after reload | Critical endpoint HTTP monitor | | Port binding lost | TCP port monitor | | Deployment pipeline failure | Heartbeat monitor | | TLS certificate expiry | Vigilmon SSL cert check on the gateway domain |

What You've Built

| Monitor | Type | Checks | |---|---|---| | /__health | HTTP | Gateway process alive and responsive | | Critical API route | HTTP | Specific route configured and upstream healthy | | Gateway TCP port | TCP | Listener port open | | Deployment heartbeat | Heartbeat | Successful deployment confirmation |

This setup gives you layered visibility into KrakenD availability: from OS-level port binding up through application-level route health. With Vigilmon monitoring your API gateway, you'll detect outages in seconds across multiple geographic regions — before API consumers start reporting errors.