Produktionsfehler nach Deployments systematisch eingrenzen

1. Warum Systematik über Intuition geht

Wenn ein Produktionsfehler nach einem Deployment auftritt, ist der natürliche Impuls, sofort nach einer Lösung zu suchen. Das Problem dabei: ohne Systematik werden häufig mehrere Änderungen gleichzeitig vorgenommen, was die Diagnose erschwert und in manchen Fällen neue Fehler erzeugt. Ein strukturierter Diagnoseansatz trennt Beobachtung von Hypothese und Hypothese von Aktion – in dieser Reihenfolge, nicht durchgemischt.

Für Magento-Deployments ist Systematik besonders wichtig, weil ein einziger Release typischerweise viele Änderungen enthält: PHP-Code, Composer-Pakete, DI-Compile, Static Content, Datenbankmigrationen und möglicherweise Konfigurationsänderungen. Der Fehler kann in jeder dieser Schichten liegen. Ohne einen strukturierten Ansatz ist die Suche ein Erraten – mit Systematik ist sie ein Eingrenzen.

Der Rahmen ist einfach: Zuerst beobachten (Logs, HTTP-Status, Monitoring), dann einordnen (welche Schicht ist betroffen?), dann gezielt testen (einzelne Hypothesen prüfen), dann entscheiden (rollbacken oder fixen). Dieser Ablauf gilt unabhängig davon, wie dringend der Fehler ist – die Dringlichkeit beeinflusst die Geschwindigkeit, nicht die Systematik.

2. Die ersten 60 Sekunden: Triage ohne Panik

In den ersten 60 Sekunden nach Meldung eines Produktionsfehlers geht es um Triage, nicht um Diagnose. Drei Fragen bestimmen den ersten Schritt: Ist die Anwendung komplett ausgefallen oder ist es ein Teilfehler? Ist das Fehlerverhalten reproduzierbar? Haben andere Nutzer dieselbe Erfahrung? Die Antworten auf diese Fragen bestimmen, ob sofort der Maintenance Mode eingeschaltet und ein Rollback eingeleitet werden sollte, oder ob eine ruhigere Diagnose möglich ist.

Ein kompletter Ausfall (500-Fehler auf allen Seiten, Health Endpoint antwortet nicht) erfordert einen sofortigen Rollback ohne weitere Diagnose. Ein partieller Fehler (bestimmte Seiten oder Funktionen) erlaubt eine gezieltere Analyse. Die Faustregel: wenn der Fehler mehr als 10% der Nutzer betrifft oder umsatzkritische Pfade (Checkout, Login) betrifft, ist Rollback die erste Antwort – Diagnose kommt danach im alten Zustand.

# GitLab pipeline as diagnostic tool — rerun verify stage manually
verify:manual-diagnostic:
  stage: verify
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: manual
  script:
    # Check current symlink target
    - ssh "${DEPLOY_USER}@${DEPLOY_HOST}"
        "readlink -f ${DEPLOY_PATH}/current"

    # Show last 50 lines of exception log
    - ssh "${DEPLOY_USER}@${DEPLOY_HOST}"
        "tail -50 ${DEPLOY_PATH}/current/var/log/exception.log 2>/dev/null || echo 'Log empty'"

    # Check PHP-FPM status
    - ssh "${DEPLOY_USER}@${DEPLOY_HOST}"
        "systemctl status php8.4-fpm --no-pager -l | tail -20"

    # HTTP status of main pages
    - for URL in / /checkout/cart /customer/account/login/; do
        STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://shop.example.com${URL}");
        echo "  $URL → HTTP $STATUS";
      done

3. Magento-Logs lesen und einordnen

Das Magento-Log-System hat mehrere Dateien mit unterschiedlichen Zwecken: var/log/exception.log enthält Stack Traces für unbehandelte Ausnahmen, var/log/system.log enthält allgemeine System-Ereignisse, und var/log/debug.log enthält detaillierte Debug-Ausgaben, wenn der Debug-Modus aktiviert ist. Die wichtigste Datei für Deployment-Fehler ist exception.log – hier landen PHP-Exceptions, die Magento nicht selbst behandeln konnte.

