18 – Troubleshooting

Version : 4.0.0 Date : 2025-12-09

1. Problèmes de démarrage

1.1 Application ne démarre pas

Symptôme : L’application ne démarre pas ou crashe immédiatement.

Causes possibles :

1. Port déjà utilisé

   Error: Address already in use: bind
   

   Solution :

   # Trouver le processus
   lsof -i :8080
   # Changer le port
   export HTTP_PORT=8081
   

2. Configuration manquante

   Failed to bind properties under 'socle.xxx'
   

   Solution : Vérifier les variables d’environnement et application.yml

3. Erreur de logging

   ERROR StatusLogger Log4j2 could not find a logging implementation
   

   Solution : Vérifier que log4j2.xml existe dans src/main/resources/

1.2 Workers ne démarrent pas

Symptôme : Les workers sont enregistrés mais restent en état REGISTERED.

Solutions :

1. Vérifier les logs d’initialisation
2. Vérifier les dépendances (base de données, Redis, etc.)
3. Vérifier les priorités de démarrage

curl http://localhost:8080/admin/workers

2. Problèmes de connectivité

2.1 Redis non accessible

Symptôme :

Cannot get Jedis connection

Solutions :

1. Vérifier l’hôte et le port Redis

   redis-cli -h localhost -p 6379 ping
   

2. Vérifier le mot de passe
3. Vérifier les firewalls

2.2 Database non accessible

Symptôme :

Database may be already in use: "locked by another process"

Solutions :

1. Arrêter les autres instances
2. Utiliser AUTO_SERVER=TRUE dans l’URL H2
3. Supprimer les fichiers de lock

rm ./data/socle-techdb.lock.db

3. Problèmes de logging (V4)

3.1 Logs non visibles

Symptôme : Aucun log n’apparaît.

Solutions :

1. Vérifier que log4j2.xml existe
2. Vérifier le niveau de log
3. Vérifier logging.config dans application.yml

logging:
  config: classpath:log4j2.xml

3.2 Conflit Logback/Log4j2

Symptôme :

SLF4J: Class path contains multiple SLF4J bindings

Solution : Exclure Logback de toutes les dépendances

mvn dependency:tree | grep logback

<exclusion>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-logging</artifactId>
</exclusion>

3.3 AsyncLoggers non actifs

Symptôme : Performance de logging dégradée.

Solution : Vérifier log4j2.component.properties

Log4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector

3.4 LogForwarder queue pleine

Symptôme :

WARN - Log queue full, storing to fallback

Solutions :

1. Augmenter queue-capacity
2. Vérifier la connectivité réseau vers le LogHub
3. Réduire le volume de logs

# Vérifier les logs en fallback
curl http://localhost:8080/admin/logforwarder/status

4. Problèmes de performance

4.1 Haute consommation CPU

Solutions :

1. Vérifier les workers en boucle infinie
2. Vérifier les logs en DEBUG
3. Profiler avec JFR

jcmd <pid> JFR.start duration=60s filename=recording.jfr

4.2 Haute consommation mémoire

Solutions :

1. Analyser le heap dump

   jmap -dump:format=b,file=heap.hprof <pid>
   

2. Vérifier les fuites dans KvBus/SharedDataRegistry
3. Ajuster la configuration JVM

4.3 Latence élevée

Solutions :

1. Vérifier les circuit breakers

   curl http://localhost:8080/admin/resilience/circuits
   

2. Vérifier les connexions réseau
3. Vérifier les métriques

   curl http://localhost:8080/actuator/prometheus | grep latency
   

5. Problèmes de résilience

5.1 Circuit Breaker bloqué en OPEN

Symptôme : Un circuit reste ouvert malgré la récupération du service.

Solutions :

1. Reset manuel

   curl -X POST http://localhost:8080/admin/resilience/circuits/my-circuit/reset
   

2. Vérifier le timeout configuré
3. Vérifier que le service cible répond

5.2 Retry infini

Symptôme : L’application retry sans fin.

Solutions :

1. Vérifier max-attempts configuré
2. Vérifier les exceptions retryables
3. Ajouter un circuit breaker

6. Problèmes H2 TechDB (V4)

