Health for Laravel: Kubernetes Probes та Prometheus Metrics

Пакет Health for Laravel від Sylvester Damgaard надає комплексну систему 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:

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 кожна проба вказує на свій шлях:

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, який працює на Linux та macOS. Ви отримуєте середнє навантаження, показники пам'яті, використання диска для кожної точки монтування, байти мережі для кожного інтерфейсу та uptime. Всередині контейнера ендпоінт додає ще п'ять метрик:

Детальніше про всі можливості можна дізнатися в документації Prometheus Metrics.

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

ScheduleCheck зчитує timestamp heartbeat з кешу. Заплануйте команду health:heartbeat у файлі routes/console.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:

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:

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

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

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

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

Вихідний код та повна документація доступні на GitHub.