Socle V004 – Migration V3 vers V4

Écrit par

jmh

dans

Blog, TheSocle

25 – Guide de Migration V3 → V4

Version : 4.0.0 Date : 2025-12-09

1. Résumé des changements

1.1 Ce qui change

Aspect	V3	V4
Logging	Logback	Log4j2 + LogForwarder
Persistance technique	In-memory/Redis	+ H2 TechDB
Auth	AdminAuthFilter local	+ SocleAuthClient JWT
Registry	Supervisor local	+ WorkerRegistryClient

1.2 Ce qui ne change PAS

Architecture MOP
Interface Worker
KvBus (in_memory / Redis)
SharedDataRegistry
Supervisor
HttpWorker
AdminRestApi
PipelineEngine
CircuitBreaker / Retry
Scheduler

2. Checklist de migration

□ Phase 1: Préparation
  □ Lire ce guide en entier
  □ Backup du projet V3
  □ Créer branche migration-v4

□ Phase 2: Dépendances Maven
  □ Mettre à jour pom.xml
  □ Exclure Logback
  □ Ajouter Log4j2
  □ Ajouter H2

□ Phase 3: Configuration
  □ Créer log4j2.xml
  □ Créer log4j2.component.properties
  □ Supprimer logback-spring.xml
  □ Mettre à jour application.yml

□ Phase 4: Code (optionnel)
  □ Intégrer TechDbManager
  □ Intégrer SocleAuthClient
  □ Intégrer WorkerRegistryClient

□ Phase 5: Tests
  □ Compiler
  □ Exécuter les tests
  □ Vérifier les logs
  □ Valider H2 Console

□ Phase 6: Déploiement
  □ Variables d'environnement
  □ Test en staging
  □ Déploiement production

3. Phase 1 : Préparation

3.1 Backup

# Backup du projet V3
cp -r socle-v003 socle-v003-backup

# Créer branche
cd socle-v003
git checkout -b migration-v4

3.2 Version cible

<version>4.0.0</version>

4. Phase 2 : Dépendances Maven

4.1 Modifications pom.xml

<!-- AVANT (V3) -->
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
</dependency>
<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
</dependency>

<!-- APRÈS (V4) -->
<!-- Exclure Logback de Spring Boot -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Log4j2 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

<!-- LMAX Disruptor -->
<dependency>
    <groupId>com.lmax</groupId>
    <artifactId>disruptor</artifactId>
    <version>4.0.0</version>
</dependency>

<!-- H2 Database -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.2.224</version>
</dependency>

4.2 Vérifier les exclusions

S’assurer que Logback est exclu de TOUTES les dépendances Spring Boot :

mvn dependency:tree | grep logback
# Ne doit rien retourner

5. Phase 3 : Configuration

5.1 Créer log4j2.xml

Créer src/main/resources/log4j2.xml :

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">
    <Properties>
        <Property name="LOG_DIR">${env:LOG_DIR:-./logs}</Property>
        <Property name="APP_NAME">${env:APP_NAME:-socle-v4}</Property>
    </Properties>

    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n"/>
        </Console>

        <RollingFile name="File"
                     fileName="${LOG_DIR}/${APP_NAME}.log"
                     filePattern="${LOG_DIR}/${APP_NAME}-%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n"/>
            <Policies>
                <TimeBasedTriggeringPolicy interval="1"/>
                <SizeBasedTriggeringPolicy size="100MB"/>
            </Policies>
            <DefaultRolloverStrategy max="30"/>
        </RollingFile>
    </Appenders>

    <Loggers>
        <Logger name="eu.lmvi.socle" level="${env:LOG_LEVEL:-INFO}" additivity="false">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="File"/>
        </Logger>
        <Logger name="org.springframework" level="WARN"/>
        <Root level="INFO">
            <AppenderRef ref="Console"/>
            <AppenderRef ref="File"/>
        </Root>
    </Loggers>
</Configuration>

5.2 Créer log4j2.component.properties

Créer src/main/resources/log4j2.component.properties :

Log4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector
AsyncLogger.RingBufferSize=262144
AsyncLogger.WaitStrategy=Sleep
log4j2.formatMsgNoLookups=true

5.3 Supprimer logback-spring.xml

rm src/main/resources/logback-spring.xml

5.4 Mettre à jour application.yml

Ajouter les nouvelles configurations V4 :

# Ajouter à application.yml existant

socle:
  # ... config V3 existante ...

  # NOUVEAU V4: H2 TechDB
  techdb:
    enabled: ${TECHDB_ENABLED:true}
    url: jdbc:h2:file:${TECHDB_PATH:./data/socle-techdb};MODE=PostgreSQL;DB_CLOSE_DELAY=-1
    username: socle
    password: ${TECHDB_PASSWORD:socle}
    console:
      enabled: ${H2_CONSOLE_ENABLED:false}
      path: /h2-console

  # NOUVEAU V4: LogForwarder (optionnel)
  logging:
    forwarder:
      enabled: ${LOG_FORWARDER_ENABLED:false}
      transport-mode: ${LOG_TRANSPORT_MODE:http}
      log-hub-url: ${LOG_HUB_URL:}

  # NOUVEAU V4: Auth Client (optionnel)
  auth:
    enabled: ${AUTH_ENABLED:false}
    server-url: ${AUTH_SERVER_URL:}
    api-key: ${API_KEY:}

  # NOUVEAU V4: Worker Registry (optionnel)
  worker-registry:
    enabled: ${WORKER_REGISTRY_ENABLED:false}
    server-url: ${WORKER_REGISTRY_URL:}

