Introduction

Health for Laravel adds health endpoints to a Laravel application: Kubernetes liveness, readiness and startup probes, a Prometheus scrape endpoint, JSON system metrics, and an optional HTML dashboard. It ships with 10 built-in health checks, and everything is configured from config/health.php.

Features

• Kubernetes Probes — liveness, readiness, and startup endpoints
• Prometheus Metrics — Prometheus text format at /health/metrics
• JSON Metrics — structured system metrics API
• HTML Dashboard — optional status page with no external assets
• 10 Built-in Checks — database, cache, queue, storage, Redis, environment, schedule, CPU, memory, disk space
• Custom Checks — implement the HealthCheck contract
• Replacing the Runner — decorate or swap the RunsHealthChecks contract
• Token & IP Auth — protect endpoints with bearer tokens and IP allowlists
• Response Caching — configurable TTL to reduce overhead
• Container Awareness — automatic cgroup detection for Docker/Kubernetes
• Testing Helpers — fake the runner and system metrics in your tests

How It Works

The package registers health check endpoints under a configurable prefix (default: /health). Each probe endpoint runs its own set of checks and returns:

• 200 — every check is ok or warning
• 503 — at least one check is critical or unknown

You assign checks to probes based on their purpose:

• Liveness (/health) — is the process stuck? Failure triggers a container restart. Keep this minimal — typically just the database.
• Readiness (/health/ready) — can this pod serve traffic? Failure removes the pod from the load balancer but keeps it running. Include all dependencies here.
• Startup (/health/startup) — has the app finished booting? Kubernetes stops calling it once it succeeds.

This distinction matters. A Redis check on liveness means a Redis outage restarts all your pods — turning a dependency blip into a full application outage. See Kubernetes Probes for detailed guidance, and Architecture for how a request flows through the package.

Documentation

• Getting started — Requirements, Installation, Quick Start, Testing
• Configuration — Configuration Reference
• Core concepts — Architecture, Caching, System Metrics
• Health checks — Overview and one page per built-in check
• Endpoints — Overview, Kubernetes Probes, Prometheus Metrics, JSON Metrics, Dashboard
• Extension points — Custom Checks, Replacing the Runner
• Security — Endpoint Security
• Upgrading — Upgrade guide, Changelog