Laravel Health: Kubernetes Probes & Prometheus Metrics | Mohamed Said       [Skip to content](#main)  [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public)
- [Projects](https://www.msaied.com/public/projects)
- [Articles](https://www.msaied.com/public/articles)
- [Certificates](https://www.msaied.com/public/certificates)
- [About](https://www.msaied.com/public#about)

           [  Contact](https://www.msaied.com/public#contact) Menu 

Menu
----

Close 

 - [HomeStart here](https://www.msaied.com/public)
- [ProjectsCase studies](https://www.msaied.com/public/projects)
- [ArticlesEngineering notes](https://www.msaied.com/public/articles)
- [CertificatesCredentials](https://www.msaied.com/public/certificates)
- [AboutHow I work](https://www.msaied.com/public#about)
- [ContactGet in touch](https://www.msaied.com/public#contact)

  [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 

 1. [Home](https://www.msaied.com/public)
2. /
3. [Articles](https://www.msaied.com/public/articles)
4. /
5. [Laravel](https://www.msaied.com/public/articles?category=laravel)
6. /
7. Health for Laravel: Kubernetes Probes and Prometheus Metrics

   [Laravel](https://www.msaied.com/public/articles?category=laravel) [Composer Pacakge](https://www.msaied.com/public/articles?category=composer-pacakge) 

 Health for Laravel: Kubernetes Probes and Prometheus Metrics
=============================================================

 The cboxdk/laravel-health package adds dedicated Kubernetes liveness, readiness, and startup probe endpoints plus a Prometheus-scrapable /health/metrics route to any Laravel 11, 12, or 13 application.

 ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 20 Sep 2026 · Updated 23 Sep 2026 · 4 min read

ShareCopy linkCopied

 ![Health for Laravel: Kubernetes Probes and Prometheus Metrics](https://cdn.msaied.com/693/9f287c301c3bfdda9f1fe3d40ab40521.png) 

  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)

 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)

- [Laravel](https://www.msaied.com/public/articles?search=Laravel)
- [Kubernetes](https://www.msaied.com/public/articles?search=Kubernetes)
- [Prometheus](https://www.msaied.com/public/articles?search=Prometheus)
- [Health Checks](https://www.msaied.com/public/articles?search=Health%20Checks)
- [Composer Package](https://www.msaied.com/public/articles?search=Composer%20Package)
- [Monitoring](https://www.msaied.com/public/articles?search=Monitoring)

 Frequently asked questions 
---------------------------

  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`.

   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.

   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.

   ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author
----------------

[Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow.

[About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)  

   [Previous articleDifflock: Lint Laravel Migrations and Diff Your Database Schema](https://www.msaied.com/public/articles/difflock-lint-laravel-migrations-and-diff-your-database-schema) [Next articleBuilding a Laravel Package: Service Providers, Auto-Discovery, and Config Merging](https://www.msaied.com/public/articles/building-a-laravel-package-service-providers-auto-discovery-and-config-merging-4)  

   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)

 ###  Have a technical challenge?

 Tell me what you’re building. I reply within two working days.

[Start a conversation](https://www.msaied.com/public#contact) 

   Related articles
-----------------

 [ ![](https://cdn.msaied.com/743/8998fac3a41451ab3fe1588194e17a43.png) Filament · 3 min read### Securing Filament Plugins with Plumb: Automated Security Scoring for PHP Packages

5 Oct 2026 ](https://www.msaied.com/public/articles/securing-filament-plugins-with-plumb-automated-security-scoring-for-php-packages) [ ![](https://cdn.msaied.com/742/2d02018669cdeedccb5de2efb898f0ee.png) Filament · 3 min read### Filament v3.3.56 Released: File Hash Names and Livewire Upload Fix

5 Oct 2026 ](https://www.msaied.com/public/articles/filament-v3356-released-file-hash-names-and-livewire-upload-fix) [ ![](https://cdn.msaied.com/741/5b55c123ad08e4d34e1f4b99ad6a428b.png)  · 3 min read### Filament v4 Schema-Based Forms, Infolists, and the Unified Schema API

5 Oct 2026 ](https://www.msaied.com/public/articles/filament-v4-schema-based-forms-infolists-and-the-unified-schema-api-5) 

  Have a technical challenge?
----------------------------

Tell me what you’re building. I reply within two working days.

 [Discuss your project ↗](https://www.msaied.com/public#contact) 

  © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow.

 - [Home](https://www.msaied.com/public)
- [Articles](https://www.msaied.com/public/articles)
- [Certificates](https://www.msaied.com/public/certificates)
- [GitHub](https://github.com/EG-Mohamed)
- [LinkedIn](https://www.linkedin.com/in/msaiedm/)
- [WhatsApp](https://wa.me/201094619204)
- [Email Address](mailto:hello@msaied.com)
- [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)
- [Sitemap](https://www.msaied.com/public/sitemap.xml)