Correlation-IDs fuer verteiltes Tracing in Shell-Pipelines

1. Was eine Correlation-ID ist und warum Shell-Pipelines sie brauchen

Eine Correlation-ID ist ein eindeutiger Bezeichner, meist eine UUID, der einen einzelnen logischen Vorgang von Anfang bis Ende begleitet, unabhaengig davon, wie viele einzelne Prozesse, Skripte oder Programme an diesem Vorgang beteiligt sind. Anders als eine Prozess-ID, die mit jedem neuen Skriptaufruf wechselt, bleibt die Correlation-ID ueber die gesamte Kette hinweg konstant und wird explizit weitergereicht, statt sich implizit aus der Systemumgebung zu ergeben.

In einer typischen Bash-Deployment-Pipeline, die etwa Migrationen ausfuehrt, Assets baut und einen Health-Check durchfuehrt, laeuft jeder dieser Schritte als eigener Prozessaufruf mit eigener Prozess-ID und eigenem Log-Fenster. Ohne eine gemeinsame Correlation-ID muss ein Entwickler bei der Fehlersuche zeitlich anhand von Zeitstempeln muehsam rekonstruieren, welche Log-Zeilen zu welchem Deployment-Lauf gehoeren, was bei mehreren parallel laufenden Deployments praktisch unmoeglich wird.

2. Die Correlation-ID am Pipeline-Anfang einmal erzeugen

Die Correlation-ID muss an genau einer Stelle entstehen, dem Einstiegspunkt der Pipeline, und darf danach niemals von einem der nachgelagerten Skripte neu generiert werden. Das Skript, das die Pipeline startet, prueft dafuer zunaechst, ob eine Correlation-ID bereits von aussen uebergeben wurde, etwa weil es selbst von einem uebergeordneten Prozess wie einem CI-Job aufgerufen wird, und generiert nur dann eine neue, wenn keine vorhanden ist.

Fuer die Generierung selbst reicht uuidgen auf den meisten Linux-Distributionen, alternativ laesst sich mit $(date +%s%N)-$$ auch ohne dieses Zusatzpaket eine ausreichend eindeutige Kennung erzeugen, wenn uuidgen nicht verfuegbar ist. Wichtig ist nur, dass die Erzeugung idempotent gegenueber einer bereits vorhandenen ID ist, damit verschachtelte Aufrufe der Pipeline nicht versehentlich mehrere unabhaengige IDs fuer denselben logischen Vorgang erzeugen.

#!/usr/bin/env bash
set -euo pipefail

# Reuse an inherited correlation ID, or generate a new one if this is the entry point
export CORRELATION_ID="${CORRELATION_ID:-$(uuidgen 2>/dev/null || echo "$(date +%s%N)-$$")}"

echo "Starting deployment pipeline, correlation_id=${CORRELATION_ID}"

3. Weitergabe per Umgebungsvariable an aufgerufene Skripte

Eine mit export gesetzte Umgebungsvariable vererbt sich automatisch an jeden Kindprozess, den ein Bash-Skript startet, egal ob es sich um ein weiteres Bash-Skript, ein Python-Programm oder ein beliebiges anderes Kommando handelt. Genau dieses Verhalten macht die Umgebungsvariable zum idealen Traeger fuer eine Correlation-ID: Solange jedes Skript in der Kette die Variable am Anfang uebernimmt, statt sie zu ueberschreiben, bleibt sie ohne zusaetzlichen Verdrahtungsaufwand ueber beliebig viele Ebenen erhalten.

Ein haeufiger Fehler ist, die Correlation-ID nur als lokale Shell-Variable zu setzen statt sie zu exportieren. Ohne export ist die Variable zwar im aktuellen Skript sichtbar, aber fuer jeden Kindprozess unsichtbar, sodass die Kette genau an der Stelle abreisst, an der ein neues Skript oder Programm gestartet wird, ohne dass dieser Fehler beim Testen im interaktiven Terminal sofort auffaellt.

#!/usr/bin/env bash
set -euo pipefail
# entrypoint.sh

