Bei einem Schnittstellen-Problem kann die Ursache auf beiden Seiten, im Netzwerk oder in einer Race Condition liegen.
Bei einem Bug in der eigenen Anwendung laesst sich der Code direkt debuggen. Bei einem Schnittstellen-Problem ist die Ursache unklarer, ohne gutes Tooling wird das schnell zum Raten mit verbundenen Augen.
Trace IDs als erste Massnahme
Jede Schnittstellen-Anfrage bekommt eine eindeutige ID, die durch alle Logs, alle Services und alle beteiligten Systeme weitergegeben wird. Schlaegt etwas fehl, lassen sich alle zugehoerigen Log-Eintraege auf einen Blick finden, ueber Header wie eine eigene Request-ID oder den etablierten W3C-Standard fuer Traceparent.
Request- und Response-Logging
Alle Requests und Responses zu loggen, aber intelligent: im Debug-Modus alles, im Produktivbetrieb nur bei Fehlern, dann aber inklusive Request und Response. Sensible Daten wie Tokens oder Passwoerter gehoeren dabei niemals ins Log.
Replay-Mechanismus
Ist ein Webhook oder eine Queue-Nachricht fehlgeschlagen und die Ursache behoben, sollte sie sich erneut verarbeiten lassen. Kafka ermoeglicht das ueber das Zuruecksetzen des Offsets von Haus aus, fuer eigene Webhooks braucht es dafuer einen eigenen Replay-Mechanismus.
Checkliste: Trace IDs durch alle beteiligten Systeme propagiert, Request- und Response-Logging fuer Fehlerszenarien, zentrale Log-Aggregation fuer alle Systeme, Replay-Mechanismus fuer Queue-Nachrichten, Runbook fuer haeufige Fehlerszenarien dokumentiert.
Ein Beispiel aus der Praxis
Eine Integration schlug sporadisch fehl, ohne dass sich das Muster reproduzieren liess. Ohne durchgaengige Trace-IDs war unklar, ob das Problem beim Sender, beim Empfaenger oder im Netzwerk dazwischen lag. Erst nach der Einfuehrung einer eindeutigen Request-ID, die durch alle beteiligten Systeme und deren Logs propagiert wurde, liess sich der Fehler innerhalb weniger Stunden auf einen einzelnen, unter Last gelegentlich ueberlasteten Zwischenservice zuruckfuehren, ein Fund, der ohne durchgaengiges Tracing praktisch unmoeglich gewesen waere.
Schnittstellen-Troubleshooting noetig? markom.digital debuggt Integrationsprobleme und richtet Observability fuer Schnittstellen ein.
