Chapitre 2: Les Endpoints Actuator

Introduction

Actuator fournit de nombreux endpoints prêts à l'emploi. Ce chapitre explore les plus utiles et vous montre comment créer les vôtres.

🎯 Objectifs du Chapitre

À la fin de ce chapitre, vous saurez:

✅ Utiliser tous les endpoints natifs
✅ Comprendre quand utiliser chaque endpoint
✅ Créer des endpoints personnalisés
✅ Filtrer et formater les réponses

1. Liste des Endpoints

Endpoints de Base

Endpoint	Description	Sensible?
`/actuator`	Liste tous les endpoints	Non
`/actuator/health`	État de santé	Non
`/actuator/info`	Informations application	Non

Endpoints d'Analyse

Endpoint	Description	Sensible?
`/actuator/beans`	Liste tous les beans Spring	Oui
`/actuator/conditions`	Conditions d'auto-configuration	Oui
`/actuator/configprops`	Propriétés de configuration	Oui
`/actuator/env`	Variables d'environnement	Oui
`/actuator/mappings`	Tous les @RequestMapping	Oui

Endpoints de Métriques

Endpoint	Description	Sensible?
`/actuator/metrics`	Liste les métriques	Non
`/actuator/metrics/\{name\}`	Une métrique spécifique	Non
`/actuator/prometheus`	Format Prometheus	Non

Endpoints de Debugging

Endpoint	Description	Sensible?
`/actuator/loggers`	Niveaux de log	Oui
`/actuator/threaddump`	Dump des threads	Oui
`/actuator/heapdump`	Dump mémoire (fichier)	Oui
`/actuator/httptrace`	Historique HTTP	Oui

Endpoints d'Actions

Endpoint	Description	Sensible?
`/actuator/shutdown`	Arrêter l'application	Oui
`/actuator/refresh`	Rafraîchir la config	Oui

2. Endpoints en Détail

/actuator/beans

Liste tous les beans Spring de l'application:

curl http://localhost:8080/actuator/beans

{
  "contexts": {
    "application": {
      "beans": {
        "userService": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.service.UserService",
          "dependencies": ["userRepository"]
        },
        "userController": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.controller.UserController",
          "dependencies": ["userService"]
        }
      }
    }
  }
}

Utilité: Débugger l'injection de dépendances.

/actuator/conditions

Montre pourquoi les auto-configurations ont été appliquées ou non:

curl http://localhost:8080/actuator/conditions

{
  "contexts": {
    "application": {
      "positiveMatches": {
        "DataSourceAutoConfiguration": [{
          "condition": "OnClassCondition",
          "message": "@ConditionalOnClass found required classes 'javax.sql.DataSource'"
        }]
      },
      "negativeMatches": {
        "RedisAutoConfiguration": {
          "notMatched": [{
            "condition": "OnClassCondition",
            "message": "@ConditionalOnClass did not find required class 'org.springframework.data.redis.core.RedisOperations'"
          }]
        }
      }
    }
  }
}

Utilité: Comprendre pourquoi une feature est activée/désactivée.

/actuator/env

Affiche toutes les sources de configuration:

curl http://localhost:8080/actuator/env

{
  "activeProfiles": ["dev"],
  "propertySources": [
    {
      "name": "systemProperties",
      "properties": {
        "java.version": {"value": "17.0.1"}
      }
    },
    {
      "name": "applicationConfig: [classpath:/application.properties]",
      "properties": {
        "spring.datasource.url": {"value": "jdbc:h2:mem:testdb"}
      }
    }
  ]
}

Une propriété spécifique:

curl http://localhost:8080/actuator/env/spring.datasource.url

/actuator/mappings

Liste tous les endpoints HTTP de l'application:

curl http://localhost:8080/actuator/mappings

{
  "contexts": {
    "application": {
      "mappings": {
        "dispatcherServlets": {
          "dispatcherServlet": [
            {
              "handler": "com.example.controller.UserController#getAll()",
              "predicate": "{GET /api/users}",
              "details": {
                "requestMappingConditions": {
                  "methods": ["GET"],
                  "patterns": ["/api/users"]
                }
              }
            }
          ]
        }
      }
    }
  }
}

Utilité: Voir tous les endpoints disponibles.

/actuator/loggers

Voir et modifier les niveaux de log à chaud:

# Voir tous les loggers
curl http://localhost:8080/actuator/loggers

# Un logger spécifique
curl http://localhost:8080/actuator/loggers/com.example.service

{
  "configuredLevel": null,
  "effectiveLevel": "DEBUG"
}

Modifier un niveau à chaud (POST):

curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'

Utilité: Activer le DEBUG en production sans redémarrer!

/actuator/threaddump

Affiche l'état de tous les threads:

curl http://localhost:8080/actuator/threaddump

