Laravel Health: Kubernetes Probes & Prometheus Metrics | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Health for Laravel: Kubernetes Probes and Prometheus Metrics On this page 1. [ What Is Health for Laravel? ](#what-is-health-for-laravel) 2. [ Key Features at a Glance ](#key-features-at-a-glance) 3. [ Assigning Checks to Each Kubernetes Probe ](#assigning-checks-to-each-kubernetes-probe) 4. [ Prometheus Metrics ](#prometheus-metrics) 5. [ Monitoring the Task Scheduler ](#monitoring-the-task-scheduler) 6. [ Writing a Custom Check ](#writing-a-custom-check) 7. [ Installation ](#installation) 8. [ Real Takeaways ](#real-takeaways) ![Health for Laravel: Kubernetes Probes and Prometheus Metrics](https://cdn.msaied.com/693/9f287c301c3bfdda9f1fe3d40ab40521.png) [ Laravel ](https://msaied.com/articles?category=laravel) [ Composer Pacakge ](https://msaied.com/articles?category=composer-pacakge) #Laravel #Kubernetes #Prometheus #Health Checks #Composer Package #Monitoring Health for Laravel: Kubernetes Probes and Prometheus Metrics ============================================================== 20 Sep 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said Table of contents 1. [ 01 What Is Health for Laravel? ](#what-is-health-for-laravel) 2. [ 02 Key Features at a Glance ](#key-features-at-a-glance) 3. [ 03 Assigning Checks to Each Kubernetes Probe ](#assigning-checks-to-each-kubernetes-probe) 4. [ 04 Prometheus Metrics ](#prometheus-metrics) 5. [ 05 Monitoring the Task Scheduler ](#monitoring-the-task-scheduler) 6. [ 06 Writing a Custom Check ](#writing-a-custom-check) 7. [ 07 Installation ](#installation) 8. [ 08 Real Takeaways ](#real-takeaways) What Is Health for Laravel? --------------------------- [`cboxdk/laravel-health`](https://github.com/cboxdk/laravel-health) is a package by Sylvester Damgaard that goes well beyond Laravel's built-in `/up` route. It registers three Kubernetes-ready probe endpoints, a Prometheus scrape target, and a CLI command — all configurable from a single `config/health.php` file. ### Key Features at a Glance - **Three Kubernetes probe endpoints**: `/health` (liveness), `/health/ready` (readiness), `/health/startup` - **10 built-in checks**: database, cache, queue, storage, Redis, environment, schedule, CPU, memory, and disk space - **Prometheus metrics** at `/health/metrics` with per-check status and duration gauges - **Container-aware memory reporting** via cgroup v1 and v2 - **JSON metrics** at `/health/metrics/json` including the pod name - **`health:check` Artisan command** that exits non-zero on failure - **Response caching** (10-second default) and an optional HTML dashboard at `/health/ui` Assigning Checks to Each Kubernetes Probe ----------------------------------------- Each probe type gets its own list of checks in `config/health.php`: ```php use Cbox\LaravelHealth\Checks\{ CacheCheck, DatabaseCheck, EnvironmentCheck, QueueCheck, RedisCheck, StorageCheck }; 'checks' => [ 'liveness' => [DatabaseCheck::class], 'readiness' => [ DatabaseCheck::class, CacheCheck::class, RedisCheck::class, QueueCheck::class, StorageCheck::class, ], 'startup' => [EnvironmentCheck::class], ], ``` A probe endpoint returns `200` when every check is `ok` or `warning`, and `503` when any check is `critical` or `unknown`. Your Kubernetes deployment manifest maps each path to the correct probe: ```yaml livenessProbe: httpGet: path: /health port: 80 periodSeconds: 15 readinessProbe: httpGet: path: /health/ready port: 80 periodSeconds: 10 startupProbe: httpGet: path: /health/startup port: 80 failureThreshold: 30 periodSeconds: 5 ``` Prometheus Metrics ------------------ The `/health/metrics` endpoint exposes two gauges per check: - `app_health_check_status` — `1.0` (ok), `0.5` (warning), `0.0` (critical/unknown) - `app_health_check_duration_seconds` — how long the check took The `app` prefix is controlled by the `HEALTH_PROMETHEUS_NAMESPACE` environment variable. System-level metrics (load averages, memory, disk per mount, network per interface, uptime) come from the companion `cboxdk/system-metrics` package. Inside a container, five additional metrics are added, including `app_container_memory_limit_bytes`, `app_container_cpu_quota`, and `app_container_oom_kills_total`. Monitoring the Task Scheduler ----------------------------- `ScheduleCheck` reads a heartbeat timestamp written by the `health:heartbeat` Artisan command. Schedule it in `routes/console.php`: ```php Schedule::command('health:heartbeat')->everyMinute(); ``` The check returns `critical` when the heartbeat is older than `max_age_minutes` (default: 5). Add it to the readiness list and Kubernetes will stop routing traffic to any pod whose scheduler has stalled. Writing a Custom Check ---------------------- Extend `BaseCheck`, implement `run()`, and return a `CheckResult`: ```php namespace App\Health; use Cbox\LaravelHealth\Checks\BaseCheck; use Cbox\LaravelHealth\DataTransferObjects\CheckResult; use Illuminate\Support\Facades\Http; class PaymentGatewayCheck extends BaseCheck { public function run(): CheckResult { try { $response = Http::timeout(5)->get('https://payments.example.com/health'); } catch (\Throwable $e) { return CheckResult::critical($this->name(), $e->getMessage()); } return $response->successful() ? CheckResult::ok($this->name()) : CheckResult::critical($this->name(), "HTTP {$response->status()}"); } } ``` `CheckResult` has four named constructors — `ok()`, `warning()`, `critical()`, and `unknown()` — each accepting an optional metadata array that appears in JSON responses. Installation ------------ Requires PHP 8.3 and Laravel 11, 12, or 13: ```bash composer require cboxdk/laravel-health php artisan vendor:publish --tag="health-config" ``` Verify the setup from the terminal: ```bash php artisan health:check php artisan health:check --endpoint=readiness ``` The `HEALTH_PREFIX` environment variable changes the `/health` base path if you prefer paths like `/livez` or `/readyz`. ### Real Takeaways - Separate check lists per probe type give Kubernetes precise restart and traffic-routing signals. - The Prometheus endpoint requires no extra exporter — just point your scrape config at `/health/metrics`. - Container-aware cgroup metrics mean memory figures reflect actual container limits, not host totals. - `ScheduleCheck` + `health:heartbeat` provides a simple, cache-backed scheduler watchdog. - Custom checks are a single class with four possible result states and optional metadata. --- Source: [Health for Laravel: Kubernetes Probes and Prometheus Metrics — Laravel News](https://laravel-news.com/laravel-health-kubernetes-prometheus) Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fhealth-for-laravel-kubernetes-probes-and-prometheus-metrics&text=Health+for+Laravel%3A+Kubernetes+Probes+and+Prometheus+Metrics) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fhealth-for-laravel-kubernetes-probes-and-prometheus-metrics) Frequently Asked Questions ---------------------------- 3 questions Q01 What is the difference between the liveness and readiness probe endpoints in this package? The liveness probe at `/health` tells Kubernetes whether to restart the container — a failure triggers a restart. The readiness probe at `/health/ready` tells Kubernetes whether to route traffic to the pod; a failure removes the pod from the load balancer without restarting it. You assign a different set of checks to each probe in `config/health.php`. Q02 How does the ScheduleCheck know whether the Laravel task scheduler is running? You schedule the `health:heartbeat` Artisan command to run every minute. It writes a timestamp to the cache. `ScheduleCheck` reads that timestamp and returns `critical` if it is older than `max_age_minutes` (default: 5), giving Kubernetes a signal to stop routing traffic to a pod with a stalled scheduler. Q03 Does the Prometheus metrics endpoint require a separate exporter process? No. The `/health/metrics` endpoint is served directly by your Laravel application. Prometheus scrapes it like any other HTTP target. System and container metrics are provided by the `cboxdk/system-metrics` companion package, so no sidecar or external exporter is needed. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Live Stream: Building a Social Network in PHP in 48 Hours](https://cdn.msaied.com/692/e20cfd66bbb0473d2084f86b7f5e4dcc.png) PHP Live Stream Nuno Maduro ### Live Stream: Building a Social Network in PHP in 48 Hours Nuno Maduro, Brent Roose, and Matthieu Napoli will build a full social network in PHP live from the JetBrains... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 22 Sep 2026 2 min read Read ](https://msaied.com/articles/live-stream-building-a-social-network-in-php-in-48-hours) [ ![Livewire v4.4.6 Released: Bug Fixes, Test Improvements, and Alpine v3.17.4](https://cdn.msaied.com/689/454c52282f3ef5d585905e5952ca969c.png) Livewire Laravel Alpine.js ### Livewire v4.4.6 Released: Bug Fixes, Test Improvements, and Alpine v3.17.4 Livewire v4.4.6 ships with 18 changes including validation performance improvements, better test assertions, k... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 21 Sep 2026 3 min read Read ](https://msaied.com/articles/livewire-v446-released-bug-fixes-test-improvements-and-alpine-v3174) [ ![Laravel 14: New Features, Breaking Changes, and PHP 8.4 Requirement](https://cdn.msaied.com/688/2dfe8f11b0bef35c0ee6db912004209f.png) Laravel 14 PHP 8.4 Breaking Changes ### Laravel 14: New Features, Breaking Changes, and PHP 8.4 Requirement Laravel 14 is expected in Q1 2027 and will require PHP 8.4. Here is everything known so far from the master br... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 21 Sep 2026 4 min read Read ](https://msaied.com/articles/laravel-14-new-features-breaking-changes-and-php-84-requirement) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)