Zum Inhalt

Fehleranalyse & Request ID (Correlation Tracing)

In der Microservice-Architektur der Open Data Infrastruktur (ODI) durchläuft ein einzelner Benutzeraufruf oft mehrere unabhängige Dienste (z. B. Ingress ➔ odi-staging-backend ➔ odi-metadata-service ➔ odi-ckan-service).

Um Fehler dienstübergreifend nachvollziehen zu können, verwendet die ODI ein durchgängiges Correlation Tracing mittels Request ID.

Funktionsweise der Request ID

sequenceDiagram
    autonumber
    actor User as Client / User
    participant Ingress as Ingress Controller
    participant Staging as odi-staging-backend
    participant Meta as odi-metadata-service
    participant CKAN as odi-ckan-service

    User->>Ingress: POST /api/dataset (ohne ID)
    Note over Ingress: Generiert x-request-id:<br/>b92f180a-912c-4c6e-821f...
    Ingress->>Staging: HTTP POST (mit x-request-id)
    Staging->>Meta: HTTP POST (reicht x-request-id weiter)
    Meta->>CKAN: HTTP POST (reicht x-request-id weiter)
    Note over CKAN: Fehler tritt auf!
    CKAN-->>Meta: HTTP 500 Response (mit x-request-id)
    Meta-->>Staging: HTTP 500 Response (mit x-request-id)
    Staging-->>User: HTTP 500 Response (mit x-request-id Header)
  1. Erzeugung / Injektion: Kommt eine Anfrage am Ingress oder Microservice an, wird geprüft, ob der HTTP-Header x-request-id existiert. Wenn nicht, generiert das System eine eindeutige UUID (z. B. b92f180a-912c-4c6e-821f-0e1234567890).
  2. Weiterleitung (Propagation): Jeder Microservice reicht den Header x-request-id bei internen HTTP-Aufrufen an nachfolgende Dienste weiter.
  3. Response Header: Die x-request-id wird im HTTP-Antwort-Header an den Aufrufer (z. B. Frontend oder API-Client) zurückgegeben.
  4. Log-Koppelung: Jeder Microservice bindet die requestId automatisch über den Pino-Logger (CorrelationIdStorage / mixin) in alle ausgehenden Log-Zeilen ein.

Fehleranalyse Schritt für Schritt

Direktlinks zur Request ID Suche im Grafana Dashboard

Wenn ein Benutzer oder ein API-Client einen Fehler meldet oder ein System-Alert auslöst, gehe wie folgt vor:

Schritt 1: Request ID ermitteln

  • Aus dem Client-Response: Im HTTP-Response-Header x-request-id ablesen.
  • Aus dem Frontend: In den Entwickler-Werkzeugen der Browser-Konsole (Netzwerk-Tab) unter den Antwort-Headern nachsehen.
  • Aus den Grafana Logs: Über die Zeit und den betroffenen Endpunkt im Fehleranalyse Dashboard suchen.

Schritt 2: Filterung im Fehleranalyse Dashboard

  1. Öffne das Fehleranalyse & Request ID Suche Dashboard in Grafana:
  2. Trage die Request ID in das obere Filterfeld requestId ein.
  3. Das Dashboard filtert augenblicklich alle Diagramme und den Log-Stream auf diesen exakten Aufruf.

Gefiltertes Grafana Dashboard zur Fehleranalyse

Schritt 3: Dienstübergreifenden Verlauf analysieren

Im gefilterten Log-Stream siehst du chronologisch alle Log-Meldungen, die während der Verarbeitung dieser einen Anfrage entstanden sind – serviceübergreifend:

[13:05:00.100] [staging-backend]   INFO  POST /api/dataset | requestId: b92f180a...
[13:05:00.150] [metadata-service]  INFO  Processing dataset metadata | requestId: b92f180a...
[13:05:00.220] [ckan-service]      ERROR [ServerError] Connection failed to Ckan | at CkanClient.post (ckan.client.js:42:11)

Ergebnis: Du erkennst sofort, welcher nachgelagerte Service (odi-ckan-service) den Fehler verursacht hat und wo im Code der Fehler auftrat.

Nützliche LogQL-Abfragen in Grafana / Loki

Falls du direkt im Grafana Explore-Bereich suchst, kannst du folgende LogQL-Abfragen nutzen:

  • Alle Logs zu einer spezifischen Request ID über alle Services: 

    {app=~".*"} | json | requestId="b92f180a-912c-4c6e-821f-0e1234567890"

  • Nur Fehler zu einer spezifischen Request ID: 

    {app=~".*"} | json | requestId="b92f180a-912c-4c6e-821f-0e1234567890" | level="error"