Vom Fehlerbericht bis zur verifizierten Behebung in einem einzigen Workflow

Die meisten Anleitungen zum Debuggen behandeln nur eine einzelne Funktion isoliert. Diese Anleitung deckt den gesamten Prozess ab.

Der Fehler: Ein Rabattcode wurde für Kunden mit Jahresabrechnung nicht mehr angewendet. Er bestand alle vorhandenen Tests, funktionierte bei Monatsabonnements und schlug nur bei einer Untergruppe echter Jahreskunden fehl. Außerhalb der Produktivumgebung hatte niemand den Fehler reproduzieren können.

So ging es vom Ticket bis zur verifizierten Korrektur.

Die Umgebung klonen

Das Wichtigste: Beginne mit einer isolierten Kopie der Produktivumgebung, die über dieselben Dienste, dieselbe Konfiguration und eine Kopie der Produktionsdaten verfügt.

Der erste Schritt ist ein Branch:

upsun branch debug-branch main --resources-init=parent

Dadurch wird aus dem main eine Vorschauumgebung namens „debug-branch“ erstellt. Standardmäßig werden die Daten des übergeordneten Zweigs geklont, sodass auch die Jahresabrechnungskonten, bei denen der Rabatt fehlschlug, vorhanden sind. Das Flag „--resources-init=parent“ weist der neuen Umgebung dieselbe CPU-Leistung und denselben Arbeitsspeicher wie in der Produktivumgebung zu. Lässt du es weg, startet die Entwicklungsumgebung mit minimalen Ressourcen – das ist zwar kostengünstiger, entspricht aber bei leistungssensiblen Fehlern nicht der Produktivumgebung.

Als Nächstes öffnest du Tunnel zu den Diensten der Umgebung und exportierst deren Verbindungsdaten:

upsun tunnel:open
export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"

„tunnel:open“ erstellt SSH-Tunnel zu allen Diensten der App, einschließlich der Datenbank. Durch den Export kann eine lokale Kopie der App oder ein beliebiges lokales Tool eine Verbindung zu ihnen herstellen, als würden sie auf deinem Rechner laufen.

Den Fehler reproduzieren

Das Wichtigste: Löse den Fehler mit denselben Daten und Diensten aus, die ihn in der Produktivumgebung verursacht haben.

Wenn der Tunnel offen ist, frage einen der fehlerhaften Jahreskonten ab, um dessen Abrechnungsstatus zu überprüfen. Öffne dann die URL der Vorschau-Umgebung, wende denselben Rabattcode auf dieses Konto an und beobachte, wie es stillschweigend fehlschlägt – genau so, wie es die Kunden erlebt haben.

Das Reproduzieren ist bei einem solchen Fehler meist der zeitaufwändigste Teil, da jemand Testdaten erstellen muss, die sich wie das fehlerhafte Konto verhalten. Hier befindet sich das fehlerhafte Konto bereits in der Umgebung.

Isolieren und beheben

Das Wichtigste: Schreibe den Fix und teste ihn unter den Bedingungen, die den Fehler verursacht haben.

Sobald sich der Fehler zuverlässig reproduzieren lässt, ist der Rest normales Debugging: Lies die Protokolle, gehe die Rabattlogik Schritt für Schritt durch und überprüfe, was sich geändert hat. Du kannst über SSH einen Remote-Debugger an die laufende Umgebung anschließen – mit „upsun xdebug“ für PHP oder einer SSH-Portweiterleitung für Node.js – und das Programm anhand genau der Konten durchgehen, bei denen der Fehler auftritt.

Die Ursache: Die Rabattlogik überprüfte ein Feld für den monatlichen Abrechnungszyklus, das bei Jahreskonten nicht auf dieselbe Weise ausgefüllt wird.

Die erste Korrektur hat diesen Fall behoben. Nachdem ich sie auf den „debug-branch“ gepusht und an einigen weiteren Jahreskonten in derselben Umgebung getestet hatte, tauchte ein zweiter Randfall auf: Mehrjahrespläne, bei denen der Abrechnungszyklus in einem ganz anderen Feld gespeichert wird. Die zweite Korrektur landete im selben Branch und wurde an beiden Kontengruppen getestet.

