Skip to content

[Epic] Einführung von Tracing für Auth- und Service-Stack

Warum

Zur besseren Überwachung und Fehleranalyse unserer Anwendungen wollen wir übergreifendes Tracing einführen, welches via Kibana oder einer andere Anwendung visualisiert und ausgewertet werden kann. Dabei gilt v.a. folgende Begrifflichkeiten klar abzugrenzen:

  • Logs: Logs sind chronologische Einträge, die festhalten, was in einem System passiert ist. Sie geben detaillierte Einblicke in Ereignisse, sind jedoch oft isoliert und schwer zu korrelieren, besonders in verteilten Systemen.
  • Metrics: Metrics sind aggregierte Messwerte, die beispielsweise die Anzahl an Requests, Latenzzeiten oder Fehlerraten beschreiben. Sie sind ideal für das Monitoring und das Erkennen von Anomalien, bieten jedoch keinen direkten Einblick in den Kontext einzelner Transaktionen.
  • Traces: Traces füllen diese Lücke. Sie verfolgen den Weg einer einzelnen Anfrage durch alle beteiligten Dienste hinweg. So wird sichtbar, wie eine Anfrage durch das System fließt, welche Komponenten wie lange für ihre Aufgaben benötigen und wo mögliche Engpässe oder Fehler liegen.

Tracing verbindet damit die Detailtiefe der Logs mit der Systemübersicht der Metrics und ist somit ein unverzichtbares Werkzeug. Hiervon können die Entwickelnden und der Support massiv profitieren, um systemübergreifende Fehler ganzheitlich nachvollziehen zu können.

Hervorzuheben ist, dass Tracing eine Team und Software übergreifende Initiative sein muss und wird. Nimmt ein Service/System nicht Teil entstehen "blinde Flecken" oder bricht im schlimmsten Fall der Trace.

Was zeichnet einen Trace aus?

  • End-to-End-Verfolgung einer Anfrage: Ein Trace zeigt den Weg einer einzelnen Anfrage durch ein verteiltes System. Jede Station – vom Eingang in den ersten Service bis zur Verarbeitung durch nachgelagerte Dienste – wird abgebildet. Wenn das System instrumentiert ist!
  • Spans als Bausteine: Ein Trace besteht aus mehreren Spans:
    • Span: Ein Zeitabschnitt, der eine spezifische Operation beschreibt, z. B. eine Datenbankabfrage oder ein HTTP-Request.
    • Spans enthalten Metadaten wie Startzeit, Dauer, Status und optionale Tags oder Logs (z. B. Fehlermeldungen oder benutzerdefinierte Informationen).
    • Alle Spans eines Traces sind hierarchisch miteinander verbunden, sodass die Abhängigkeiten zwischen den Komponenten sichtbar werden.
  • Eindeutige Identifikation
    • Jeder Trace hat eine eindeutige Trace ID, die für die gesamte Anfrage gleich bleibt.
    • Jeder Span hat zusätzlich eine Span ID, die ihn eindeutig identifiziert. So kann die Hierarchie von Spans innerhalb eines Traces rekonstruiert werden.
  • Zusammenhang zwischen Komponenten
    • Tracing ermöglicht es, Abhängigkeiten zwischen Diensten und deren Einfluss auf die Gesamtperformance zu verstehen. Es zeigt beispielsweise, welcher Service wie lange auf eine Antwort gewartet hat oder ob eine Timeout-Schwelle überschritten wurde.
    • Traces werden häufig in einem zeitbasierten Aufrufsbaum (Call Tree) visualisiert.

Ziel

Es soll eine Technologie-Entscheidung bezüglich der Trace Datenbank und des dazugehörigen Frontends getroffen werden. Nachfolgend gilt es diese Technologien zu etablieren bzw die entsprechenden Systeme aufzusetzen.

Von eingehenden synchronen HTTP-Requests kann der Datenfluss vom traefik bis in das letzte uns bekannte bzw kontrollierte System nachvollzogen werden und so eine Kette von Aufrufen abgebildet werden. Hierzu haben wir schon einen PoC im Open Space am 22.01.2025 vorgestellt. Ziel dieses Epics soll sein, dass alle synchronen Calls von FIT-Connect instrumentiert werden und ins Tracing einfließen. Es stellt damit eine Basis für spätere Erweiterungen, Verbesserungen und eventuell nötige weitere Schritte dar.

Links, Hinweise, Bemerkungen

Feature Branches des PoC von Januar 2025:

Technologien & Libraries

Im Proof-Of-Concept eingesetzt

Mögliche Kandidaten für unser Tooling

Stories

Akzeptanzkriterien

  1. Technologie-Entscheidung bezüglich der Trace Datenbank und des dazugehörigen Frontend wurde getroffen
  2. OpenTelemetry als Protokoll wurde bestätigt oder eine alternative Entscheidung getroffen
  3. ZSD unterstützt Tracing (und gibt die Trace-ID bei Fehlern in der Payload zurück)
  4. Token-Validator unterstützt Tracing
  5. SSP unterstützt Tracing und gibt bestenfalls die Trace-ID im Fehlerdialog aus
  6. Die Instrumentierung des Connect2ID (OAuth) Servers und Keycloak wurde evaluiert und wenn möglich durchgeführt
  7. Die Instrumentierung des ZBP Adapter, fake-dvdv, 115, PMS und backstage wurde evaluiert und wenn nötig & möglich durchgeführt
  8. Traces, Metrics und Logs sind entsprechend verknüpft um maximalen Mehrwert zu schaffen
  9. Definition of Done wurde überprüft.

Mögliche Folgeaktivitäten

  • SDK für Tracing-Informationen fit machen, um im Fehlerfall Kunden und Support bei schneller Problemlösung zu unterstützen

Offene Fragen

Edited by Hendrik Kamp