docs: finalize and verify Zipkin integration in system hardening roadmap

Marked Zipkin integration tasks as completed and verified in archived roadmaps. Documented fixes for gateway propagation type (`w3c` → `b3`) and Zipkin endpoint configuration. Removed redundant dependencies in `build.gradle.kts` and updated related session logs. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-03-09 11:24:52 +01:00
parent 218c7fa13a
commit 2db3fd82c5
5 changed files with 45 additions and 8 deletions
@@ -32,7 +32,8 @@ dependencies {
  implementation(libs.spring.cloud.starter.circuitbreaker.reactor.resilience4j)

  implementation(libs.spring.data.valkey)
-  implementation(libs.micrometer.tracing.bridge.brave)
+  // micrometer-tracing-bridge-brave + zipkin-reporter-brave + zipkin-sender-okhttp3
+  // werden transitiv via :backend:infrastructure:monitoring:monitoringClient bereitgestellt.

  testImplementation(projects.platform.platformTesting)
 }
@@ -52,9 +52,15 @@ management:
        enabled: true # Aktiviert /actuator/health/liveness und /readiness
  tracing:
    sampling:
-      probability: 1.0
+      probability: ${TRACING_SAMPLING_PROBABILITY:1.0}
    propagation:
-      type: "w3c"
+      # B3 ist das native Format von Brave/Zipkin. W3C wäre für OpenTelemetry.
+      # Alle Services nutzen Brave (via monitoring-client), daher muss das Gateway ebenfalls B3 verwenden.
+      type: "b3"
+  zipkin:
+    tracing:
+      # Lokal: Zipkin auf Port 9411. In Docker via ENV MANAGEMENT_ZIPKIN_TRACING_ENDPOINT überschrieben.
+      endpoint: ${MANAGEMENT_ZIPKIN_TRACING_ENDPOINT:http://localhost:9411/api/v2/spans}

 # --- Custom Service URLs ---
 # Default: Localhost (für Entwicklung ohne Docker)
@@ -46,7 +46,8 @@ Implementierung des ersten vertikalen Durchstichs.
 - [ ] **Ping Service:** Implementierung von `:backend:services:ping:ping-service` mit Spring Boot 3.5.9.
 - [ ] **Security:** Integration von OAuth2 Resource Server (Keycloak) und Absicherung des `/secure` Endpoints.
 - [ ] **Discovery:** Registrierung bei Consul.
- [ ] **Observability:** Tracing mit Zipkin und Metrics mit Prometheus aktivieren.
+- [x] **Observability:** Tracing mit Zipkin und Metrics mit Prometheus aktivieren. _(verifiziert 2026-03-09:
+  monitoring-client Bundle + Gateway B3-Fix)_

 ---

@@ -52,9 +52,11 @@ last_update: 2026-03-09
  - `post.logout.redirect.uris` für alle Clients konfiguriert.

 ### 2.2 Observability
- [ ] **Zipkin Integration:** _(offen — Priorität: technische Stabilisierung)_
-    - Prüfen, ob Traces vom Gateway bis zur DB durchgereicht werden.
-    - Ggf. `micrometer-tracing-bridge-brave` konfigurieren.
+
+- [x] **Zipkin Integration:** _(verifiziert 2026-03-09)_
+  - `monitoring-client`-Bundle enthält alle nötigen Dependencies (bridge-brave, reporter-brave, sender-okhttp3).
+  - `dc-backend.yaml` setzt `MANAGEMENT_ZIPKIN_TRACING_ENDPOINT=http://zipkin:9411/api/v2/spans` für alle Services.
+  - Gateway-Fix: `propagation.type` von `w3c` auf `b3` korrigiert; Zipkin-Endpoint explizit ergänzt.

 ---

@@ -46,8 +46,35 @@ Sicherheitseinstellungen auf einen produktionsreifen Stand gebracht.
 Verifiziert: `micrometer = "1.16.1"` und `micrometerTracing = "1.6.1"` waren bereits korrekt in
 `gradle/libs.versions.toml` gesetzt — kein Code-Change erforderlich. Archiv-Roadmaps entsprechend abgehakt.

+## ✅ Zipkin Integration (2026-03-09, gleiche Session)
+
+Analyse ergab: Infrastruktur war bereits zu ~90% korrekt aufgebaut. Einzige Lücke war eine falsche
+Propagation-Konfiguration im Gateway.
+
+### Befund
+
+- `dc-infra.yaml`: Zipkin-Container (`openzipkin/zipkin:3`, Port 9411) bereits vorhanden.
+- `monitoring-client`-Bundle: enthält `micrometer-tracing-bridge-brave`, `zipkin-reporter-brave`,
+  `zipkin-sender-okhttp3` — von allen Services eingebunden.
+- `monitoring-defaults.properties`: setzt `management.zipkin.tracing.endpoint=http://localhost:9411/api/v2/spans`
+  als Default, überschreibbar via `MANAGEMENT_ZIPKIN_TRACING_ENDPOINT`.
+- `dc-backend.yaml`: setzt `MANAGEMENT_ZIPKIN_TRACING_ENDPOINT=http://zipkin:9411/api/v2/spans` für alle
+  Services inkl. Gateway.
+
+### Fix: Gateway `application.yaml`
+
+- **`management.tracing.propagation.type`**: `w3c` → `b3`
+  (B3 ist das native Format von Brave/Zipkin; W3C wäre für OpenTelemetry — Mismatch hätte
+  Trace-Korrelation zwischen Gateway und Services gebrochen).
+- **`management.zipkin.tracing.endpoint`**: Explizit mit lokalem Default + ENV-Override ergänzt.
+- **`TRACING_SAMPLING_PROBABILITY`**: Konsistent mit Services via ENV-Variable.
+
+### Fix: Gateway `build.gradle.kts`
+
+- Redundante direkte `micrometer-tracing-bridge-brave`-Dependency entfernt
+  (bereits transitiv via `monitoring-client` vorhanden).
+
 ## 🔜 Nächste Schritte

- **Zipkin Integration** — Tracing vom Gateway bis zur DB aktivieren.
 - **OIDC Client im Frontend** — Login-Flow mit `ktor-client-auth` und `frontend-client` implementieren.
 - **TLS/HTTPS** — Langfristig: `KC_HOSTNAME_STRICT_HTTPS=true` setzen, sobald TLS eingerichtet ist.