{
  "threads": [
    {
      "threadName": "http-nio-8080-exec-1",
      "threadId": 23,
      "blockedTime": -1,
      "blockedCount": 0,
      "waitedTime": -1,
      "waitedCount": 2,
      "lockName": null,
      "threadState": "RUNNABLE",
      "stackTrace": [
        {
          "className": "java.net.SocketInputStream",
          "methodName": "socketRead0",
          "lineNumber": -2,
          "nativeMethod": true
        }
      ]
    }
  ]
}

Utilité: Détecter les deadlocks, threads bloqués.

/actuator/heapdump

Génère un fichier heap dump (attention: lourd!):

curl -O http://localhost:8080/actuator/heapdump
# Génère un fichier heapdump que vous pouvez analyser avec VisualVM ou MAT

Utilité: Analyser les fuites mémoire.

/actuator/shutdown (Dangereux!)

Arrête l'application proprement:

# Doit être explicitement activé
management.endpoint.shutdown.enabled=true

curl -X POST http://localhost:8080/actuator/shutdown

{
  "message": "Shutting down, bye..."
}

⚠️ À sécuriser absolument!

3. Endpoints Personnalisés

Créer un Endpoint Simple

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {

    @ReadOperation
    public Map<String, Object> customInfo() {
        return Map.of(
            "status", "operational",
            "timestamp", LocalDateTime.now(),
            "version", "1.0.0"
        );
    }
}

curl http://localhost:8080/actuator/custom

{
  "status": "operational",
  "timestamp": "2024-01-15T10:30:00",
  "version": "1.0.0"
}

Endpoint avec Paramètres

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {

    private final Map<String, Boolean> features = new ConcurrentHashMap<>();

    @ReadOperation
    public Map<String, Boolean> getAllFeatures() {
        return features;
    }

    @ReadOperation
    public Boolean getFeature(@Selector String name) {
        return features.getOrDefault(name, false);
    }

    @WriteOperation
    public void setFeature(@Selector String name, boolean enabled) {
        features.put(name, enabled);
    }

    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }
}

# Lire toutes les features
curl http://localhost:8080/actuator/features

# Lire une feature
curl http://localhost:8080/actuator/features/dark-mode

# Activer une feature
curl -X POST "http://localhost:8080/actuator/features/dark-mode?enabled=true"

# Supprimer une feature
curl -X DELETE http://localhost:8080/actuator/features/dark-mode

Endpoint pour Statistiques Métier

@Component
@Endpoint(id = "business-stats")
@RequiredArgsConstructor
public class BusinessStatsEndpoint {

    private final OrderRepository orderRepository;
    private final UserRepository userRepository;

    @ReadOperation
    public Map<String, Object> getStats() {
        return Map.of(
            "totalUsers", userRepository.count(),
            "totalOrders", orderRepository.count(),
            "ordersToday", orderRepository.countByCreatedAtAfter(LocalDate.now().atStartOfDay()),
            "revenue", orderRepository.sumTotalAmount()
        );
    }
}

4. Web Endpoints vs JMX

Exposition Web (HTTP)

# Exposer via HTTP
management.endpoints.web.exposure.include=health,info,metrics

Exposition JMX

# Exposer via JMX (pour JConsole, VisualVM)
management.endpoints.jmx.exposure.include=*

# Désactiver JMX si non utilisé
spring.jmx.enabled=false

5. Résumé

Endpoints Recommandés en Production

Endpoint	Exposition	Usage
`/health`	Public	Load balancer, K8s
`/info`	Public	Version, build
`/metrics`	Interne	Prometheus
`/prometheus`	Interne	Scraping
`/loggers`	Admin	Debug à chaud

Endpoints à Sécuriser

/actuator/env         → Exposer des secrets!
/actuator/heapdump    → Données sensibles!
/actuator/shutdown    → Arrêter l'app!
/actuator/beans       → Architecture interne

Créer un Endpoint

@Component
@Endpoint(id = "my-endpoint")
public class MyEndpoint {
    
    @ReadOperation    // GET
    public Data read() { }
    
    @WriteOperation   // POST
    public void write() { }
    
    @DeleteOperation  // DELETE
    public void delete() { }
}

🎯 Prochaine Étape

Les endpoints c'est bien, mais comment mesurer les performances? Place aux métriques!

➡️ Chapitre 3: Métriques avec Micrometer

⬅️ Retour au Module 11

Introduction​

🎯 Objectifs du Chapitre​

1. Liste des Endpoints​

Endpoints de Base​

Endpoints d'Analyse​

Endpoints de Métriques​

Endpoints de Debugging​

Endpoints d'Actions​

2. Endpoints en Détail​

/actuator/beans​

/actuator/conditions​

/actuator/env​

/actuator/mappings​

/actuator/loggers​

/actuator/threaddump​

/actuator/heapdump​

/actuator/shutdown (Dangereux!)​

3. Endpoints Personnalisés​

Créer un Endpoint Simple​

Endpoint avec Paramètres​

Endpoint pour Statistiques Métier​

4. Web Endpoints vs JMX​

Exposition Web (HTTP)​

Exposition JMX​

5. Résumé​

Endpoints Recommandés en Production​

Endpoints à Sécuriser​

Créer un Endpoint​

🎯 Prochaine Étape​