6.1 Base corrompue

Symptôme :

File corrupted

Solution :

rm -rf ./data/socle-techdb.*
# Redémarrer l'application

6.2 H2 Console inaccessible

Solutions :

1. Vérifier socle.techdb.console.enabled=true
2. Vérifier l’URL : http://localhost:8080/h2-console
3. Utiliser l’URL JDBC correcte : jdbc:h2:file:./data/socle-techdb

6.3 Offsets perdus

Solutions :

1. Vérifier que TechDB est enabled
2. Vérifier les logs de saveOffset
3. Requêter directement H2

   SELECT * FROM socle_offsets;
   

7. Problèmes d’authentification (V4)

7.1 Login échoue

Symptôme :

AuthenticationException: Login failed: 401

Solutions :

1. Vérifier API_KEY
2. Vérifier SOURCE_NAME
3. Vérifier AUTH_SERVER_URL

7.2 Token expiré

Symptôme :

Token expired

Solutions :

1. Vérifier l’horloge système (NTP)
2. Augmenter access-token-buffer-seconds

7.3 Admin API 401

Solutions :

1. Vérifier si l’auth est activée

   socle.admin.auth.enabled: true
   

2. Utiliser les credentials corrects

   curl -u admin:password http://localhost:8080/admin/workers
   

8. Problèmes Kubernetes

8.1 Pod en CrashLoopBackOff

Solutions :

1. Vérifier les logs

   kubectl logs <pod-name> --previous
   

2. Vérifier les ressources
3. Vérifier les probes

8.2 Probes échouent

Solutions :

1. Augmenter initialDelaySeconds
2. Vérifier que l’endpoint /admin/health répond
3. Vérifier le port

8.3 OOMKilled

Solutions :

1. Augmenter les limites mémoire
2. Ajuster les options JVM

   -XX:MaxRAMPercentage=75.0
   

9. Commandes de diagnostic

9.1 API Admin

# Santé globale
curl http://localhost:8080/admin/health

# État des workers
curl http://localhost:8080/admin/workers

# Registry
curl http://localhost:8080/admin/registry

# Circuits breakers
curl http://localhost:8080/admin/resilience/circuits

# Configuration
curl http://localhost:8080/admin/config

# Métriques
curl http://localhost:8080/actuator/prometheus

9.2 JVM

# Thread dump
jstack <pid>

# Heap info
jmap -heap <pid>

# GC stats
jstat -gcutil <pid> 1000

# JFR recording
jcmd <pid> JFR.start duration=60s filename=recording.jfr

9.3 Réseau

# Test Redis
redis-cli -h localhost ping

# Test HTTP
curl -v http://localhost:8080/admin/health

# DNS
nslookup myservice.namespace.svc.cluster.local

10. Logs utiles à activer

# application.yml ou variables d'environnement

logging:
  level:
    eu.lmvi.socle: DEBUG
    eu.lmvi.socle.mop: DEBUG
    eu.lmvi.socle.supervisor: DEBUG
    eu.lmvi.socle.techdb: DEBUG
    eu.lmvi.socle.resilience: DEBUG
    org.springframework.web: DEBUG
    io.lettuce: DEBUG  # Redis

11. Checklist de diagnostic

□ L'application démarre-t-elle ?
  □ Logs de démarrage présents ?
  □ Port disponible ?
  □ Configuration valide ?

□ Les workers sont-ils healthy ?
  □ GET /admin/workers
  □ Heartbeats reçus ?
  □ Erreurs dans les logs ?

□ Les connexions externes fonctionnent-elles ?
  □ Redis accessible ?
  □ Base de données accessible ?
  □ APIs externes accessibles ?

□ Les métriques sont-elles normales ?
  □ CPU < 80% ?
  □ Mémoire < 80% ?
  □ Latence acceptable ?
  □ Taux d'erreur bas ?

□ Les logs sont-ils corrects ?
  □ Log4j2 configuré ?
  □ LogForwarder fonctionne ?
  □ Pas de logs en fallback ?

12. Références

• 14-ADMIN-API – API Admin
• 15-METRICS – Métriques
• 17-HOWTO – How-To Guides