Contactez-nous

Endpoints courants (`health`, `info`, `metrics`, `env`, `loggers`, `beans`, `mappings`)

Explorez les endpoints Actuator les plus utilisés : health, info, metrics, env, loggers, beans, et mappings. Apprenez à les utiliser pour surveiller et gérer vos applications.

Introduction aux endpoints fondamentaux d'Actuator

Spring Boot Actuator expose par défaut (ou peut être configuré pour exposer) une série d'endpoints HTTP ou JMX fournissant des informations cruciales sur l'état et le fonctionnement de votre application. Comprendre l'utilité des endpoints les plus courants est fondamental pour une surveillance et une gestion efficaces en production. Ces endpoints servent de fenêtres sur l'intérieur de votre application, permettant aux opérateurs, aux développeurs et aux systèmes de monitoring automatisés d'obtenir des données vitales.

Par défaut, pour des raisons de sécurité, seuls les endpoints `/health` et `/info` sont généralement exposés via HTTP dans les versions récentes de Spring Boot. Les autres nécessitent une configuration explicite pour être accessibles. Nous allons détailler ici sept des endpoints les plus fréquemment utilisés : `/health`, `/info`, `/metrics`, `/env`, `/loggers`, `/beans`, et `/mappings`.

Chacun de ces endpoints répond à un besoin spécifique, allant de la simple vérification de l'état de santé à l'inspection détaillée de la configuration, des métriques de performance ou des composants internes de l'application.

`/actuator/health` : L'indicateur de santé vital

L'endpoint `/actuator/health` est sans doute le plus important. Il fournit une indication simple mais essentielle sur l'état de santé général de l'application. Par défaut, il retourne un statut global (`UP` ou `DOWN`). Un statut `UP` signifie que l'application est considérée comme fonctionnelle et prête à servir des requêtes.

La véritable puissance de cet endpoint réside dans sa capacité à agréger l'état de plusieurs composants sous-jacents grâce aux `HealthIndicator`. Spring Boot fournit automatiquement des indicateurs pour des éléments courants comme la connexion à la base de données (`db`), l'espace disque (`diskSpace`), les systèmes de messagerie (RabbitMQ, Kafka), Redis, etc. Si l'un de ces composants essentiels rencontre un problème (ex: impossible de se connecter à la base de données), son statut passe à `DOWN`, et par conséquent, le statut global de l'application passe également à `DOWN`.

Il est possible de configurer l'endpoint pour afficher plus de détails (les statuts individuels de chaque `HealthIndicator`). Cela se fait via la propriété `management.endpoint.health.show-details` (valeurs possibles : `never`, `when-authorized`, `always`). Un exemple de réponse détaillée pourrait ressembler à ceci :

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "PostgreSQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 250790436864,
        "free": 119167713280,
        "threshold": 10485760,
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

Cet endpoint est massivement utilisé par les systèmes d'orchestration (comme Kubernetes pour les liveness/readiness probes) et les load balancers pour déterminer si une instance de l'application doit recevoir du trafic.

`/actuator/info` : Informations applicatives personnalisées

L'endpoint `/actuator/info` sert à exposer des informations générales et arbitraires sur l'application. Contrairement à `/health` qui reflète l'état opérationnel, `/info` est destiné à fournir des données descriptives statiques.

