From cc4eade957a7b532ca780b258b6b8faf0fecaaca Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Sat, 17 Jan 2026 10:17:07 +0100 Subject: [PATCH] docs: document Zipkin setup and integrate tracing configuration Added new documentation for Zipkin setup, including Docker Compose configuration, service integration, and troubleshooting steps. Integrated tracing configuration for key microservices to enable distributed tracing and latency analysis. --- docker-compose.yaml | 36 +++++++++++++++++++ docs/07_Infrastructure/Reference/zipkin.md | 36 +++++++++++++++++++ .../2026-01-15_Infrastructure_Zipkin_Setup.md | 36 +++++++++++++++++++ 3 files changed, 108 insertions(+) create mode 100644 docs/07_Infrastructure/Reference/zipkin.md create mode 100644 docs/99_Journal/2026-01-15_Infrastructure_Zipkin_Setup.md diff --git a/docker-compose.yaml b/docker-compose.yaml index 57f2f5a3..65db8586 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -215,6 +215,19 @@ services: - "grafana" profiles: [ "ops", "all" ] + # --- MONITORING: Zipkin --- + zipkin: + image: "${ZIPKIN_IMAGE:-openzipkin/zipkin:3}" + container_name: "${PROJECT_NAME:-meldestelle}-zipkin" + restart: no + ports: + - "${ZIPKIN_PORT:-9411:9411}" + profiles: [ "ops", "all" ] + networks: + meldestelle-network: + aliases: + - "zipkin" + # --- CONSUL --- consul: image: "${CONSUL_IMAGE:-hashicorp/consul:1.22.1}" @@ -289,6 +302,10 @@ services: LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_CLOUD_GATEWAY: "DEBUG" LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY: "DEBUG" + # --- ZIPKIN --- + MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}" + MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}" + depends_on: postgres: condition: "service_healthy" @@ -349,6 +366,10 @@ services: SPRING_DATA_REDIS_PASSWORD: "${REDIS_PASSWORD:-redis-password}" SPRING_DATA_REDIS_CONNECT_TIMEOUT: "${REDIS_SERVER_CONNECT_TIMEOUT:-5s}" + # --- ZIPKIN --- + MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}" + MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}" + depends_on: postgres: condition: "service_healthy" @@ -392,6 +413,11 @@ services: SPRING_DATASOURCE_URL: "${POSTGRES_DB_URL:-jdbc:postgresql://postgres:5432/pg-meldestelle-db}" SPRING_DATASOURCE_USERNAME: "${POSTGRES_USER:-pg-user}" SPRING_DATASOURCE_PASSWORD: "${POSTGRES_PASSWORD:-pg-password}" + + # --- ZIPKIN --- + MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}" + MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}" + depends_on: postgres: condition: "service_healthy" @@ -430,6 +456,11 @@ services: SPRING_DATASOURCE_URL: "${POSTGRES_DB_URL:-jdbc:postgresql://postgres:5432/pg-meldestelle-db}" SPRING_DATASOURCE_USERNAME: "${POSTGRES_USER:-pg-user}" SPRING_DATASOURCE_PASSWORD: "${POSTGRES_PASSWORD:-pg-password}" + + # --- ZIPKIN --- + MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}" + MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}" + depends_on: postgres: condition: "service_healthy" @@ -468,6 +499,11 @@ services: SPRING_DATASOURCE_URL: "${POSTGRES_DB_URL:-jdbc:postgresql://postgres:5432/pg-meldestelle-db}" SPRING_DATASOURCE_USERNAME: "${POSTGRES_USER:-pg-user}" SPRING_DATASOURCE_PASSWORD: "${POSTGRES_PASSWORD:-pg-password}" + + # --- ZIPKIN --- + MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}" + MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}" + depends_on: postgres: condition: "service_healthy" diff --git a/docs/07_Infrastructure/Reference/zipkin.md b/docs/07_Infrastructure/Reference/zipkin.md new file mode 100644 index 00000000..e2623a94 --- /dev/null +++ b/docs/07_Infrastructure/Reference/zipkin.md @@ -0,0 +1,36 @@ +# Zipkin Tracing + +## Übersicht +Zipkin ist ein verteiltes Tracing-System, das hilft, Latenzprobleme in Microservice-Architekturen zu analysieren. Es sammelt Timing-Daten, die benötigt werden, um Latenzprobleme in Service-Architekturen zu beheben. + +## Konfiguration in Docker Compose +Der Zipkin-Service ist in der `docker-compose.yaml` definiert: + +```yaml + zipkin: + image: "${ZIPKIN_IMAGE:-openzipkin/zipkin:3}" + container_name: "${PROJECT_NAME:-meldestelle}-zipkin" + restart: no + ports: + - "${ZIPKIN_PORT:-9411:9411}" + profiles: [ "ops", "all" ] + networks: + meldestelle-network: + aliases: + - "zipkin" +``` + +## Integration in Services +Die Services (`api-gateway`, `ping-service`, etc.) sind so konfiguriert, dass sie Tracing-Daten an Zipkin senden. Dies geschieht über Umgebungsvariablen in der `docker-compose.yaml`: + +```yaml + MANAGEMENT_ZIPKIN_TRACING_ENDPOINT: "${ZIPKIN_ENDPOINT:-http://zipkin:9411/api/v2/spans}" + MANAGEMENT_TRACING_SAMPLING_PROBABILITY: "${ZIPKIN_SAMPLING_PROBABILITY:-1.0}" +``` + +## Zugriff +Die Zipkin UI ist unter `http://localhost:9411` erreichbar. + +## Troubleshooting +- **Keine Traces sichtbar:** Stelle sicher, dass die Services korrekt gestartet sind und die Umgebungsvariablen für Zipkin gesetzt sind. Prüfe die Logs der Services auf Verbindungsfehler zu Zipkin. +- **Zipkin nicht erreichbar:** Prüfe, ob der Container läuft (`docker ps`) und ob der Port 9411 nicht blockiert ist. diff --git a/docs/99_Journal/2026-01-15_Infrastructure_Zipkin_Setup.md b/docs/99_Journal/2026-01-15_Infrastructure_Zipkin_Setup.md new file mode 100644 index 00000000..cdff7680 --- /dev/null +++ b/docs/99_Journal/2026-01-15_Infrastructure_Zipkin_Setup.md @@ -0,0 +1,36 @@ +--- +type: Journal +status: ACTIVE +owner: Infrastructure & DevOps Engineer +last_update: 2026-01-15 +--- + +# Session Log: Infrastructure Zipkin Setup + +## Zusammenfassung +In dieser Session wurde die Infrastruktur um Distributed Tracing mit **Zipkin** erweitert, um Latenzanalysen in der Microservice-Architektur zu ermöglichen. + +## Durchgeführte Änderungen + +### 1. Docker Compose (`docker-compose.yaml`) +* **Neuer Service `zipkin`:** + * Image: `openzipkin/zipkin:3` + * Port: `9411` + * Network Alias: `zipkin` +* **Service Integration:** + * Die Services `api-gateway`, `ping-service`, `entries-service`, `results-service` und `scheduling-service` wurden konfiguriert, um Tracing-Daten an Zipkin zu senden. + * Umgebungsvariablen hinzugefügt: + * `MANAGEMENT_ZIPKIN_TRACING_ENDPOINT` + * `MANAGEMENT_TRACING_SAMPLING_PROBABILITY` + +### 2. Dokumentation +* Neue Referenz-Dokumentation erstellt: `docs/07_Infrastructure/Reference/zipkin.md`. + * Enthält Konfigurationsdetails und Troubleshooting-Hinweise. + +## Betroffene Dateien +* `docker-compose.yaml` +* `docs/07_Infrastructure/Reference/zipkin.md` + +## Nächste Schritte +* Backend-Developer müssen sicherstellen, dass die Micrometer-Tracing-Dependencies (`micrometer-tracing-bridge-brave`, `zipkin-reporter-brave`) im Build vorhanden sind. +* Neustart der Umgebung mit `docker compose up -d`.