Beim Lesen des Exception-Logs nach einem Deployment ist der Zeitstempel der wichtigste Filter: Einträge, die exakt zum Zeitpunkt des Symlink-Wechsels oder kurz danach erscheinen, sind direkt mit dem Deployment assoziiert. Ältere Einträge sind möglicherweise nicht relevant. Ein schneller Grep nach dem Release-Zeitstempel: grep "2026-05-09 14:30" exception.log – der Zeitpunkt des Deployments ist in der GitLab-Pipeline-Ausgabe protokolliert.

4. GitLab-Pipeline als Diagnosewerkzeug

Die GitLab-Pipeline enthält mehr Diagnoseinformationen, als auf den ersten Blick sichtbar ist. Der Job-Output des Deploy-Jobs zeigt den exakten Zeitpunkt des Symlink-Wechsels, eventuelle Fehlermeldungen aus den Magento-CLI-Kommandos und den Output von setup:upgrade. Wenn setup:upgrade mit einer Warnung oder einem Nicht-Standard-Exitcode endete, aber trotzdem als erfolgreich gewertet wurde, ist das der erste Hinweis.

Zusätzlich zeigt die GitLab-Pipeline-Ansicht, welche Jobs in welcher Reihenfolge liefen, welche Artefakte erzeugt wurden und ob ein Caching-Treffer vorlag. Ein Build-Job, der Composer-Pakete aus dem Cache geladen hat, könnte eine veraltete Abhängigkeit mitgebracht haben. Der Pipeline-Trace unter "Download artifacts" und "Job artifacts" ist oft der schnellste Weg, den genauen Build-Stand zu rekonstruieren.

5. Änderungen eingrenzen: git bisect und diff

Wenn der Fehler nach mehreren Commits auftritt und nicht sofort aus den Logs erklärt werden kann, ist git bisect das präziseste Werkzeug zur Eingrenzung. Es ermöglicht eine binäre Suche durch die Commit-Geschichte: Man markiert einen bekannten guten Stand und den aktuellen schlechten Stand, und Git wählt automatisch den nächsten Commit für den Test aus. Bei 20 Commits dauert die Eingrenzung maximal 5 Schritte.

Für Magento-Deployments ist eine Alternative zu git bisect das direkte Diff zwischen dem aktuellen Release und dem vorherigen: git diff PREVIOUS_TAG HEAD -- app/code/ app/design/. Dieses Diff zeigt alle PHP-, Template- und Layout-Änderungen, die im aktuellen Release enthalten sind. Kombiniert mit dem Stack Trace aus dem Exception-Log lässt sich häufig direkt die betroffene Datei identifizieren, ohne ein vollständiges Bisect durchführen zu müssen.

# Diagnostic job to compare current and previous release on server
diagnose:diff-releases:
  stage: verify
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: manual
  script:
    - |
      ssh "${DEPLOY_USER}@${DEPLOY_HOST}" bash -s << 'REMOTE'
        set -euo pipefail
        CURRENT=$(readlink -f ${DEPLOY_PATH}/current)
        RELEASES=$(ls -1t ${DEPLOY_PATH}/releases/)
        PREVIOUS=$(echo "$RELEASES" | sed -n '2p')

        echo "=== Current release: $(basename $CURRENT) ==="
        echo "=== Previous release: $PREVIOUS ==="

        # Show what changed in app/code between releases
        diff -rq --brief \
          "${DEPLOY_PATH}/releases/${PREVIOUS}/app/code/" \
          "${CURRENT}/app/code/" 2>/dev/null \
          || echo "Diff completed above"

        # Show exception log entries since current deploy time
        DEPLOY_TIME=$(stat -c %Y "$CURRENT")
        find ${CURRENT}/var/log/ -name "exception.log" -newer "$CURRENT" \
          -exec tail -30 {} \; 2>/dev/null || echo "No recent exceptions"
      REMOTE

6. Wann rollbacken, wann fixen?

Die Rollback-Entscheidung hängt von drei Faktoren ab: Schwere des Fehlers, Verfügbarkeit eines bekannten guten Zustands und Komplexität des Fixes. Ein vollständiger Shop-Ausfall erfordert immer einen sofortigen Rollback – die Diagnose kann danach im stabilen Zustand erfolgen. Ein partieller Fehler in einem nicht-kritischen Bereich (z.B. ein kaputtes Widget auf einer Informationsseite) kann direkt gefixt werden, wenn die Ursache klar ist und der Fix einfach ist.