export CORRELATION_ID="${CORRELATION_ID:-$(uuidgen)}"

./bin/run-migrations.sh    # inherits CORRELATION_ID
./bin/build-assets.sh      # inherits CORRELATION_ID
./bin/health-check.sh      # inherits CORRELATION_ID

echo "Pipeline finished, correlation_id=${CORRELATION_ID}"

4. Prozessgrenzen ueberwinden: SSH, Cron und Hintergrundprozesse

Die einfache Vererbung ueber export funktioniert nur innerhalb eines zusammenhaengenden Prozessbaums. Sobald die Pipeline ueber ssh einen Befehl auf einem anderen Host ausfuehrt, muss die Correlation-ID explizit als Argument oder Umgebungsvariable an den Remote-Befehl uebergeben werden, weil SSH standardmaessig keine lokalen Umgebungsvariablen an die Remote-Session weiterreicht, sofern der SSH-Server nicht ausdruecklich dafuer konfiguriert wurde.

Bei einem per cron gestarteten Skript existiert erst gar keine uebergeordnete Shell-Sitzung, deren Umgebungsvariablen vererbt werden koennten, sodass ein solches Skript grundsaetzlich immer eine neue Correlation-ID am Einstiegspunkt generieren muss. Bei Hintergrundprozessen, die mit & gestartet werden, funktioniert die Vererbung dagegen normal, solange die Variable vor dem & bereits exportiert wurde, was in der Praxis leicht uebersehen wird, wenn die Reihenfolge im Skript vertauscht ist.

#!/usr/bin/env bash
set -euo pipefail

export CORRELATION_ID="${CORRELATION_ID:-$(uuidgen)}"

# SSH does not forward local env vars by default -- pass explicitly
ssh deploy@remote-host "CORRELATION_ID='${CORRELATION_ID}' /opt/scripts/restart-service.sh"

# Background job started AFTER export still inherits the variable correctly
long_running_cleanup_task &

5. Integration mit strukturiertem Logging

Eine Correlation-ID entfaltet ihren vollen Nutzen erst in Kombination mit strukturiertem Logging, weil sich strukturierte Felder in einem Log-Aggregator direkt filtern lassen. Jede Log-Funktion einer Pipeline sollte deshalb automatisch das Feld correlation_id aus der gleichnamigen Umgebungsvariable in jede geloggte Zeile einfuegen, ohne dass der Aufrufer diesen Wert bei jedem Log-Aufruf manuell mitgeben muss.

In der Praxis reicht dafuer eine kleine jq-basierte Log-Funktion, die die Umgebungsvariable direkt liest, weil Umgebungsvariablen innerhalb eines Bash-Prozesses ohnehin global sichtbar sind. Ein Log-Aggregator wie ELK oder Loki kann anschliessend mit einer einzigen Abfrage nach correlation_id="..." alle Zeilen quer durch alle beteiligten Skripte und Hosts eines einzelnen Deployment-Laufs anzeigen, in korrekter zeitlicher Reihenfolge.

#!/usr/bin/env bash
set -euo pipefail

log_json() {
  local level="$1" message="$2"
  jq -nc \
    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    --arg level "$level" \
    --arg msg "$message" \
    --arg correlation_id "${CORRELATION_ID:-unknown}" \
    '{timestamp: $ts, level: $level, message: $msg, correlation_id: $correlation_id}' >&2
}

log_json "info" "Running database migrations"

6. Correlation-IDs an HTTP-Aufrufe weiterreichen

Ruft ein Bash-Skript im Rahmen der Pipeline eine HTTP-API auf, etwa um einen Deployment-Status an ein externes System zu melden, sollte die Correlation-ID als benutzerdefinierter Header wie X-Correlation-ID mitgesendet werden. Das erlaubt es, den Trace ueber die Grenze zwischen Shell-Skript und Webanwendung hinweg fortzusetzen, sofern die empfangende Anwendung diesen Header ebenfalls in ihr eigenes strukturiertes Logging uebernimmt.

