Log‑Korrelation über Service‑Grenzen hinweg: Trace‑IDs und Baggage in verteilten Systemen richtig nutzen

Log‑Korrelation über Service‑Grenzen hinweg: Trace‑IDs und Baggage in verteilten Systemen richtig nutzen

Einleitung In modernen Microservice‑Architekturen ist die lückenlose Verfolgung von Anfragen über mehrere Services hinweg entscheidend für schnelle Fehlereingrenzungen und die Einhaltung von SLAs. Ohne eine konsistente Log‑Korrelation verlieren SRE‑ und Produktteams die Übersicht, was zu erhöhtem MTTR (Mean Time to Recovery) führt. Dieser Leitfaden führt Sie Schritt für Schritt durch ein typisches Projekt – von der Planung bis zum produktiven Roll‑out – und zeigt, wie Trace‑IDs und Baggage korrekt eingesetzt werden.

1. Projektplanung und Anforderungsdefinition

1.1 Zielsetzung

• Durchgängige Trace‑ID‑Propagation über alle Service‑Grenzen hinweg
• Einheitliche Baggage‑Nutzung für Kontextinformationen (z. B. Benutzer‑ID, Request‑Timestamp)
• Minimaler Performance‑Overhead (< 2 % zusätzliche Latenz)

1.2 Stakeholder & Rollen

• Backend‑Entwickler: Implementierung der Middleware
• SRE‑Team: Definition von SLA‑Metriken und Alert‑Logik
• Product Owner: Priorisierung von Compliance‑ und Datenschutz‑Aspekten (DSGVO‑Konformität)

1.3 Technologiestack

2. Architektur‑Design und Entscheidungspunkte

2.1 Auswahl des Propagation‑Formats

OpenTelemetry definiert das W3C Trace‑Context‑Format (Header traceparent und tracestate). Für Baggage‑Daten wird das baggage‑Header‑Format verwendet. Diese Standards garantieren Interoperabilität zwischen Java, Node und Python.

2.2 Middleware‑Implementierung

• Spring Boot: spring-cloud-sleuth konfiguriert automatisch traceparent und baggage.
• Node.js: @opentelemetry/api + @opentelemetry/auto-instrumentation-node erzeugt und propagiert Header.
• FastAPI: opentelemetry-instrumentation-fastapi übernimmt die gleiche Aufgabe.

Tipp: Aktivieren Sie das BaggagePropagation‑Feature nur für notwendige Schlüssel, um Header‑Größe zu begrenzen.

2.3 Entscheidung: Baggage‑Schlüssel wählen

3. Implementierung – Meilenstein 1: Basis‑Tracing

3.1 Service‑A (Spring Boot) – Code‑Snippet

@Bean
public Tracer tracer(OpenTelemetry openTelemetry) {
    return openTelemetry.getTracer("lescopr-demo");
}

@Bean
public BaggagePropagationCustomizer baggageCustomizer() {
    return builder -> builder.addKey("user-id");
}

Dieses Snippet erzeugt einen Tracer und konfiguriert Baggage‑Propagation nur für user-id.

3.2 Service‑B (Node.js) – Code‑Snippet

const { trace, propagation } = require('@opentelemetry/api');
app.use((req, res, next) => {
  const ctx = propagation.extract(context.active(), req.headers);
  const span = trace.getTracer('lescopr-demo').startSpan('incoming-request', undefined, ctx);
  // Add baggage
  const baggage = propagation.createBaggage({
    'request-id': req.headers['x-request-id'] || uuidv4()
  });
  propagation.inject(trace.setSpan(context.active(), span), res.headers);
  next();
});

Hier wird die eingehende Trace‑ID extrahiert und ein neuer Baggage‑Eintrag hinzugefügt.

3.3 Service‑C (FastAPI) – Code‑Snippet

from opentelemetry import trace, baggage
from fastapi import FastAPI, Request
app = FastAPI()

