27 – Status Dashboard

Version : 4.0.0 Package : eu.lmvi.socle.worker.status

Introduction

Le StatusDashboardWorker est un Worker integre au Socle V004 qui expose un dashboard HTML de supervision sur un port dedie. Il permet de visualiser en temps reel l’etat de l’application et de tous les Workers.

Caracteristiques

• Automatique : Active par defaut, aucun code a ajouter
• Port dedie : 9374 (configurable)
• Dashboard HTML : Interface web avec rafraichissement AJAX partiel
• API JSON : Endpoints REST pour integration
• Metriques d’activite : Throughput, duree, charge relative
• Animation visuelle : Mise en evidence des valeurs modifiees

Acces au Dashboard

Une fois l’application demarree, le dashboard est accessible sur :

http://localhost:9374/

Configuration

application.yml

socle:
  status_dashboard:
    # Activer/desactiver le dashboard (defaut: true)
    enabled: true

    # Port du serveur HTTP (defaut: 9374)
    port: 9374

    # Adresse de bind (vide = toutes les interfaces)
    bind_address: ""

    # Intervalle de rafraichissement HTML en secondes (defaut: 5)
    refresh_interval: 5

    # Fenetre de calcul des metriques en secondes (defaut: 60)
    metrics_window: 60

    # Limite de requetes par seconde (defaut: 10)
    max_requests_per_second: 10

    # Activer l'API JSON (defaut: true)
    api_enabled: true

Variables d’environnement

Rafraichissement AJAX

Le dashboard utilise JavaScript pour mettre a jour uniquement les valeurs qui changent, sans recharger la page entiere.

Fonctionnement

1. Chargement initial : La page HTML complete est servie
2. Rafraichissement periodique : JavaScript appelle /api/status et /api/workers
3. Mise a jour selective : Seuls les elements dont la valeur a change sont modifies
4. Animation visuelle : Les valeurs modifiees sont brievement mises en surbrillance (effet cyan)

Avantages

• Pas de rechargement complet de la page
• Experience utilisateur fluide
• Reduction de la bande passante
• Conservation de l’etat de scroll

Configuration de l’intervalle

L’intervalle de rafraichissement AJAX correspond a refresh_interval :

socle:
  status_dashboard:
    refresh_interval: 3  # Rafraichissement toutes les 3 secondes

Endpoints HTTP

Dashboard HTML

Health Check

Exemple de reponse :

{"status":"UP"}

API JSON

Donnees affichees

Section : Status Global

Section : Worker Activity

Barres visuelles montrant la charge relative de chaque Worker :

cdc_kafka_worker    ████████████████████░░░░  85%  [HOT]
http_worker         ██████████████░░░░░░░░░░  58%
rule_engine         ████████░░░░░░░░░░░░░░░░  32%
control_worker      ███░░░░░░░░░░░░░░░░░░░░░  12%
maintenance_worker  █░░░░░░░░░░░░░░░░░░░░░░░   2%  [IDLE]

Tags :

• [HOT] : Worker avec charge > 80%
• [IDLE] : Worker inactif
• [PASSIVE] : Worker event-driven sans activite

Section : Workers Detail

Tableau detaille avec :

Exemples API JSON

GET /api/status

{
  "timestamp": "2026-01-12T17:34:56.789Z",
  "application": {
    "name": "my-app",
    "environment": "PROD",
    "version": "4.0.0"
  },
  "mop": {
    "state": "RUNNING",
    "uptime_ms": 9252000,
    "uptime_human": "2h 34m 12s"
  },
  "workers": {
    "total": 6,
    "healthy": 6,
    "running": 6
  },
  "activity": {
    "total_throughput": 847.3,
    "metrics_window_sec": 60
  }
}

GET /api/workers

