Health checks

The HealthPlugin exposes a lightweight endpoint for serverless runtimes like Cloud Run. It tells the platform whether the instance is ready to receive traffic.

Getting started

Register the health() plugin alongside http():

import { application, http, health } from '@putnami/application';

const app = application()
  .use(health())
  .use(http({ port: 3000 }));

await app.start();

The endpoint is available immediately after the application starts:

curl http://localhost:3000/_/health
# → 200 { "status": "ok" }

Endpoint behavior

The health endpoint tracks the application lifecycle automatically:

Application state	HTTP status	Response body
Starting (before start() completes)	503	{ "status": "unavailable" }
Running	200	{ "status": "ok" }
Shutting down (after stop() is called)	503	{ "status": "unavailable" }

Cloud Run uses these status codes to decide whether to route traffic to the instance. A 503 tells the platform the instance is not ready.

Configuration

health({
  path: '/_/health', // default
});

Option	Type	Default	Description
path	string	/_/health	The endpoint path

Middleware bypass

The health endpoint is registered as a prepended middleware. It runs before authentication, CORS, rate limiting, and any other middleware you configure. This ensures the probe is always reachable, even if other middleware would reject unauthenticated requests.

const app = application()
  .use(health())
  .use(http({ port: 3000 }));

const httpPlugin = app.getPlugin(HttpPlugin);

// These middleware will NOT run for /_/health requests
httpPlugin.use(authMiddleware);
httpPlugin.use(rateLimitMiddleware);

Cloud Run configuration

Point the startup and liveness probes to /_/health:

apiVersion: serving.knative.dev/v1
kind: Service
spec:
  template:
    spec:
      containers:
        - image: my-app
          startupProbe:
            httpGet:
              path: /_/health
            initialDelaySeconds: 0
            periodSeconds: 2
            failureThreshold: 10
          livenessProbe:
            httpGet:
              path: /_/health
            periodSeconds: 10

Startup probe

Checks that the instance is ready to serve. Runs repeatedly until it gets a 200, then stops. Configure failureThreshold × periodSeconds to match your worst-case startup time.

Liveness probe

Checks that the instance is still healthy after startup. If it starts returning 503 (e.g., during graceful shutdown), Cloud Run stops routing new requests to it.

Why /_/health

The /_/ prefix is a reserved namespace for framework-level endpoints. It avoids collision with application routes and signals that the endpoint is infrastructure, not business logic.

Observability beyond health

For metrics, error rates, and response durations, use the TelemetryPlugin. It auto-instruments HTTP requests and lets you record custom counters, gauges, and histograms. Telemetry data is pushed to the Putnami backend automatically.

Related guides

• Telemetry
• Plugins & lifecycle
• HTTP & middleware
• Deploy an app