Gateway Monitoring

Overview

Checkpoint's edge Gateway exposes health endpoints and dashboard monitoring. Use these to verify your integration is working, track performance, and troubleshoot issues.

If you're running Middleware instead of (or alongside) the Gateway, the health endpoints and status table below don't apply to it — see Monitoring a Middleware deployment for what's available there.

Gateway Health Endpoints

The Gateway exposes three health endpoints for monitoring and orchestration:

Health Check

GET /__gateway/health

Returns the Gateway's operational status:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-02-01T12:00:00Z",
  "region": "SFO",
  "environment": "production"
}

Readiness Probe

GET /__gateway/ready

Kubernetes-style readiness probe. Returns 200 with { "ready": true } when the Gateway can reach its routing store, or 503 with { "ready": false, "error": "KV namespace unavailable" } otherwise. Use this for load balancer health checks.

Version Info

GET /__gateway/version

Returns version and environment information:

{
  "version": "1.0.0",
  "environment": "production"
}

WASM Detection Health

GET /__detect/health

Reports the detection engine's own initialization and fault status, separately from /__gateway/health's worker-liveness check:

{
  "status": "healthy",
  "wasmVersion": "1.0.0",
  "wasmInitialized": true,
  "environment": "production",
  "timestamp": "2026-02-01T12:00:00Z"
}

Returns 200 when the engine initialized and is not currently faulting. Returns 503 with status: "degraded" (initialized but faulting) or status: "unhealthy" (initialization failed) otherwise — the HTTP status always matches the body's health signal, so a load balancer can key off status code alone.

Dashboard Monitoring

Gateway Status

The Enforce settings page shows real-time status for each Gateway domain:

The status maps to the underlying provisioning state machine (pending → dns_pending → ssl_pending → active, plus inactive and error):

Detection Metrics

View detection activity on the Activity and Analytics screens in the left rail (legacy tab names: Monitor and Analyze):

• Real-time feed — Live detection events as they happen
• Detection rate — Percentage of traffic classified as agents/bots
• Classification breakdown — Distribution across detection classes
• Confidence distribution — Histogram of confidence scores
• Top agents — Most frequently detected agent types

See Analytics & Reporting for detailed analytics.

Uptime Monitoring

For production deployments, configure external uptime monitoring against the health endpoints:

# Check Gateway health
curl -s https://shop.example.com/__gateway/health | jq .status
# Expected: "healthy"

# Check readiness
curl -s -o /dev/null -w "%{http_code}" https://shop.example.com/__gateway/ready
# Expected: 200

Recommended Checks

Monitoring a Middleware deployment

Middleware doesn't expose /__gateway/* or /__detect/health — there's no edge worker to probe. What's available instead depends on which entry point you're running:

• Response headers (withCheckpoint, the in-process engine path). Sets X-Checkpoint-* headers (for example X-Checkpoint-Engine, X-Checkpoint-Ruleset-Hash) plus a __checkpoint_verdict cookie, byte-identical across Next.js and Express. In enforcementMode: 'observe', it additionally stamps X-Checkpoint-Would-Have-Been so you can inspect what enforcement would have done. See Response Headers.
• Response headers (withCheckpointApi, the SaaS-gateway path, Next.js only). Sets KYA-Detected / KYA-Confidence / KYA-Agent on pass-through instead — this path proxies detection to the edge Gateway rather than running the engine in-process.
• The storage adapter (Express only). @kya-os/checkpoint-express exports MemoryStorageAdapter, RedisStorageAdapter, and createStorageAdapter; wire one up in your onResult callback to record recent events/sessions in-process (storeEvent / getRecentEvents, storeSession / getActiveSessions). This is a local diagnostic surface, not a dashboard one — the in-memory adapter doesn't survive a restart. See Storage adapters.
• Dashboard Activity. When a project API key is configured, both entry points asynchronously report each detection to the same ingestion path the Gateway uses, so Middleware-detected traffic appears alongside Gateway traffic on the Activity and Analytics screens (see Detection Metrics above). Reporting is fire-and-forget and fails silently by default — pass debug: true in the SDK config to surface reporting failures via console.warn.

Troubleshooting

Gateway Shows "Pending"

The DNS record hasn't been detected yet.

• Verify your DNS record points to cname.checkpoint-gateway.ai
• Check for typos in the record name or value
• Wait for DNS propagation (check with dig or nslookup)

dig shop.example.com CNAME +short

Gateway Shows "Error"

Common causes:

• DNS misconfiguration — Conflicting records for the same domain
• Origin unreachable — Your origin server is down or blocking Cloudflare IPs
• SSL issue — CAA records preventing certificate issuance

WASM Not Initialized

The WASM detection module failed to load.

• Check the /__detect/health endpoint — wasmInitialized: true means the engine is up; a 503 with status: "degraded" or "unhealthy" indicates a faulting or failed engine
• This typically resolves on its own as Cloudflare retries initialization
• If persistent, contact support

High Latency

Detection latency should be under 5ms (p95) for the Gateway.

• Check if signature verification is adding latency (key fetch not cached)
• Review the Cloudflare region serving your traffic
• Ensure your origin server responds quickly (Gateway latency includes origin response time)

Detection Not Appearing in Dashboard

• Verify your project ID matches the Gateway configuration
• Check that the Gateway status is Active
• Look for errors on the Activity screen
• Confirm the request is going through the Gateway (not bypassing DNS)

Next Steps

• Gateway Enforcement — Setup and DNS configuration
• Policies — Configure enforcement rules
• Dashboard Analytics — Detailed detection analytics