{
  "timestamp": "2026-01-12T17:34:56.789Z",
  "workers": [
    {
      "name": "cdc_kafka_worker",
      "state": "running",
      "healthy": true,
      "schedule": "PASSIVE",
      "metrics": {
        "execution_count": 12847,
        "total_duration_ms": 29548,
        "avg_duration_ms": 2.3,
        "last_execution": "2026-01-12T17:34:55.123Z",
        "throughput_per_sec": 721.4,
        "errors_count": 3,
        "messages_processed": 45230
      },
      "relative_load": 0.85
    }
  ]
}

Securite

Bind localhost uniquement (production)

Pour limiter l’acces au dashboard en production :

socle:
  status_dashboard:
    bind_address: "127.0.0.1"

Desactiver en production

socle:
  status_dashboard:
    enabled: false

Ou via variable d’environnement :

export STATUS_DASHBOARD_ENABLED=false

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  StatusDashboardWorker                      │
│                                                             │
│  ┌─────────────────────┐    ┌─────────────────────────┐    │
│  │ WorkerActivityTracker│    │ DashboardHtmlRenderer   │    │
│  │ (collecte metriques) │    │ (genere HTML)           │    │
│  └──────────┬──────────┘    └────────────┬────────────┘    │
│             │                            │                  │
│             └──────────┬─────────────────┘                  │
│                        │                                    │
│              ┌─────────▼─────────┐                          │
│              │   MiniHttpServer  │                          │
│              │   (port 9374)     │                          │
│              └─────────┬─────────┘                          │
└────────────────────────┼────────────────────────────────────┘
                         │
                         ▼
                    Browser / curl

Composants

Integration avec Monitoring

Le dashboard peut etre integre avec des outils de monitoring existants :

Prometheus / Grafana

Utilisez l’endpoint /api/status pour collecter les metriques :

# prometheus.yml
scrape_configs:
  - job_name: 'socle-status'
    metrics_path: /api/status
    static_configs:
      - targets: ['localhost:9374']

Health Checks (Kubernetes)

# deployment.yaml
livenessProbe:
  httpGet:
    path: /health
    port: 9374
  initialDelaySeconds: 30
  periodSeconds: 10

Convention des Stats Workers

Pour que le dashboard affiche correctement les metriques, les workers doivent exposer des cles standardisees dans getStats().

Cles requises par WorkerActivityTracker

Cles optionnelles

Note : Les workers heritant de AbstractEventDrivenWorker exposent automatiquement ces cles depuis la version 4.0.1.

Voir 05-WORKERS.md section 12 pour les details d’implementation.

Troubleshooting

Le dashboard ne demarre pas

Cause possible : Port deja utilise

Solution :

socle:
  status_dashboard:
    port: 9375  # Changer le port

Metriques a zero

Cause possible : Les workers sont en mode PASSIVE et n’ont pas encore traite d’evenements

Solution : Normal pour les workers event-driven. Les metriques apparaitront des que des evenements seront traites.

Dashboard lent

Cause possible : Trop de workers ou refresh trop frequent

Solution :

socle:
  status_dashboard:
    refresh_interval: 10  # Augmenter l'intervalle

Voir aussi

• 05-WORKERS.md – Documentation des Workers
• 08-SUPERVISOR.md – Supervision et health checks
• 15-METRICS.md – Metriques Prometheus

Socle V004 – Status Dashboard

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

01 – Introduction au Socle V4

Version : 4.0.0 Date : 2025-01-25

1. Qu’est-ce que le Socle V4 ?

Le Socle V4 est un framework Java de grade production construit sur Spring Boot 3.2.1 qui implémente le pattern MOP (Main Orchestrator Process). Il fournit une base solide pour construire des applications d’entreprise robustes et observables.

Évolution depuis V3

Le Socle V4 conserve et étend l’architecture V3 en ajoutant :

2. Philosophie « MOP Pilote Tout »

Le Main Orchestrator Process est le cœur du framework :