# Logging
logging:
  config: classpath:log4j2.xml

6. Phase 4 : Code (optionnel)

Les composants V4 sont optionnels et activés via configuration. Aucune modification de code n’est obligatoire.

6.1 Si vous voulez utiliser TechDB

@Autowired(required = false)
private TechDbManager techDbManager;

// Utilisation
if (techDbManager != null) {
    techDbManager.saveOffset("kafka", "topic-0", offset, null);
}

6.2 Si vous voulez utiliser AuthClient

@Autowired(required = false)
private SocleAuthClient authClient;

// Utilisation
if (authClient != null && authClient.isAuthenticated()) {
    String token = authClient.getValidAccessToken();
}

6.3 Si vous voulez utiliser WorkerRegistry

@Autowired(required = false)
private WorkerRegistryClient registryClient;

// L'intégration MOP est automatique si enabled

7. Phase 5 : Tests

7.1 Compilation

mvn clean compile

Erreurs possibles :

package ch.qos.logback does not exist → Logback pas complètement exclu
cannot find symbol: class Logger → Import SLF4J correct ?

7.2 Tests unitaires

mvn test

7.3 Vérification logs

mvn spring-boot:run

Vérifier :

Logs apparaissent en console
Format correct
Pas d’erreur Log4j2

7.4 H2 Console

Si H2_CONSOLE_ENABLED=true :

Ouvrir http://localhost:8080/h2-console
JDBC URL: jdbc:h2:file:./data/socle-techdb
Vérifier les tables créées

8. Phase 6 : Déploiement

8.1 Variables d’environnement (minimum)

# Existantes V3 (inchangées)
APP_NAME=my-app
ENV_NAME=PROD
HTTP_PORT=8080

# Nouvelles V4 (optionnelles)
TECHDB_ENABLED=true
TECHDB_PATH=./data/techdb
H2_CONSOLE_ENABLED=false
LOG_FORWARDER_ENABLED=false
AUTH_ENABLED=false
WORKER_REGISTRY_ENABLED=false

8.2 Docker

Mettre à jour le Dockerfile si nécessaire :

# Pas de changement requis si vous utilisez le JAR
FROM eclipse-temurin:21-jre
COPY target/socle-v004-4.0.0.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

8.3 Kubernetes

Mettre à jour les ConfigMaps/Secrets avec les nouvelles variables.

9. Mapping des configurations

9.1 Logback → Log4j2

Logback	Log4j2
`<appender class="ConsoleAppender">`	`<Console name="...">`
`<appender class="RollingFileAppender">`	`<RollingFile name="...">`
`<encoder><pattern>`	`<PatternLayout pattern="...">`
`<root level="INFO">`	`<Root level="INFO">`
`<logger name="..." level="...">`	`<Logger name="..." level="...">`

9.2 Pattern identique

Le pattern de log reste identique :

%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n

10. Rollback

En cas de problème, pour revenir à V3 :

# Restaurer le pom.xml V3
git checkout HEAD~1 -- pom.xml

# Restaurer logback-spring.xml
git checkout HEAD~1 -- src/main/resources/logback-spring.xml

# Supprimer fichiers V4
rm src/main/resources/log4j2.xml
rm src/main/resources/log4j2.component.properties

# Rebuild
mvn clean package

11. FAQ

Q: Dois-je modifier mon code de logging ?

Non. Le code reste identique :

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger log = LoggerFactory.getLogger(MyClass.class);
log.info("Message");

Q: Les MDC fonctionnent-ils ?

Oui. MDC fonctionne de manière identique avec Log4j2.

Q: Puis-je activer les fonctionnalités V4 progressivement ?

Oui. Toutes les fonctionnalités V4 sont optionnelles :

TECHDB_ENABLED=false → Pas de H2
LOG_FORWARDER_ENABLED=false → Pas de LogForwarder
AUTH_ENABLED=false → Pas d’auth JWT
WORKER_REGISTRY_ENABLED=false → Pas de registry

Q: Performance : V4 est-il plus rapide ?

Oui pour le logging. Log4j2 avec AsyncLoggers (LMAX Disruptor) est 6-68x plus rapide que Logback en mode async.

12. Références

01-INTRODUCTION – Introduction V4
21-H2-TECHDB – H2 TechDB
22-LOG4J2-LOGFORWARDER – Log4j2
23-AUTH-CLIENT – Auth Client
24-WORKER-REGISTRY – Worker Registry

Coding Computers