---
title: "Health for Laravel: Kubernetes Probes та Prometheus Metrics"
url: https://laravelukraine.com/blog/health-for-laravel-kubernetes-probes-ta-prometheus-metrics
date: 2026-09-23
source: https://laravel-news.com/laravel-health-kubernetes-prometheus
---

# Health for Laravel: Kubernetes Probes та Prometheus Metrics

Пакет Health for Laravel від [Sylvester Damgaard](https://github.com/cboxdk) надає комплексну систему health-перевірок для Laravel-додатків, яка інтегрується з Kubernetes та Prometheus. На відміну від стандартного `/up` ендпоінта у нових Laravel-додатках, який лише повідомляє про успішне завантаження застосунку, цей пакет дозволяє призначати різні набори перевірок для кожного типу проби.

## Основні можливості пакета

Пакет пропонує широкий спектр функціоналу:

- **Kubernetes probes**: три окремі ендпоінти `/health`, `/health/ready` та `/health/startup`, кожен з власним списком перевірок
- **10 вбудованих перевірок**: database, cache, queue, storage, Redis, environment, schedule, CPU, memory та disk space
- **Prometheus metrics**: статус та тривалість перевірок, а також метрики навантаження, пам'яті, дискового простору та мережі
- **Container awareness**: читає обмеження cgroup v1 та v2, тому показники пам'яті беруться з контейнера, а не з хоста
- **JSON metrics**: ті самі системні дані на `/health/metrics/json` з hostname або назвою pod, який обробив запит
- **Команда `health:check`**: запускає перевірки з терміналу та повертає ненульовий код виходу при помилці
- **Response caching**: результати перевірок кешуються на 10 секунд за замовчуванням
- **HTML dashboard**: сторінка статусу на `/health/ui`, за замовчуванням вимкнена

## Окремі перевірки для кожної Kubernetes проби

Ви призначаєте перевірки для проб у конфігураційному файлі `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,
    ],
],
```

Kubernetes перезапускає контейнер, коли його liveness проба не проходить. Коли readiness проба не спрацьовує, Kubernetes припиняє маршрутизацію трафіку на pod, але залишає його запущеним. Ендпоінт проби повертає статус `200`, коли кожна перевірка має статус `ok` або `warning`, та `503`, коли будь-яка перевірка має статус `critical` або `unknown`.

У маніфесті deployment кожна проба вказує на свій шлях:

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

Ендпоінт `/health/status` повертає результати всіх перевірок разом з hostname, який у Kubernetes є назвою pod. Три ендпоінти проб не включають hostname у відповідь.

## Prometheus Metrics

Ендпоінт `/health/metrics` повертає два gauge на кожну health-перевірку. Метрика `app_health_check_status` дорівнює `1.0` для ok, `0.5` для warning та `0.0` для critical або unknown. Метрика `app_health_check_duration_seconds` записує, скільки часу зайняла перевірка. Префікс `app` береться зі змінної середовища `HEALTH_PROMETHEUS_NAMESPACE`.

Системні метрики надходять з пакета [cboxdk/system-metrics](https://github.com/cboxdk/system-metrics), який працює на Linux та macOS. Ви отримуєте середнє навантаження, показники пам'яті, використання диска для кожної точки монтування, байти мережі для кожного інтерфейсу та uptime. Всередині контейнера ендпоінт додає ще п'ять метрик:

| Метрика | Тип |
|---------|-----|
| `app_container_memory_limit_bytes` | gauge |
| `app_container_memory_usage_bytes` | gauge |
| `app_container_cpu_quota` | gauge |
| `app_container_cpu_throttled_total` | counter |
| `app_container_oom_kills_total` | counter |

Детальніше про всі можливості можна дізнатися в [документації Prometheus Metrics](https://github.com/cboxdk/laravel-health/blob/main/docs/endpoints/prometheus-metrics.md).

## Перевірка роботи планувальника задач

`ScheduleCheck` зчитує timestamp heartbeat з кешу. Заплануйте команду `health:heartbeat` у файлі `routes/console.php`, щоб записувати його:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('health:heartbeat')->everyMinute();
```

Перевірка повертає `critical`, коли heartbeat старіший за `max_age_minutes`, що за замовчуванням дорівнює 5 хвилинам. Вона повертає `warning`, коли heartbeat ще не існує. Додайте перевірку до списку readiness, і ендпоінт поверне `503`, коли планувальник задач не запускався протягом п'яти хвилин.

## Написання власної перевірки

Перевірка реалізує контракт `HealthCheck`, який має метод `name()` та метод `run()`, що повертає `CheckResult`. Розширте `BaseCheck`, і назва буде отримана з імені класу, тому `PaymentGatewayCheck` стане `payment_gateway`:

```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());
        }

        if ($response->successful()) {
            return CheckResult::ok($this->name());
        }

        return CheckResult::critical($this->name(), "HTTP {$response->status()}");
    }
}
```

Додайте клас до масиву `readiness` у `config/health.php`. `CheckResult` має чотири конструктори: `ok()`, `warning()`, `critical()` та `unknown()`. Кожен приймає масив метаданих як третій аргумент, і відповіді статусу та JSON включають його. Вбудована перевірка `QueueCheck` використовує метадані для звіту про `queue_size`.

## Встановлення та налаштування

Версія 2.0.0 вимагає PHP 8.3 та Laravel 11, 12 або 13:

```bash
composer require cboxdk/laravel-health
php artisan vendor:publish --tag="health-config"
```

Запустіть перевірки з терміналу, щоб підтвердити налаштування:

```bash
php artisan health:check
php artisan health:check --endpoint=readiness
```

Без опції команда запускає liveness та readiness перевірки. Змінна середовища `HEALTH_PREFIX` змінює префікс `/health`, і кожен ендпоінт має власні ключі `path` та `enabled`, якщо ви віддаєте перевагу `/readyz`.

Вихідний код та повна документація доступні на [GitHub](https://github.com/cboxdk/laravel-health).