┌─────────────────────────────────────────────────────────────────┐
│                           MOP                                    │
│  - Orchestre tous les Workers                                   │
│  - Gère le lifecycle (start/stop)                               │
│  - Appelle doWork() automatiquement                             │
│  - Garantit le shutdown gracieux                                │
└─────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
    ┌─────────┐         ┌─────────┐         ┌─────────┐
    │ Worker  │         │ Worker  │         │  HTTP   │
    │ Métier  │         │ Métier  │         │ Worker  │
    └─────────┘         └─────────┘         └─────────┘

Principes clés

1. Orchestration centralisée : Le MOP contrôle tout le lifecycle
2. Démarrage ordonné : Workers par priorité (petit → grand), HTTP en dernier
3. Arrêt gracieux : HTTP d’abord (drain), puis Workers
4. Scheduling automatique : doWork() appelé selon cron ou interval

3. Les 4 principes fondamentaux V4

3.1 Portabilité

• Fonctionne sur ARM/AMD64, Linux/macOS
• Aucune dépendance serveur externe obligatoire
• Base H2 embarquée pour l’état technique

3.2 Sécurité

• Aucun port entrant sur les NUC/agents
• Communication sortante uniquement (HTTP/NATS)
• Authentification JWT pour les services centraux

3.3 Observabilité

• Logs centralisés via LogForwarder
• Corrélation par correlationId / execId
• Suivi des workers via Registry

3.4 Standardisation

• Même authentification partout
• Même format de logs
• Même enregistrement des workers

4. Stack technique

5. Composants du Socle

Composants V3 (conservés)

Nouveaux composants V4

6. Cas d’usage

Le Socle V4 est idéal pour :

• Agents de collecte (DB2 Journal Reader, CDC)
• Services de synchronisation (ODH-sync)
• Proxies et bridges (Kafka Proxy)
• Workers de traitement (ETL, pipelines)
• Services multi-région (MTQ, GUA, REU, etc.)

7. Prérequis

Développement

• JDK 21+
• Maven 3.9+
• IDE (IntelliJ IDEA recommandé)

Production

• JRE 21+
• Docker (optionnel)
• Accès NATS ou HTTP pour LogForwarder (optionnel)

8. Premiers pas

# Cloner le projet
git clone <repo>/socle-v004.git

# Build
cd socle-v004
mvn clean package -DskipTests

# Run
java -jar target/socle-v004-4.0.0.jar

# Vérifier
curl http://localhost:8080/health

9. Documentation

10. Support

• Issues : GitHub Issues
• Documentation : Ce dossier docs/Help/
• Exemples : 20-EXEMPLES

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

01 – Introduction au Socle V4

Version : 4.0.0 Date : 2025-01-25

1. Qu’est-ce que le Socle V4 ?

Le Socle V4 est un framework Java de grade production construit sur Spring Boot 3.2.1 qui implémente le pattern MOP (Main Orchestrator Process). Il fournit une base solide pour construire des applications d’entreprise robustes et observables.

Évolution depuis V3

Le Socle V4 conserve et étend l’architecture V3 en ajoutant :

2. Philosophie « MOP Pilote Tout »

Le Main Orchestrator Process est le cœur du framework :

┌─────────────────────────────────────────────────────────────────┐
│                           MOP                                    │
│  - Orchestre tous les Workers                                   │
│  - Gère le lifecycle (start/stop)                               │
│  - Appelle doWork() automatiquement                             │
│  - Garantit le shutdown gracieux                                │
└─────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
    ┌─────────┐         ┌─────────┐         ┌─────────┐
    │ Worker  │         │ Worker  │         │  HTTP   │
    │ Métier  │         │ Métier  │         │ Worker  │
    └─────────┘         └─────────┘         └─────────┘

Principes clés

1. Orchestration centralisée : Le MOP contrôle tout le lifecycle
2. Démarrage ordonné : Workers par priorité (petit → grand), HTTP en dernier
3. Arrêt gracieux : HTTP d’abord (drain), puis Workers
4. Scheduling automatique : doWork() appelé selon cron ou interval

3. Les 4 principes fondamentaux V4

3.1 Portabilité

