Health per Laravel: Probe Kubernetes e Metriche Prometheus

Health for Laravel è un pacchetto di health check di Sylvester Damgaard. Registra endpoint separati per i tre tipi di probe Kubernetes, e un endpoint /health/metrics che Prometheus può raccogliere. Le nuove applicazioni Laravel includono la route di health /up, che segnala se l'applicazione è stata avviata. Con questo pacchetto, assegni un insieme diverso di check a ciascun probe.

Ecco cosa offre il pacchetto:

• Probe Kubernetes: /health, /health/ready e /health/startup, ciascuno con la propria lista di check
• 10 check integrati: database, cache, coda, storage, Redis, ambiente, pianificazione, CPU, memoria e spazio su disco
• Metriche Prometheus: stato e durata dei check, più gauge di carico, memoria, disco e rete
• Consapevolezza dei container: legge i limiti cgroup v1 e v2, quindi i valori di memoria provengono dal container e non dall'host
• Metriche JSON: gli stessi dati di sistema su /health/metrics/json, con l'hostname o il nome del pod che ha servito la richiesta
• health:check: esegue i check dal terminale ed esce con codice diverso da zero in caso di errore
• Cache delle risposte: i risultati dei check sono memorizzati in cache per 10 secondi per impostazione predefinita
• Dashboard HTML: una pagina di stato su /health/ui, disabilitata per impostazione predefinita

Check separati per ciascun probe Kubernetes

Assegni i check ai probe in 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 riavvia un container quando il suo liveness probe fallisce. Quando il readiness probe fallisce, Kubernetes smette di instradare traffico verso il pod e lo lascia in esecuzione. Un endpoint probe restituisce 200 quando ogni check è ok o warning, e 503 quando un check è critical o unknown. Il manifest di deployment punta ciascun probe al suo path:

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

L'endpoint /health/status restituisce ogni risultato dei check insieme all'hostname, che in Kubernetes è il nome del pod. I tre endpoint probe omettono l'hostname.

Metriche Prometheus

L'endpoint /health/metrics restituisce due gauge per ogni health check. app_health_check_status è 1.0 per ok, 0.5 per un warning e 0.0 per critical o unknown. app_health_check_duration_seconds registra quanto tempo ha impiegato il check. Il prefisso app proviene da HEALTH_PROMETHEUS_NAMESPACE.

Le metriche di sistema provengono dal pacchetto cboxdk/system-metrics dell'autore, che funziona su Linux e macOS. Ottieni load average, memoria, utilizzo del disco per punto di mount, byte di rete per interfaccia e uptime. All'interno di un container, l'endpoint aggiunge altre cinque metriche:

Puoi saperne di più su tutte le funzionalità offerte nella documentazione Prometheus Metrics.

Verificare che lo scheduler sia in esecuzione

ScheduleCheck legge un timestamp di heartbeat dalla cache. Pianifica il comando health:heartbeat in routes/console.php per scriverlo:

use Illuminate\Support\Facades\Schedule;

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

Il check restituisce critical quando l'heartbeat è più vecchio di max_age_minutes, che per impostazione predefinita è 5. Restituisce warning quando non esiste ancora alcun heartbeat. Aggiungi il check alla lista readiness, e l'endpoint restituisce 503 quando lo scheduler delle attività non viene eseguito per cinque minuti.

Scrivere un check personalizzato

Un check implementa il contract HealthCheck, che ha un metodo name() e un metodo run() che restituisce un CheckResult. Estendi BaseCheck e il nome deriva dal nome della classe, quindi PaymentGatewayCheck diventa 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()}");
}
}

Aggiungi la classe all'array readiness in config/health.php. CheckResult ha quattro costruttori: ok(), warning(), critical() e unknown(). Ognuno accetta un array di metadati come terzo argomento, e le risposte di stato e JSON lo includono. Il QueueCheck integrato usa i metadati per riportare queue_size.

Installazione

La versione 2.0.0 richiede PHP 8.3 e Laravel 11, 12 o 13:

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

Esegui i check dal terminale per confermare la configurazione:

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

Senza l'opzione, il comando esegue i check di liveness e readiness. La variabile d'ambiente HEALTH_PREFIX cambia il prefisso /health, e ogni endpoint ha le proprie chiavi path e enabled se preferisci /readyz.

Il codice sorgente e la documentazione completa sono su GitHub.