GraphQL health check for reliable API performance and uptime monitoring

A GraphQL health check is a dedicated endpoint or query that verifies whether your GraphQL server is fully operational — not just running, but capable of processing real requests. A robust health check validates critical dependencies: database connectivity, cache availability, and schema integrity. This matters because a server can respond to TCP pings while silently failing to execute any query. Automated infrastructure like Kubernetes, load balancers, and CI/CD pipelines rely on health check results to route traffic, restart failing pods, and gate deployments.

Understanding GraphQL Health Checks: What They Are and Why You Need Them

A GraphQL health check endpoint is the contract between your API and the infrastructure managing it. When a load balancer or Kubernetes scheduler needs to know whether a pod can receive traffic, it doesn’t execute a business query — it calls your health endpoint and reads the HTTP status code. A 200 OK means the server is ready; a 503 Service Unavailable pulls it from rotation.

The minimal JSON response for a healthy GraphQL service looks like this:

{
  "status": "ok",
  "timestamp": "2025-06-01T12:00:00Z",
  "dependencies": {
    "database": "ok",
    "cache": "ok"
  }
}

When a dependency fails, return 503 and mark the component:

{
  "status": "degraded",
  "dependencies": {
    "database": "error: connection timeout after 5000ms",
    "cache": "ok"
  }
}

The key insight is that health checks serve the infrastructure, not developers. They must be fast (under 1 second), unauthenticated, and accurate. A check that returns 200 while the database is down is actively harmful — it creates false confidence and prevents automatic recovery.

Types of GraphQL Health Checks: Liveness vs. Readiness

Understanding the distinction between liveness and readiness checks is the most important design decision when implementing health checks for GraphQL services. They answer fundamentally different questions and trigger different infrastructure responses.

Liveness answers: “Is the process alive and not deadlocked?” A liveness failure tells Kubernetes the pod is unrecoverable — it gets restarted. Only check the bare minimum: HTTP server responding, event loop not blocked.

Readiness answers: “Is this instance ready to handle production traffic?” A readiness failure removes the pod from service endpoints without restarting it, allowing temporary issues (startup lag, cache warming) to resolve naturally. This is where you check database connections, upstream services, and schema loading.

A common mistake is putting database checks inside a liveness probe. If the database goes down, every pod fails its liveness check and gets restarted in a loop — making the outage worse. Readiness probes are built for this: they simply remove the pod from rotation until the database recovers, then automatically restore it.

Implementing Health Checks in Popular GraphQL Servers

Each major GraphQL server handles health checks differently — some provide built-in endpoints, others require middleware. Here’s what you actually need to configure for each.

Apollo Server Health Checks

Apollo Server 4 does not expose a health endpoint by default. You add one via Express middleware before the GraphQL handler:

import express from 'express';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';

const app = express();
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();

// Health check — mount BEFORE GraphQL middleware
app.get('/health', async (req, res) => {
  try {
    // Optional: verify DB connection
    await db.query('SELECT 1');
    res.status(200).json({ status: 'ok' });
  } catch (err) {
    res.status(503).json({ status: 'error', message: err.message });
  }
});

app.use('/graphql', expressMiddleware(server));

“GraphOS Router and Apollo Router Core support a basic HTTP-level health check. This is enabled by default and is served on port 8088 at the URL path /health. This returns a 200 status code if the HTTP server is successfully serving.”
— Apollo GraphQL Docs
Source link

GraphQL-level Health Checks for Apollo Server

GraphQL-level health checks validate more components than an HTTP ping — they exercise schema parsing, the execution engine, and resolver infrastructure. The standard pattern uses { __typename } as a minimal introspection query that requires no resolver logic:

# Send as HTTP GET to avoid CSRF concerns
GET /graphql?query={__typename}

# Expected response when healthy
{ "data": { "__typename": "Query" } }

This approach catches issues like schema compilation errors or resolver initialization failures that an HTTP-only check would miss. However, you must implement CSRF protection when enabling GET requests — use a dedicated query name or a separate unauthenticated endpoint rather than exposing the full GraphQL endpoint unauthenticated.

GraphQL Yoga Server Health Checks

GraphQL Yoga ships with /health and /readiness endpoints enabled out of the box — no configuration needed for basic usage. For custom dependency checks, use the plugin system:

import { createSchema, createYoga } from 'graphql-yoga';
import { useReadinessCheck } from '@graphql-yoga/plugin-readiness-check';

const yoga = createYoga({
  schema,
  plugins: [
    useReadinessCheck({
      endpoint: '/readiness',
      check: async () => {
        // Returns true if ready, false or throws if not
        const dbOk = await db.ping().catch(() => false);
        const cacheOk = await redis.ping().catch(() => false);
        return dbOk && cacheOk;
      },
    }),
  ],
});

Hasura GraphQL Engine Health Checks

“Hasura gives a health check endpoint to monitor the status of the GraphQL API. This is available under the /healthz endpoint for all Hasura projects.”
— Hasura Docs
Source link

Hasura exposes /healthz out of the box. Query it directly:

# Basic health check
curl https://your-hasura-domain/healthz

# Healthy response
{"status":"OK"}

# With metadata consistency check
curl "https://your-hasura-domain/healthz?strict=true"

The strict=true parameter adds metadata consistency validation — useful in production where you want to catch schema drift between the database and Hasura’s tracked tables. The endpoint integrates directly with Prometheus and Datadog via standard HTTP scraping.

GraphQL Mesh Health Checks

GraphQL Mesh is built on GraphQL Yoga and inherits its /health and /readiness endpoints. In Mesh’s layered architecture, readiness checks are especially critical because Mesh federates multiple upstream GraphQL sources — a readiness check should reflect the aggregate health of all of them:

# mesh.config.ts
export const config = {
  serve: {
    healthCheckEndpoint: '/health',
    readinessCheckEndpoint: '/readiness',
  },
  // Custom readiness: validate all upstream sources
};

Configure readiness to check whether all upstream sources have successfully loaded their schemas. A Mesh instance that starts before upstream services are ready should fail readiness until federation is complete.

Custom GraphQL Health Check Implementations

A production-grade health check checks dependencies in parallel to keep response time fast, implements per-dependency timeouts to avoid hanging, and returns structured metadata so monitoring tools can distinguish between a full outage and partial degradation.

import { Router } from 'express';

const healthRouter = Router();

async function checkWithTimeout(fn, timeoutMs = 3000) {
  return Promise.race([
    fn(),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs)
    ),
  ]);
}

healthRouter.get('/health/ready', async (req, res) => {
  const start = Date.now();

  // Run all checks in parallel — don't let one slow check block others
  const [dbResult, cacheResult] = await Promise.allSettled([
    checkWithTimeout(() => db.query('SELECT 1')),
    checkWithTimeout(() => redis.ping()),
  ]);

  const dependencies = {
    database: dbResult.status === 'fulfilled' ? 'ok' : dbResult.reason.message,
    cache: cacheResult.status === 'fulfilled' ? 'ok' : cacheResult.reason.message,
  };

  const healthy = Object.values(dependencies).every(v => v === 'ok');

  res.status(healthy ? 200 : 503).json({
    status: healthy ? 'ok' : 'degraded',
    uptime: process.uptime(),
    responseTime: `${Date.now() - start}ms`,
    dependencies,
  });
});

For services that can operate in a degraded state (e.g., serving cached data when the primary DB is slow), return 200 with "status": "degraded" rather than 503. This keeps the pod in rotation while signaling to monitoring that intervention may be needed.

Testing Health Check Endpoints

Always test both the happy path and failure scenarios. The most common oversight is only testing that health checks return 200 when everything works, never verifying they return 503 when a dependency is down.

# Test healthy state
curl -i http://localhost:4000/health/ready

# Expected: HTTP/1.1 200 OK
# Body: {"status":"ok","dependencies":{"database":"ok","cache":"ok"}}

# Simulate DB failure (stop your local DB), then:
curl -i http://localhost:4000/health/ready

# Expected: HTTP/1.1 503 Service Unavailable
# Body: {"status":"degraded","dependencies":{"database":"error: ...","cache":"ok"}}

In CI/CD pipelines, add a post-deploy step that polls the health endpoint until it returns 200 or times out — this is your deployment gate. Combine it with a synthetic failure test: temporarily kill the database container and assert your health endpoint returns 503 before restoring it.