@app.middleware("http")
async def add_tracing(request: Request, call_next):
    ctx = trace.propagation.extract(dict(request.headers))
    span = trace.get_tracer("lescopr-demo").start_span("incoming-request", context=ctx)
    # Propagate baggage
    baggage.set_baggage("locale", request.headers.get("accept-language", "de-DE"))
    response = await call_next(request)
    return response

Der Middleware‑Layer sorgt dafür, dass sowohl Trace‑ID als auch Baggage in den nachfolgenden Aufrufen erhalten bleiben.

4. Implementierung – Meilenstein 2: Log‑Korrelation

4.1 Log‑Framework‑Integration

Alle Services nutzen structured logging (JSON‑Format). Die Trace‑ID und relevante Baggage‑Werte werden als Felder trace_id, user_id und request_id eingebettet.

• Spring Boot: Logback‑Konfiguration mit %X{traceId} und %X{user-id}.
• Node.js: Winston‑Transport mit format.combine(format.json(), format.metadata()).
• FastAPI: structlog‑Setup, das trace_id aus dem aktuellen Span ausliest.

4.2 Zentrale Log‑Aggregation

Lescopr sammelt die strukturierten Logs über OpenTelemetry Collector und speichert sie in einem Elasticsearch‑Cluster. Durch die einheitlichen Felder können Sie in Kibana oder Lescopr‑Dashboard Queries wie folgt ausführen:

SELECT * FROM logs WHERE trace_id = '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' AND user_id = '12345'

Damit erhalten Sie sämtliche Log‑Einträge einer einzelnen Anfrage über alle Services hinweg.

5. Testing & Validierung

5.1 Unit‑Tests

• Spring Boot: @WebMvcTest prüft, ob traceparent im Response‑Header enthalten ist.
• Node.js: Jest‑Test verifiziert, dass baggage‑Header korrekt gesetzt wird.
• FastAPI: Pytest‑Suite prüft, ob trace_id im Log‑Output erscheint.

5.2 End‑to‑End‑Tests (E2E)

Ein Chaos‑Monkey‑Szenario simuliert Service‑Ausfälle. Beobachten Sie, ob die Logs weiterhin korrekt korreliert werden. Das erwartete Ergebnis: MTTR reduziert um mindestens 30 % gegenüber dem Basis‑Setup ohne Baggage‑Propagation.

6. Roll‑out und Monitoring

6.1 Staged Deployment

1. Canary‑Release (5 % Traffic) – Überwachen Sie trace_id‑Durchsatz und Latenz.
2. Blue‑Green‑Switch – Bei stabilen Metriken schalten Sie auf 100 % um.

6.2 KPI‑Dashboard in Lescopr

• Trace‑Completeness % (Ziel ≥ 98 %)
• Log‑Correlation Latency (Ziel ≤ 50 ms)
• Additional Header Overhead (Ziel ≤ 1 ms pro Request)

7. Wartung & Weiterentwicklung

7.1 Governance für Baggage‑Schlüssel

Ein zentrales Baggage‑Registry definiert, welche Schlüssel erlaubt sind. Änderungen erfordern ein Pull‑Request‑Review, um unbeabsichtigte Performance‑Einbrüche zu vermeiden.

7.2 Upgrade‑Pfad

OpenTelemetry veröffentlicht regelmäßig neue Versionen. Planen Sie ein Quarterly Review, um Kompatibilitäts‑ und Sicherheitsupdates zu integrieren.

Fazit

Durch konsequente Nutzung von Trace‑IDs und Baggage schaffen Sie eine robuste Log‑Korrelation, die Fehlerursachen schneller sichtbar macht und die Einhaltung von SLAs unterstützt. Der vorgestellte Projektablauf liefert ein wiederholbares Muster für jede Microservice‑Umgebung.

Für mehr Details: Die Lescopr-Dokumentation beschreibt die Einrichtung Schritt für Schritt.