RUEN
Продвинутое

Health / Actuator

Winter умеет отдавать диагностические эндпоинты под /actuator — состояние приложения, метрики, метаданные, таблицу маршрутов. Они выключены по умолчанию и включаются одним вызовом в Boot.

Включение Health::configure()Хук Boot::health()Путь /actuator/*

Что такое health и зачем

Health / Actuator — набор read-only эндпоинтов для наблюдаемости приложения.

Проблема. Оркестратору (Kubernetes, балансировщику) нужен способ узнать, живо ли приложение и здоровы ли его зависимости; команде — быстрый взгляд на метрики и конфигурацию без доступа к серверу.

Решение. Winter отдаёт стандартные /actuator-эндпоинты со статусом, метриками и метаданными — как в Spring Boot Actuator. Об этом и раздел.

Включение

По умолчанию actuator-маршруты не регистрируются. Включите в хуке health():

bootstrap.php
use Flytachi\Winter\K2\Http\Health\Health;

protected static function health(): void
{
  Health::configure();   // включить с индикатором по умолчанию
}

Сигнатура:

php
public static function configure(
  string  $indicator  = HealthIndicator::class,   // свой индикатор
  ?string $middleware = null,                     // guard-middleware
): void

Эндпоинты

URL Отдаёт
/actuator/health up / degraded / down — общий статус + по компонентам (БД, кеш, диск, память)
/actuator/info Версия PHP/SAPI, версия и рантайм фреймворка, метаданные проекта
/actuator/metrics CPU, память, диск, opcache, текущий запрос, аптайм
/actuator/env Пользовательский срез окружения (пусто, пока не переопределено)
/actuator/loggers Активные каналы логов и их уровни
/actuator/mappings Снимок зарегистрированных маршрутов

Агрегация статуса: любой down → down; иначе любой degraded → degraded; иначе up. Диск/память: ≥90% → down, ≥80% → degraded. Проверки БД/кеша активны, только если установлены winter-cdo / winter-cache.

Свой индикатор

Наследуйте HealthIndicator и переопределите нужные методы — например, добавьте свою проверку:

main/Health/AppHealthIndicator.php
use Flytachi\Winter\K2\Http\Health\HealthIndicator;

final class AppHealthIndicator extends HealthIndicator
{
  protected function customHealth(): array
  {
      $lag = $this->measureQueueLag();
      return [
          'status'  => $lag > 60 ? 'down' : ($lag > 10 ? 'degraded' : 'up'),
          'details' => ['queue_lag_seconds' => $lag],
      ];
  }

  public function env(): array
  {
      return ['env' => env('APP_ENV')];
  }
}
bootstrap.php
Health::configure(
  indicator:  App\Health\AppHealthIndicator::class,
  middleware: App\Http\Middleware\InternalOnlyMiddleware::class,
);

Защитите actuator

/actuator раскрывает внутренности приложения. В проде закрывайте его guard-middleware (middleware:) — оно применяется ко всем actuator-маршрутам до любого обработчика.

Дальше