Health checks Laravel en production : ce que /up prouve vraiment

Par défaut, /up confirme que Laravel démarre sans exception. Cela ne prouve ni l’envoi de mail, ni la disponibilité d’un paiement, ni les bonnes données d’un portail. Ajoutez seulement les contrôles correspondant à la disponibilité visée.

Comparaison : une erreur au démarrage peut faire échouer /up, tandis qu’un formulaire cassé peut coexister avec un /up réussi. Distinguez contrôle léger et test sûr d’un parcours métier.

• Identifier les dépendances réellement contrôlées.
• Borner les appels externes pour ne pas amplifier une panne.
• Ne pas utiliser de vraies transactions ou exposer des diagnostics dans le contrôle public.

• Source et détails
• Audit Laravel et assistance technique

Une application Laravel qui renvoie HTTP 200 sur un endpoint de santé est joignable, mais cela ne prouve pas que toute l'application est utilisable. La route de santé intégrée est surtout un contrôle léger du démarrage. C'est une bonne base en production si l'accessibilité, les dépendances critiques et les parcours utilisateur réels sont supervisés séparément.

Ce que `/up` prouve et ne prouve pas

Laravel 13 inclut une route de santé, généralement sur `/up`. La documentation officielle indique qu'elle renvoie 200 lorsque l'application démarre sans exception et 500 dans le cas contraire. Elle déclenche aussi `Illuminate\Foundation\Events\DiagnosingHealth`, ce qui permet d'ajouter des contrôles ciblés.

• 200 sur `/up` signifie que Laravel a pu traiter la requête de santé et démarrer.
• Un timeout ou une erreur de connexion peut se situer avant Laravel, par exemple DNS, TLS, serveur web, réseau ou hébergement.
• Un `/up` vert ne prouve pas automatiquement que l'e-mail, une API externe, le checkout ou un autre flux métier fonctionne.

Utilisez trois niveaux de supervision

1. Contrôle de base : appeler `/up` avec un timeout court.
2. Dépendance critique : contrôler uniquement une dépendance dont la panne rend l'application pratiquement inutilisable, par exemple la base principale.
3. Supervision fonctionnelle : contrôler séparément une route publique représentative, un appel API ou un parcours synthétique sûr.

Cette séparation évite la fausse confiance et la fragilité inutile. Une supervision trop superficielle peut rester verte alors que les utilisateurs rencontrent des erreurs. Un endpoint trop profond devient instable parce que chaque fournisseur externe ou intégration optionnelle peut faire échouer l'état global.

Une sonde légère de base de données avec `DiagnosingHealth`

Si presque toutes les requêtes importantes ont besoin de la base principale, une petite sonde est raisonnable. Gardez la requête peu coûteuse, en lecture seule et prévisible. Un simple `select 1` vérifie la connexion sans lire de données métier.

<?php

namespace App\Providers;

use Illuminate\Foundation\Events\DiagnosingHealth;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen(DiagnosingHealth::class, static function (): void {
            DB::select('select 1');
        });
    }
}

Ne contrôlez pas automatiquement chaque table, fournisseur externe ou fonctionnalité optionnelle. Les endpoints de santé sont souvent appelés fréquemment. Les requêtes lourdes et appels réseau augmentent la charge, la latence et les fausses alertes.

Les services externes appartiennent généralement à une supervision séparée

Un fournisseur de paiement, CRM, service cartographique ou fournisseur e-mail peut tomber brièvement sans rendre tout le site indisponible. Supervisez ces dépendances séparément lorsqu'elles sont critiques. Ne laissez pas une API optionnelle décider de la santé de toute l'application.

• Ne lancez pas un checkout complet depuis `/up`.
• N'envoyez pas un e-mail de test à chaque requête de santé.
• N'utilisez pas une requête de reporting lourde comme sonde de base de données.
• N'exposez pas de données personnelles, secrets, stack traces ou détails fournisseurs dans la réponse publique.

Laravel 13 et les réponses JSON de santé

Laravel 13 peut renvoyer du JSON sur la route de santé intégrée lorsque le client le demande. Pour un moniteur externe, le statut HTTP reste plus important que le texte de la réponse. Un smoke check simple peut ressembler à ceci :

curl --fail --silent --show-error \
  --max-time 5 \
  --header 'Accept: application/json' \
  https://example.com/up

Hébergement mutualisé : rester basé sur HTTP

Sur un hébergement mutualisé, un health check HTTP est utile car il ne demande ni worker permanent, ni daemon, ni Redis, ni Supervisor. Un moniteur externe peut appeler `/up` périodiquement. La supervision détecte les pannes, mais ne change pas les contraintes d'exécution de l'hébergement et ne doit pas rendre les flux critiques dépendants du background processing.

Après déploiement

Combinez la route de santé avec au moins un smoke test non destructif d'une page publique ou route API représentative. Contrôlez aussi l'absence de nouvelles exceptions critiques dans les logs et connaissez le chemin de rollback avant d'en avoir besoin.

Résumé

La route `/up` intégrée à Laravel est une bonne base native au framework pour la supervision en production. Utilisez `DiagnosingHealth` uniquement pour les dépendances réellement critiques, gardez la réponse minimale et supervisez les parcours fonctionnels séparément. Le meilleur health check ne teste pas tout ; il répond de manière fiable à une question claire.