• Fonctionne sur ARM/AMD64, Linux/macOS
• Aucune dépendance serveur externe obligatoire
• Base H2 embarquée pour l’état technique

3.2 Sécurité

• Aucun port entrant sur les NUC/agents
• Communication sortante uniquement (HTTP/NATS)
• Authentification JWT pour les services centraux

3.3 Observabilité

• Logs centralisés via LogForwarder
• Corrélation par correlationId / execId
• Suivi des workers via Registry

3.4 Standardisation

• Même authentification partout
• Même format de logs
• Même enregistrement des workers

4. Stack technique

5. Composants du Socle

Composants V3 (conservés)

Nouveaux composants V4

6. Cas d’usage

Le Socle V4 est idéal pour :

• Agents de collecte (DB2 Journal Reader, CDC)
• Services de synchronisation (ODH-sync)
• Proxies et bridges (Kafka Proxy)
• Workers de traitement (ETL, pipelines)
• Services multi-région (MTQ, GUA, REU, etc.)

7. Prérequis

Développement

• JDK 21+
• Maven 3.9+
• IDE (IntelliJ IDEA recommandé)

Production

• JRE 21+
• Docker (optionnel)
• Accès NATS ou HTTP pour LogForwarder (optionnel)

8. Premiers pas

# Cloner le projet
git clone <repo>/socle-v004.git

# Build
cd socle-v004
mvn clean package -DskipTests

# Run
java -jar target/socle-v004-4.0.0.jar

# Vérifier
curl http://localhost:8080/health

9. Documentation

10. Support

• Issues : GitHub Issues
• Documentation : Ce dossier docs/Help/
• Exemples : 20-EXEMPLES

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

13 – TLS/HTTPS

Version : 4.0.0 Date : 2025-12-09

1. Introduction

Configuration du TLS/HTTPS pour sécuriser les communications HTTP du Socle V4.

2. Configuration Spring Boot

2.1 application.yml

server:
  port: ${HTTPS_PORT:8443}
  ssl:
    enabled: ${SSL_ENABLED:true}
    key-store: ${SSL_KEYSTORE:classpath:keystore.p12}
    key-store-password: ${SSL_KEYSTORE_PASSWORD:changeit}
    key-store-type: ${SSL_KEYSTORE_TYPE:PKCS12}
    key-alias: ${SSL_KEY_ALIAS:socle}

2.2 Variables d’environnement

3. Génération des certificats

3.1 Certificat auto-signé (développement)

# Générer un keystore PKCS12 avec certificat auto-signé
keytool -genkeypair \
  -alias socle \
  -keyalg RSA \
  -keysize 2048 \
  -storetype PKCS12 \
  -keystore keystore.p12 \
  -validity 365 \
  -dname "CN=localhost,OU=Dev,O=MyCompany,L=Paris,C=FR" \
  -storepass changeit \
  -keypass changeit

# Exporter le certificat (pour les clients)
keytool -exportcert \
  -alias socle \
  -keystore keystore.p12 \
  -storetype PKCS12 \
  -storepass changeit \
  -file socle.crt

3.2 Avec Let’s Encrypt (production)

# Obtenir le certificat
certbot certonly --standalone -d myapp.example.com

# Convertir en PKCS12
openssl pkcs12 -export \
  -in /etc/letsencrypt/live/myapp.example.com/fullchain.pem \
  -inkey /etc/letsencrypt/live/myapp.example.com/privkey.pem \
  -out keystore.p12 \
  -name socle \
  -passout pass:changeit

3.3 Avec CA interne

# Générer CSR
keytool -certreq \
  -alias socle \
  -keystore keystore.p12 \
  -file socle.csr \
  -storepass changeit

# Après signature par la CA, importer le certificat
keytool -importcert \
  -alias socle \
  -keystore keystore.p12 \
  -file signed-cert.crt \
  -storepass changeit

# Importer la chaîne CA
keytool -importcert \
  -alias ca-root \
  -keystore keystore.p12 \
  -file ca-root.crt \
  -storepass changeit