Par défaut, cet endpoint est vide. Vous pouvez le peupler de plusieurs manières :

  • En définissant des propriétés préfixées par `info.` dans votre fichier `application.properties` ou `application.yml`. Par exemple : `info.app.name=Mon Application`, `info.app.version=1.2.3`.
  • En exposant les informations de build Git ou Maven/Gradle via les plugins correspondants (`spring-boot-maven-plugin` avec l'exécution `build-info` ou le plugin Gradle `info`).
  • En implémentant des beans de type `InfoContributor`.

Un exemple de réponse pourrait être :

{
  "app": {
    "name": "Mon Application",
    "description": "Service de gestion de produits",
    "version": "1.0.0-SNAPSHOT"
  },
  "build": {
    "artifact": "mon-app",
    "name": "mon-app",
    "time": "2023-10-27T10:30:00.123Z",
    "version": "1.0.0-SNAPSHOT",
    "group": "com.exemple"
  },
  "git": {
    "branch": "main",
    "commit": {
      "id": "abcdef1",
      "time": "2023-10-26T15:00:00Z"
    }
  }
}

C'est un endpoint utile pour vérifier rapidement quelle version du code est déployée ou pour obtenir d'autres métadonnées pertinentes sur l'instance.

`/actuator/metrics` : Accéder aux métriques de performance

L'endpoint `/actuator/metrics` est la porte d'entrée vers les métriques collectées par l'application, principalement via Micrometer. Il permet d'explorer les métriques disponibles et d'obtenir leur valeur actuelle.

Appeler `/actuator/metrics` sans paramètre renvoie la liste des noms de métriques disponibles :

{
  "names": [
    "jvm.memory.used",
    "jvm.gc.pause",
    "system.cpu.usage",
    "http.server.requests",
    "logback.events",
    // ... et beaucoup d'autres
  ]
}

Pour obtenir la valeur d'une métrique spécifique, on appelle l'endpoint avec le nom de la métrique, par exemple `/actuator/metrics/jvm.memory.used`. La réponse détaille la métrique, ses 'tags' (dimensions permettant de la découper) et ses valeurs :

{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 2.78501888E8
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": [
        "heap",
        "nonheap"
      ]
    },
    {
      "tag": "id",
      "values": [
        "G1 Eden Space",
        "G1 Old Gen",
        // ... autres zones mémoire
      ]
    }
  ]
}

On peut également filtrer par tag, par exemple `/actuator/metrics/jvm.memory.used?tag=area:heap`. Bien que pratique pour une exploration manuelle, cet endpoint est surtout utilisé comme source de données par des systèmes de scraping comme Prometheus, configurés pour collecter régulièrement ces métriques.

`/actuator/env` : Inspecter l'environnement de l'application

L'endpoint `/actuator/env` fournit une vue détaillée de l'environnement Spring de l'application. Cela inclut les propriétés système, les variables d'environnement, les arguments de ligne de commande, les propriétés chargées depuis les fichiers `application.properties`/`yml` (y compris les profils actifs), et d'autres sources de configuration.

La réponse liste les sources de propriétés actives et leurs priorités. Elle peut également montrer les valeurs spécifiques des propriétés (bien que certaines valeurs sensibles comme les mots de passe soient généralement masquées par défaut). Pour obtenir la valeur d'une propriété spécifique, on peut requêter `/actuator/env/{propertyName}`.

Exemple partiel de la réponse de `/actuator/env` :

{
  "activeProfiles": ["prod", "cloud"],
  "propertySources": [
    {
      "name": "servletContextInitParams",
      "properties": {}
    },
    {
      "name": "systemProperties",
      "properties": {
        "java.runtime.name": { "value": "OpenJDK Runtime Environment" },
        // ...
      }
    },
    {
      "name": "systemEnvironment",
      "properties": {
        "PATH": { "value": "/usr/bin:..." },
        // ...
      }
    },
    {
      "name": "applicationConfig: [classpath:/application-prod.properties]",
      "properties": {
        "server.port": { "value": "8081", "origin": "..." },
        "spring.datasource.password": { "value": "******", "origin": "..." }
      }
    },
    {
      "name": "applicationConfig: [classpath:/application.properties]",
      "properties": {
         "spring.application.name": { "value": "my-app", "origin": "..." }
      }
    }
    // ... autres sources
  ]
}

Cet endpoint est extrêmement utile pour le débogage de problèmes de configuration, pour vérifier quels profils sont actifs ou pour comprendre d'où provient la valeur d'une propriété spécifique.

`/actuator/loggers` : Gérer les niveaux de log à la volée

L'endpoint `/actuator/loggers` permet de visualiser et de modifier les niveaux de log des loggers de l'application (typiquement Logback ou Log4j2) sans avoir besoin de redémarrer. C'est un outil très précieux pour le débogage en production.

Appeler `GET /actuator/loggers` renvoie la liste de tous les loggers configurés avec leurs niveaux effectifs et configurés :

{
  "levels": [ "OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE" ],
  "loggers": {
    "ROOT": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    "com.exemple.myapp": {
      "configuredLevel": null, // Hérite du parent
      "effectiveLevel": "INFO"
    },
    "org.springframework.web": {
      "configuredLevel": "WARN",
      "effectiveLevel": "WARN"
    },
    // ... autres loggers
  }
}