Integrating Health Checks with Deployment Environments

Health checks are the primary interface between your GraphQL service and the infrastructure managing it. Getting this integration right is what enables zero-downtime deployments, automatic recovery, and reliable rolling updates.

Kubernetes Integration

Configure separate liveness and readiness probes pointing to different endpoints. Here’s a production-ready pod spec for a GraphQL service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: graphql-api
spec:
  template:
    spec:
      containers:
        - name: graphql-api
          image: your-graphql-image:latest
          ports:
            - containerPort: 4000
          livenessProbe:
            httpGet:
              path: /health/live    # Only checks: is the HTTP server responding?
              port: 4000
            initialDelaySeconds: 15  # Wait for app startup
            periodSeconds: 20
            failureThreshold: 3
            timeoutSeconds: 5
          readinessProbe:
            httpGet:
              path: /health/ready   # Checks DB, cache, schema
              port: 4000
            initialDelaySeconds: 10
            periodSeconds: 10
            failureThreshold: 3
            timeoutSeconds: 5

For GraphQL services that load large schemas or pre-warm caches on startup, increase initialDelaySeconds generously. A pod that restarts because its liveness probe fired too early (before startup completed) is a common configuration mistake that causes deployment instability.

Docker Health Check Configuration

Add a HEALTHCHECK instruction to your Dockerfile to enable container-level health monitoring:

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

EXPOSE 4000

HEALTHCHECK \
  --interval=30s \
  --timeout=10s \
  --start-period=60s \
  --retries=3 \
  CMD wget -qO- http://localhost:4000/health/ready || exit 1

CMD ["node", "server.js"]

Docker health status is visible via docker inspect --format='{{.State.Health.Status}}' container_name. In Kubernetes deployments, Docker health checks complement pod-level probes — they provide container runtime visibility useful for local debugging and standalone Docker Compose environments.

Using in Containerized Environments

The most common health check failure in containerized environments is a server bound to 127.0.0.1 (localhost). Health check requests from Kubernetes or Docker’s health check mechanism originate from outside the container’s network namespace and cannot reach localhost-bound services:

# Wrong — health checks will fail in containers
server.listen(4000, '127.0.0.1');

# Correct — bind to all interfaces
server.listen(4000, '0.0.0.0');
# Or simply:
server.listen(4000);

Verify your service is bound correctly inside a running container:

# Check what interfaces the server is listening on
docker exec container_name netstat -tlnp | grep 4000
# Should show: 0.0.0.0:4000, not 127.0.0.1:4000

Advanced Health Check Strategies

Production systems need more than binary healthy/unhealthy states. Advanced strategies handle the reality that dependencies fail partially, transiently, or in ways that don’t require taking the entire service offline.

Circuit breaking inside health checks prevents cascading failures. If a dependency has failed 5 consecutive times, stop checking it for 30 seconds and report it as “circuit open” rather than hammering a failing service with health check requests. Libraries like opossum implement this pattern for Node.js GraphQL services.

Graceful degradation is the most valuable pattern for high-traffic GraphQL APIs. If your service can serve cached data during a database outage, your health check should return 200 with "status": "degraded" — keeping the pods in rotation while your alerting notifies on-call engineers of the underlying issue.

Logging and Monitoring Health Checks

Log health check failures in structured JSON — successful checks rarely need logging in production, but failures should include enough context for immediate diagnosis:

// Only log failures and slow checks
if (!healthy || responseTime > 500) {
  logger.warn({
    event: 'health_check',
    status: healthy ? 'ok' : 'degraded',
    responseTime,
    dependencies,
    timestamp: new Date().toISOString(),
  });
}

Health check patterns in logs reveal system behavior before it becomes a user-visible incident. Set alerts on sustained failure patterns — not individual failures — to reduce noise. A single 503 from a health check is often a transient network blip; three consecutive 503s from the same pod signal a real problem.

Best Practices and Common Pitfalls

The single most critical principle: your health check must accurately reflect your service’s ability to handle real user requests. A health check that returns 200 while your resolvers are all failing is worse than no health check — it prevents automatic recovery and delays incident response. Build your health checks to fail loudly when the service is genuinely broken, and stay silent when everything works.