Diese Praxis folgt demselben Prinzip, das in verteilten Webanwendungen laengst etabliert ist, wo Correlation-IDs oder Trace-IDs von Reverse Proxies wie nginx gesetzt und durch alle nachgelagerten Microservices durchgereicht werden. Ein Bash-Skript, das per curl mit einem solchen Header kommuniziert, reiht sich damit nahtlos in eine bestehende Observability-Kette ein, statt eine isolierte Insel ohne Anbindung an das uebrige System zu bleiben.

#!/usr/bin/env bash
set -euo pipefail

curl -sS -X POST "https://status.internal/api/deployments" \
  -H "X-Correlation-ID: ${CORRELATION_ID}" \
  -H "Content-Type: application/json" \
  -d "{\"status\": \"in_progress\"}"

7. Correlation-ID versus Trace-ID und Span-ID aus OpenTelemetry

Moderne Tracing-Standards wie OpenTelemetry unterscheiden zwischen einer Trace-ID, die einen gesamten verteilten Vorgang identifiziert, und einer Span-ID, die einen einzelnen Teilschritt innerhalb dieses Vorgangs markiert, zusammen mit einer Parent-Span-ID fuer die hierarchische Struktur. Eine einfache Correlation-ID in einem Bash-Skript deckt in der Praxis meist nur die Rolle der Trace-ID ab, ohne die feingranulare Span-Hierarchie eines vollstaendigen Tracing-Systems nachzubilden.

Fuer die meisten Bash-Automatisierungsaufgaben reicht diese vereinfachte Variante voellig aus, weil das Ziel meist nicht eine detaillierte Latenzanalyse einzelner Teilschritte ist, sondern schlicht die Moeglichkeit, alle zusammengehoerigen Log-Zeilen eines Vorgangs zu finden. Wer echtes verteiltes Tracing mit Span-Hierarchie und Latenzmessung braucht, sollte pruefen, ob ein OpenTelemetry-kompatibles Shell-Instrumentierungswerkzeug die bessere Wahl ist, statt eine eigene, vereinfachte Loesung von Grund auf nachzubauen.

8. Fallstricke: verschachtelte IDs, ueberschriebene Variablen und Sub-Shells

Der haeufigste Fehler ist, dass ein aufgerufenes Skript versehentlich eine eigene, neue Correlation-ID generiert, statt die geerbte zu pruefen und wiederzuverwenden, meist weil das Skript auch eigenstaendig ausserhalb der Pipeline lauffaehig sein soll. Die Loesung ist konsequent das Muster CORRELATION_ID="${CORRELATION_ID:-$(uuidgen)}", das eine bereits vorhandene ID immer bevorzugt und nur im Alleinlauf eine neue erzeugt.

Ein zweiter Fallstrick betrifft Sub-Shells, die durch Klammern ( ... ) oder Pipes entstehen: Variablen, die innerhalb einer Sub-Shell veraendert werden, wirken sich nicht auf die Elternumgebung aus, was bei einer versehentlichen Neuzuweisung der Correlation-ID innerhalb einer solchen Sub-Shell zu verwirrenden, scheinbar zufaelligen Log-Ausfaellen fuehrt, die schwer zu reproduzieren sind, weil sie vom genauen Aufbau der Pipe-Kette abhaengen.

9. Correlation-IDs im Vergleich zu anderen Tracing-Ansaetzen

Die Wahl des richtigen Tracing-Ansatzes fuer Shell-Automatisierung haengt von der Komplexitaet der beteiligten Systeme ab: Fuer eine einzelne Deployment-Pipeline aus Bash-Skripten reicht eine simple Correlation-ID meist voellig aus, waehrend ein System mit vielen Microservices und komplexer Anfragen-Fan-out-Struktur von einem vollstaendigen OpenTelemetry-Setup mit Span-Hierarchie deutlich mehr profitiert.

10. Zusammenfassung

11. FAQ: Correlation-IDs fuer verteiltes Tracing: Das Wichtigste auf einen Blick