4. Configuration avancée

4.1 Mutual TLS (mTLS)

server:
  ssl:
    enabled: true
    key-store: ${SSL_KEYSTORE:keystore.p12}
    key-store-password: ${SSL_KEYSTORE_PASSWORD}
    key-store-type: PKCS12
    # Trust store pour vérifier les clients
    trust-store: ${SSL_TRUSTSTORE:truststore.p12}
    trust-store-password: ${SSL_TRUSTSTORE_PASSWORD}
    trust-store-type: PKCS12
    # Exiger certificat client
    client-auth: ${SSL_CLIENT_AUTH:need}  # none, want, need

4.2 Protocoles et Ciphers

server:
  ssl:
    enabled-protocols: TLSv1.3,TLSv1.2
    ciphers:
      - TLS_AES_256_GCM_SHA384
      - TLS_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

5. HTTP + HTTPS (dual port)

5.1 Configuration

@Configuration
public class TlsConfiguration {

    @Value("${server.http.port:8080}")
    private int httpPort;

    @Bean
    public ServletWebServerFactory servletContainer() {
        TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory();
        tomcat.addAdditionalTomcatConnectors(createHttpConnector());
        return tomcat;
    }

    private Connector createHttpConnector() {
        Connector connector = new Connector(TomcatServletWebServerFactory.DEFAULT_PROTOCOL);
        connector.setScheme("http");
        connector.setPort(httpPort);
        connector.setSecure(false);
        return connector;
    }
}

5.2 Redirection HTTP → HTTPS

@Configuration
public class HttpsRedirectConfiguration {

    @Bean
    public TomcatServletWebServerFactory servletContainer() {
        TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory() {
            @Override
            protected void postProcessContext(Context context) {
                SecurityConstraint securityConstraint = new SecurityConstraint();
                securityConstraint.setUserConstraint("CONFIDENTIAL");
                SecurityCollection collection = new SecurityCollection();
                collection.addPattern("/*");
                securityConstraint.addCollection(collection);
                context.addConstraint(securityConstraint);
            }
        };

        tomcat.addAdditionalTomcatConnectors(httpToHttpsRedirectConnector());
        return tomcat;
    }

    private Connector httpToHttpsRedirectConnector() {
        Connector connector = new Connector(TomcatServletWebServerFactory.DEFAULT_PROTOCOL);
        connector.setScheme("http");
        connector.setPort(8080);
        connector.setSecure(false);
        connector.setRedirectPort(8443);
        return connector;
    }
}

6. Client HTTPS

6.1 OkHttpClient avec TLS

@Configuration
public class HttpClientConfiguration {

    @Value("${ssl.truststore:#{null}}")
    private Resource trustStore;

    @Value("${ssl.truststore-password:changeit}")
    private String trustStorePassword;

    @Bean
    public OkHttpClient secureHttpClient() throws Exception {
        OkHttpClient.Builder builder = new OkHttpClient.Builder();

        if (trustStore != null && trustStore.exists()) {
            KeyStore ks = KeyStore.getInstance("PKCS12");
            try (InputStream is = trustStore.getInputStream()) {
                ks.load(is, trustStorePassword.toCharArray());
            }

            TrustManagerFactory tmf = TrustManagerFactory.getInstance(
                TrustManagerFactory.getDefaultAlgorithm());
            tmf.init(ks);

            SSLContext sslContext = SSLContext.getInstance("TLS");
            sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());

            builder.sslSocketFactory(sslContext.getSocketFactory(),
                (X509TrustManager) tmf.getTrustManagers()[0]);
        }

        return builder
            .connectTimeout(30, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .build();
    }
}

6.2 Bypass SSL pour développement (NON RECOMMANDÉ)