Pour obtenir le niveau d'un logger spécifique, on utilise `GET /actuator/loggers/{loggerName}` (ex: `/actuator/loggers/com.exemple.myapp`).

Pour modifier le niveau d'un logger, on utilise une requête `POST` vers `/actuator/loggers/{loggerName}` avec un corps JSON spécifiant le nouveau niveau (ou `null` pour réinitialiser au niveau hérité/par défaut) :

// POST /actuator/loggers/com.exemple.myapp
// Body:
{
  "configuredLevel": "DEBUG"
}

Cela active immédiatement le logging DEBUG pour ce package, permettant de capturer des informations détaillées pour diagnostiquer un problème spécifique, puis de revenir facilement au niveau normal (ex: INFO ou WARN) une fois le diagnostic terminé.

`/actuator/beans` : Explorer le contexte Spring

L'endpoint `/actuator/beans` fournit une vue complète de tous les beans chargés dans le contexte d'application Spring (`ApplicationContext`). C'est un outil puissant pour comprendre quels composants ont été instanciés, comment ils sont configurés, et quelles sont leurs dépendances.

La réponse est une structure JSON hiérarchique qui liste les contextes d'application (il peut y en avoir plusieurs dans certaines architectures) et, pour chacun, les beans qu'il contient. Pour chaque bean, on trouve typiquement :

  • Son nom (l'identifiant unique dans le contexte Spring).
  • Son alias (s'il en a).
  • Sa portée (scope : singleton, prototype, etc.).
  • Le type complet de la classe du bean.
  • Le chemin vers la ressource où il a été défini (ex: classe de configuration).
  • Ses dépendances (les autres beans qui lui ont été injectés).

Exemple simplifié :

{
  "contexts": {
    "application-1": {
      "beans": {
        "myService": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.exemple.myapp.service.MyServiceImpl",
          "resource": "file [/.../MyServiceImpl.class]",
          "dependencies": [
            "myRepository",
            "anotherDependency"
          ]
        },
        "myRepository": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.exemple.myapp.repository.MyRepositoryImpl",
          // ...
        }
        // ... autres beans
      },
      "parentId": null
    }
  }
}

Cet endpoint est très utile pour déboguer des problèmes liés à l'injection de dépendances, vérifier si une configuration a bien été prise en compte, ou simplement explorer la structure interne de l'application telle que Spring l'a construite.

`/actuator/mappings` : Visualiser les mappings web

L'endpoint `/actuator/mappings` donne une vue d'ensemble de tous les mappings de requêtes HTTP gérés par l'application. Cela inclut les mappings définis dans les `@Controller` et `@RestController`, ainsi que les mappings des ressources statiques et ceux des endpoints Actuator eux-mêmes.

La réponse détaille, pour chaque mapping, l'URL (ou le pattern d'URL), la ou les méthodes HTTP supportées, la méthode du contrôleur qui gère la requête, ainsi que d'autres détails comme les types de médias produits ou consommés.

Exemple simplifié :

{
  "contexts": {
    "application-1": {
      "mappings": {
        "dispatcherServlets": {
          "dispatcherServlet": [
            {
              "details": {
                "handlerMethod": {
                  "className": "com.exemple.myapp.controller.ProductController",
                  "name": "getProductById",
                  "descriptor": "(java.lang.Long)org.springframework.http.ResponseEntity"
                },
                "requestMappingConditions": {
                  "patterns": ["/api/products/{id}"],
                  "methods": ["GET"],
                  "produces": [ {"mediaType":"application/json", "negated":false} ],
                  // ... autres conditions
                }
              },
              "handler": "com.exemple.myapp.controller.ProductController#getProductById(Long)",
              "predicate": "{GET /api/products/{id}, produces [application/json]}"
            },
            // ... autres mappings de contrôleurs
            {
               "details": { /* Actuator endpoint mapping */ },
               "handler": "EndpointWebMvcAdapter ...",
               "predicate": "{GET /actuator/health}"
            }
          ]
        }
      }
    }
  }
}

Cet endpoint est utile pour vérifier rapidement quels chemins sont exposés par l'application, pour s'assurer qu'un contrôleur est bien enregistré, ou pour déboguer des problèmes de routage ou de conflits d'URL.