Sind echte Kundendaten hier sicher zu verwenden?

Das Wichtigste zum Merken: Vorschau-Umgebungen können die Daten behalten, auf die ein Fehler angewiesen ist, und die Daten bereinigen, die nicht benötigt werden.

Das Debuggen anhand isolierter Kopien echter Konten wirft eine berechtigte Frage auf. Mit Upsun kannst du deinem Deploy-Hook ein Bereinigungsskript hinzufügen, das personenbezogene Daten in Preview-Umgebungen anonymisiert. Du schreibst das Skript für dein Schema – zum Beispiel, um Namen, E-Mail-Adressen und Zahlungsdetails zu ersetzen – und stellst es so ein, dass es nur in Nicht-Produktionsumgebungen ausgeführt wird. Sobald es in der Produktivumgebung übernommen wurde, wird jede neue Preview-Umgebung bei ihrer Erstellung und beim ersten Deploy bereinigt.

Bei diesem Fehler lässt das Skript den Abrechnungsstatus unberührt, da der Fehler davon abhängt. Kundennamen, E-Mail-Adressen und Zahlungsdaten werden anonymisiert.

Richte das ein, bevor du es brauchst. Die Dokumentation zur Bereinigung von Datenbanken enthält funktionierende Beispiele für MariaDB mit Drupal, PostgreSQL mit Django und PostgreSQL mit Symfony.

Vor der Zusammenführung validieren

Das Wichtigste: Überprüfe in derselben Umgebung, in der du den Fehler diagnostiziert hast, damit das Ergebnis aussagekräftige Informationen über die Produktionsumgebung liefert.

Vor dem Zusammenführen wurde die Korrektur anhand des ursprünglichen Jahreskontos und des mehrjährigen Falls in derselben Umgebung validiert, in der der Fehler diagnostiziert wurde.

Diese Umgebung läuft mit denselben Diensten und derselben Konfiguration wie die Produktivumgebung, mit Produktionsdaten abzüglich der bereinigten Felder und (mit „--resources-init=parent“) denselben Ressourcen. Eine Korrektur, die dort erfolgreich ist, wurde unter den Bedingungen getestet, die den Fehler verursacht haben – und nicht anhand einer Nachbildung dieser Bedingungen. Und nun:

upsun merge debug-branch

Bist du bereit, das bei deinem eigenen Fehler auszuprobieren? Starte eine 15-tägige kostenlose Testversion und klone deine erste Umgebung.

Häufig gestellte Fragen (FAQ)

Benötigt man dafür bei jedem Schritt andere Tools? 
Du nutzt weiterhin deine gewohnten Tools: die CLI, deine IDE, deinen Debugger. Was gleich bleibt, ist die Umgebung. Das Erstellen von Branches, das Tunneling, das Debuggen und das Validieren laufen alle in einer einzigen geklonten Umgebung ab, sodass du zwischen den Schritten keine Testdaten neu erstellen oder Dienste neu einrichten musst.

Sind die zur Reproduktion verwendeten Daten repräsentativ für die Produktion? 
Ja, soweit es die Ursachen des Fehlers betrifft. Die Umgebung wird aus der Produktivumgebung geklont und verfügt daher über dieselben Dienste, dieselbe Konfiguration und dieselben Daten. Wenn du ein Bereinigungsskript verwendest, werden personenbezogene Daten anonymisiert, während die übrigen Daten so bleiben, wie sie in der Produktivumgebung vorliegen. Erstelle einen Branch mit `--resources-init=parent`, wenn du auch passende Ressourcen benötigst.

Was passiert mit der Debugging-Umgebung, sobald der Fix veröffentlicht ist? 
Füge den Zweig zusammen und lösche ihn anschließend mit „upsun environment:delete debug-branch“. Du kannst ihn auch weiterlaufen lassen, falls du noch Untersuchungen durchführen musst. Er nutzt Ressourcen, bis du ihn löschst oder deaktivierst.