// UNIQUEMENT POUR LE DÉVELOPPEMENT - NE PAS UTILISER EN PRODUCTION
public OkHttpClient insecureClient() throws Exception {
    TrustManager[] trustAllCerts = new TrustManager[]{
        new X509TrustManager() {
            public void checkClientTrusted(X509Certificate[] chain, String authType) {}
            public void checkServerTrusted(X509Certificate[] chain, String authType) {}
            public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; }
        }
    };

    SSLContext sslContext = SSLContext.getInstance("TLS");
    sslContext.init(null, trustAllCerts, new SecureRandom());

    return new OkHttpClient.Builder()
        .sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager) trustAllCerts[0])
        .hostnameVerifier((hostname, session) -> true)
        .build();
}

7. Docker avec TLS

7.1 Dockerfile

FROM eclipse-temurin:21-jre

WORKDIR /app

# Copier le certificat
COPY keystore.p12 /app/certs/keystore.p12

# Copier l'application
COPY target/socle-v004-4.0.0.jar app.jar

ENV SSL_ENABLED=true
ENV SSL_KEYSTORE=/app/certs/keystore.p12

EXPOSE 8443

ENTRYPOINT ["java", "-jar", "app.jar"]

7.2 docker-compose.yml

version: '3.8'

services:
  socle-app:
    image: socle-v4:latest
    environment:
      - SSL_ENABLED=true
      - SSL_KEYSTORE=/app/certs/keystore.p12
      - SSL_KEYSTORE_PASSWORD_FILE=/run/secrets/ssl_password
    ports:
      - "8443:8443"
    volumes:
      - ./certs:/app/certs:ro
    secrets:
      - ssl_password

secrets:
  ssl_password:
    file: ./secrets/ssl_password.txt

8. Kubernetes avec TLS

8.1 Secret pour le certificat

apiVersion: v1
kind: Secret
metadata:
  name: socle-tls
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-cert>
  tls.key: <base64-encoded-key>

8.2 Ingress avec TLS

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: socle-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  tls:
    - hosts:
        - socle.example.com
      secretName: socle-tls
  rules:
    - host: socle.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: socle-service
                port:
                  number: 8080

8.3 cert-manager

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: socle-cert
spec:
  secretName: socle-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - socle.example.com

9. Vérification

9.1 Test avec curl

# Test HTTPS
curl -v https://localhost:8443/admin/health

# Avec certificat client (mTLS)
curl -v --cert client.crt --key client.key https://localhost:8443/admin/health

# Ignorer la vérification (dev only)
curl -vk https://localhost:8443/admin/health

9.2 Test avec openssl

# Vérifier le certificat du serveur
openssl s_client -connect localhost:8443 -showcerts

# Vérifier les protocoles supportés
openssl s_client -connect localhost:8443 -tls1_3

# Vérifier les ciphers
openssl s_client -connect localhost:8443 -cipher 'ECDHE-RSA-AES256-GCM-SHA384'

10. Troubleshooting

Erreur: PKIX path building failed

Le certificat du serveur n’est pas trusté.

# Importer le certificat dans le truststore Java
keytool -importcert \
  -alias server-cert \
  -file server.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit

Erreur: Handshake failure

Incompatibilité de protocole ou cipher.

# Vérifier les protocoles
openssl s_client -connect host:port -tls1_2
openssl s_client -connect host:port -tls1_3

Erreur: Certificate expired

Renouveler le certificat et recréer le keystore.

11. Bonnes pratiques

DO

• Utiliser TLS 1.2 minimum, TLS 1.3 recommandé
• Renouveler les certificats avant expiration
• Utiliser des clés RSA 2048 bits minimum ou ECDSA 256 bits
• Activer HSTS en production
• Utiliser cert-manager en Kubernetes

DON’T

• Ne pas utiliser de certificats auto-signés en production
• Ne pas désactiver la vérification des certificats
• Ne pas stocker les mots de passe en clair
• Ne pas utiliser TLS 1.0 ou 1.1 (dépréciés)

12. Références

• 10-SECURITY – Sécurité
• Let’s Encrypt
• cert-manager