Die gefährlichste Situation ist ein Fehler, dessen Ursache unklar ist und für den trotzdem direkt ein Fix versucht wird. Das führt häufig zu einer Kette von Änderungen, bei der am Ende unklar ist, was den ursprünglichen Fehler verursacht hat und was die Fixes eingebracht haben. In diesem Fall ist Rollback immer die bessere Wahl: stabiler Ausgangszustand, saubere Diagnose, kontrollierter Fix.

7. Umgebungsunterschiede als Fehlerquelle

Ein erheblicher Teil der Produktionsfehler nach Deployments liegt nicht im Code selbst, sondern in Unterschieden zwischen der Build-Umgebung und der Produktionsumgebung. PHP-Version, installierte PHP-Extensions, Dateirechte, Umgebungsvariablen, Datenbankversion und Redis-Konfiguration können zwischen Runner und Produktionsserver abweichen. Diese Abweichungen sind im Build-Stadium nicht sichtbar, manifestieren sich aber zur Laufzeit auf dem Server.

Die systematische Checkliste für Umgebungsunterschiede: PHP-Version auf Runner und Server vergleichen (php -v), installierte Extensions prüfen (php -m), Dateirechte des Release-Verzeichnisses validieren, env.php-Konfiguration auf korrekte Werte prüfen und den Output von bin/magento config:show mit dem erwarteten Konfigurationsstand vergleichen. Diese Checkliste sollte bei jedem unerklärten Produktionsfehler durchlaufen werden.

8. Nachbereitung: den Fehler dokumentieren

Die Nachbereitung eines Produktionsfehlers ist mindestens so wichtig wie die Behebung. Ein dokumentierter Fehler mit Ursache, Symptom, Diagnoseweg und Fix wird zum Wissensschatz des Teams – ein nicht dokumentierter Fehler wird mit hoher Wahrscheinlichkeit wieder auftreten. Die Dokumentation muss nicht umfangreich sein: Datum, Deployment-ID aus GitLab, Symptom, Ursache, Fix und Präventionsmaßnahme in vier bis fünf Sätzen reicht aus.

Wichtiger als die Form ist die Konsequenz: Jeder Produktionsfehler nach einem Deployment sollte zu mindestens einer Änderung im Prozess führen. Das kann ein neuer Post-Deploy Check sein, eine erweiterte Test-Stage, eine zusätzliche Validierung in der Build-Stage oder eine Änderung an der Umgebungskonfiguration. Ohne diese Konsequenz ist die Nachbereitung nur Protokoll ohne Lerneffekt.

9. Fehlerklassen und erste Anlaufstellen

Produktionsfehler nach Magento-Deployments fallen typischerweise in eine von wenigen Klassen. Die folgende Tabelle zeigt die häufigsten Klassen, ihre typischen Symptome und die erste Anlaufstelle für die Diagnose.

Die Tabelle zeigt, dass jede Fehlerklasse eine klar definierte erste Anlaufstelle hat. Das Ziel der Triage ist, die Fehlerklasse so schnell wie möglich zu bestimmen und dann die richtige Anlaufstelle zu prüfen – anstatt alle möglichen Logs gleichzeitig zu durchsuchen. Ein gezielter erster Check spart in einer Störungssituation oft mehrere Minuten, die den Unterschied zwischen einem kurzen und einem langen Ausfall machen.

10. Zusammenfassung

Produktionsfehler nach Deployments systematisch einzugrenzen ist eine Fähigkeit, die Teams durch Wiederholung aufbauen – nicht durch Intuition. Die drei Kernprinzipien: Beobachten vor Handeln, Hypothesen einzeln prüfen und Rollback im Zweifel der Diagnose vorziehen. GitLab bietet dabei mehr als nur eine CI/CD-Plattform: Pipeline-Output, Job-Traces und Artefakt-Metadaten sind wertvolle Diagnosedaten, die direkt nach dem Deployment verfügbar sind.

Die Investition in strukturierte Diagnose zahlt sich nicht nur im Störfall aus. Teams, die systematisch diagnostizieren, lernen aus jedem Fehler und bauen Prozesse auf, die Fehler der gleichen Klasse beim nächsten Deployment verhindern. Das ist der eigentliche Wert der Nachbereitung: kein Fehler sollte zweimal unvorbereitet auftreten.

11. FAQ: Produktionsfehler nach Deployments