Vidocq Documentation

Cette page couvre l’écriture de contrôles de santé avec Knock, l’ajout de données de diagnostic, la compréhension de l’agrégation et la lecture de la charge utile produite. Chaque exemple compile contre l’API MicroProfile Health 4.0.

Qualificateurs de sonde

Chaque contrôle déclare exactement un qualificateur de sonde. Le qualificateur détermine quel endpoint le rapporte.

Qualificateur Endpoint Signification

@Liveness

GET /health/live

L’instance fonctionne et n’est pas dans un état irrécupérable. Un DOWN de vivacité déclenche généralement un redémarrage.

@Readiness

GET /health/ready

L’instance est prête à recevoir du trafic (dépendances joignables, caches chauds).

@Startup

GET /health/started

L’initialisation lente est terminée. Permet aux orchestrateurs de différer la sonde de vivacité.

GET /health agrège tous les contrôles enregistrés, sans distinction de qualificateur.

Un bean HealthCheck sans qualificateur de sonde — ou avec plus d’un — échoue à la validation CDI au déploiement. Cette règle est appliquée par HealthCheckCdiExtension conformément à MicroProfile Health §4.2.

Écrire un contrôle

@Readiness
@ApplicationScoped
public class BrokerCheck implements HealthCheck {

    @Inject MessageBroker broker;

    @Override
    public HealthCheckResponse call() {
        return broker.isConnected()
            ? HealthCheckResponse.up("message-broker")
            : HealthCheckResponse.down("message-broker");
    }
}

Joindre des données

Le constructeur de réponse accepte des entrées withData(…​) typées. Knock sérialise nativement String, long, boolean et int ; tout autre type est rendu via String.valueOf(…​).

return HealthCheckResponse.named("disk-space")
        .status(freeBytes > threshold)
        .withData("free", freeBytes)          // long    -> nombre JSON
        .withData("path", "/var/lib")          // String  -> chaîne JSON
        .withData("writable", true)            // boolean -> booléen JSON
        .build();
{
  "name": "disk-space",
  "status": "UP",
  "data": { "free": 5368709120, "path": "/var/lib", "writable": true }
}

L’objet data est entièrement omis lorsqu’aucune entrée n’est ajoutée.

Règles d’agrégation

Le statut agrégé d’un groupe de sondes suit MicroProfile Health §3.2 :

  • le statut global est DOWN dès qu'un contrôle rapporte DOWN ;

  • une liste de contrôles vide donne UP (la sonde est considérée saine) ;

  • une exception levée par HealthCheck.call() est convertie en contrôle DOWN dont le data porte le nom de la classe d’exception — elle ne sort jamais de l’endpoint.

{
  "status": "DOWN",
  "checks": [
    { "name": "database", "status": "UP" },
    { "name": "broker",   "status": "DOWN",
      "data": { "error": "java.net.ConnectException" } }
  ]
}

Modèle d’exécution

Les contrôles d’un groupe de sondes s’exécutent sur un VirtualThreadPerTaskExecutor : chaque call() tourne sur son propre thread virtuel, si bien qu’un contrôle lent ne bloque jamais les autres. Aucun pool de threads plateforme n’est alloué et aucun ThreadLocal n’est utilisé.

Autonome (Java SE)

Sans CDI, enregistrez les contrôles directement et demandez un rapport à la façade :

HealthCheckRegistry registry = new KnockHealthCheckRegistry();
registry.register(new DatabaseCheck());
registry.register(new BrokerCheck());

KnockHealthService service = new KnockHealthService(registry);

HealthReport live = service.report(ProbeType.LIVENESS);
HealthReport all  = service.report(ProbeType.ALL);

HealthReport expose httpStatus() (200 / 503) et json() (la charge utile sérialisée).

Avec CDI (Vauban)

Ajoutez knock-cdi-vauban et Knock découvre automatiquement chaque bean @Liveness/@Readiness/@Startup : la Build Compatible Extension les valide, et HealthCheckRegistrar les enregistre à l’initialisation du contexte applicatif. Aucun enregistrement manuel n’est requis.

Avec Jakarta REST (Cassini)

Ajoutez knock-jaxrs et les endpoints /health* sont publiés par KnockHealthResource. La ressource associe chaque chemin au ProbeType correspondant, appelle KnockHealthService et renvoie la charge utile JSON avec le bon statut HTTP.

Voir aussi

  • Concepts — le vocabulaire derrière ces schémas.

  • Internes — implémentation du registre, de l’agrégateur et du sérialiseur.

  • Référence — artefacts, paquets et endpoints.