Infrastructure/Monitoring Modul – Aktuelle Dokumentation (Stand: September 2025)

Überblick

Das Monitoring-Modul stellt die zentrale Observability-Infrastruktur für alle Services bereit. Es deckt zwei der drei Observability-Säulen ab: Metriken und Distributed Tracing. Ziel ist es, Betriebsdaten konsistent zu erfassen, zu visualisieren und Probleme schnell zu erkennen.

Metriken: Quantitative Leistungsdaten wie Antwortzeiten, Fehlerraten, JVM- und Systemmetriken.
Distributed Tracing: Ende-zu-Ende-Verfolgung einer Anfrage über Service-Grenzen hinweg (Trace/Span).

Aufgabe des Moduls

Bereitstellung einer einheitlichen Monitoring-Client-Bibliothek für alle Microservices.
Zentrale Bereitstellung eines Zipkin-Servers zur Sammlung und Visualisierung von Traces.
Sicherstellung eines konsistenten Prometheus-/Micrometer-Setups über alle Services hinweg.
Bereitstellung konservativer Default-Properties, die pro Service überschrieben werden können.

Architektur

Das Modul ist in eine wiederverwendbare Client-Bibliothek und einen zentralen Server aufgeteilt:

infrastructure/monitoring/
├── monitoring-client/      # Bibliothek, die jeder Service einbindet
└── monitoring-server/      # Eigenständiger Service, der den Zipkin-Server hostet

monitoring-client

Dies ist eine wiederverwendbare Bibliothek, die von jedem Microservice (z. B. gateway, members, masterdata) eingebunden wird.

Zweck: Automatische Instrumentierung der Anwendung, Aktivierung von Actuator-/Tracing-Funktionen und Export von Metriken.
Technologien:
- Spring Boot Actuator: Stellt u. a. den Endpunkt /actuator/prometheus bereit.
- Micrometer (Core, Prometheus): Einheitliches Metrik-API, Export in Prometheus-Format.
- Micrometer Tracing (Brave Bridge) + Zipkin Reporter: Erzeugt und sendet Traces (Spans) an Zipkin.
Vorteile: Keine individuelle Konfiguration in jedem Service nötig; sinnvolle Defaults per AutoConfiguration.

AutoConfiguration und Defaults

Die Klasse MonitoringClientAutoConfiguration ist als @AutoConfiguration deklariert und aktiviert nur, wenn Actuator/Micrometer am Classpath sind (@ConditionalOnClass). Sie lädt monitoring-defaults.properties mit niedriger Priorität. Wichtige Defaults:

management.endpoints.web.exposure.include=health,info,prometheus
management.tracing.enabled=true
management.tracing.sampling.probability=${TRACING_SAMPLING_PROBABILITY:1.0}
management.observations.http.server.requests.enabled=true
management.info.env.enabled=true
management.zipkin.tracing.endpoint=http://zipkin:9411/api/v2/spans

Hinweise:

Sampling-Rate: In Entwicklung 1.0 (100%). In Produktion sollte dies reduziert werden (z. B. 0.1).
Endpunkte: Der Prometheus-Scrape-Pfad ist einheitlich /actuator/prometheus.
Überschreibung: Jede Anwendung kann diese Werte über application.yml/-properties anpassen.

monitoring-server

Eigenständiger Spring-Boot-Service, der den Zipkin-Server hostet. Durch die Zipkin-Server-Abhängigkeit erfolgt die Auto-Konfiguration; eine explizite @EnableZipkinServer-Annotation ist nicht erforderlich.

Zweck: Empfang und UI-Visualisierung von Traces aus allen Services.
Metriken: Der Server exportiert eigene Metriken (Prometheus-Registry eingebunden), sodass er ebenfalls von Prometheus gescraped werden kann.

Zusammenspiel im System

Jeder Microservice bindet :infrastructure:monitoring:monitoring-client ein und exponiert /actuator/prometheus; Traces werden an Zipkin gesendet.
Der :infrastructure:monitoring:monitoring-server empfängt Traces und stellt die Zipkin UI bereit.
Prometheus (docker-compose) scraped periodisch alle /actuator/prometheus-Endpunkte und speichert Metriken.
Grafana (docker-compose) visualisiert Metriken/Dashboards.

Diese Kombination aus Micrometer, Prometheus, Zipkin und Grafana bildet einen gängigen Production-Stack.

Verwendung in Services

Abhängigkeit hinzufügen: implementation(projects.infrastructure.monitoring.monitoringClient) (über build.gradle.kts der Services).
Optional: Eigene Tags setzen (z. B. management.metrics.tags.application, environment).
Optional: Sampling-Rate via Umgebungsvariable TRACING_SAMPLING_PROBABILITY anpassen.

Beispiel (application.yml):

management:
  metrics:
    tags:
      application: ${spring.application.name}
      environment: ${SPRING_PROFILES_ACTIVE:dev}
  tracing:
    sampling:
      probability: 0.2

Testing-Strategie (Tracer-Bullet-Zyklus)

Monitoring-Server: Ein grundlegender Smoke-Test prüft erfolgreichen Start der Anwendung.
Monitoring-Client: Keine dedizierten Unit-Tests; Validierung erfolgt End-to-End durch integrierte Services (Prometheus scrape, Zipkin-Empfang).

Aktualitäts-Check (Repo-Stand September 2025)

monitoring-client: AutoConfiguration (Deutsch kommentiert) und Defaults vorhanden; Endpunkt management.zipkin.tracing.endpoint verweist auf zipkin:9411 und entspricht docker-compose.
monitoring-server: Kotlin-Hauptklasse startet Zipkin-Server; Build-Datei bindet Actuator, Zipkin-Server und Prometheus-Registry ein.
Gateway application.yml exponiert Actuator-Endpunkte inkl. prometheus; passt zum Monitoring-Ansatz.

Optimierungen (September 2025)

Dokumentation präzisiert und vollständig auf Deutsch gebracht; Zweck und Umsetzung klar herausgestellt.
Kleine Konsistenz-Anpassung: Kommentare im Wurzel-Build-Skript des Monitoring-Moduls ins Deutsche übertragen.
Empfehlung (optional, nicht zwingend umgesetzt):
- Standard-Tags global setzen (application, environment, instance) via management.metrics.tags.*.
- Falls Services eigene MeterRegistry konfigurieren: @ConditionalOnMissingBean beachten, um Kollisionen zu vermeiden.

Letzte Aktualisierung: 4. September 2025

5.7 KiB Raw Blame History Unescape Escape