Integrationsmonitoring: Fehlgeschlagene Synchronisierungen zuverlässig erkennen

Integrationsmonitoring: Erkennen Sie stille Synchronisierungsfehler frühzeitig mit Korrelations-ID, strukturierten Logs, Geschäftsmetriken, Alarmschwellen und Abgleichsbericht.
Technische Zusammenfassung
Technologie
Strukturiertes Logging, W3C Trace Context, OpenTelemetry, Prometheus, SQL
Thema
Stille Integrationsfehler mit Monitoring und Abgleich erkennen
Niveau
Mittel
Voraussetzungen
  • Ein laufender Integrationsfluss (API, Queue oder Batch-Übertragung)
  • Grundkenntnisse in SQL und Log-Management
In diesem Beitrag7 Abschnitte

Die teuerste Störung einer Integration ist nicht die laute, sondern die stille: Die Server laufen, die Endpunkte liefern 200, doch der Bestand wurde seit drei Tagen nicht aktualisiert, oder jeden Tag kommen einige Bestellungen nie im ERP an. Meist bemerken das Kunde oder Buchhaltung. Dann liegt keine technische Störung mehr vor, sondern eine Dateninkonsistenz, die korrigiert werden muss. Um das früh zu erkennen, braucht es eine eigene Überwachungsschicht – von der Korrelations-ID über Metriken auf Geschäftsebene und Alarmschwellen bis zum periodischen Abgleichsbericht.

Der Unterschied zwischen technischer Uptime und Gesundheit des Geschäftsflusses

Klassisches Uptime-Monitoring beantwortet die Frage „Antwortet der Dienst?“. Bei Integrationen lautet die eigentliche Frage: „Kommen die Daten in der erwarteten Zeit, vollständig und korrekt auf der Gegenseite an?“ Der Unterschied zeigt sich bei diesen stillen Störungen, die wir in der Praxis immer wieder sehen:

  • Ein geplanter Job läuft gar nicht, weil die Cron-Definition nach einer Neuinstallation oder einem Umzug des Servers verloren ging; einen Fehler erzeugt er auch nicht.
  • Der Queue-Consumer läuft, wiederholt aber wegen eines im ERP gesperrten Datensatzes jede Nachricht; die Queue wächst seit Stunden.
  • Der Webhook-Anbieter weiß nicht, dass das Signaturgeheimnis geändert wurde; alle Ereignisse werden mit 401 abgelehnt, und der Anbieter gibt nach einer Weile auf.
  • Der API-Aufruf ist erfolgreich, aber weil sich das Feld-Mapping geändert hat, werden Produktpreise als null geschrieben.
  • Die Batch-Datei kommt an, ist aber leer; der Vorgang endet mit „0 Datensätze verarbeitet, erfolgreich“.

Keines dieser Szenarien erkennt eine HTTP-Uptime-Prüfung. Im Dashboard ist alles grün. Monitoring wird deshalb auf drei Ebenen aufgebaut: Infrastruktur (Server, Message Broker, Datenbank), technischer Fluss (Fehlerrate, Latenz, Queue-Tiefe) und Geschäftsergebnis (Sind die erwarteten Daten auf der Gegenseite vorhanden?). Zu Metriken und Schwellen auf Infrastrukturseite lesen Sie den Beitrag Metriken und Schwellenwerte im Server-Monitoring; hier konzentrieren wir uns auf die beiden anderen Ebenen.

Korrelations-ID und strukturiertes Logging

Auf dem Weg von der Website ins ERP durchläuft eine Bestellung mehrere Komponenten: Webanwendung, Outbox-Publisher, Queue, Consumer, ERP-Connector. Im Störungsfall muss sich die Frage „Was ist mit Bestellung 10452 passiert?“ mit einer einzigen Suche beantworten lassen. Fünf Logdateien auf fünf Servern zu greppen, ist keine Analyse, sondern Raten. Zwei Praktiken ermöglichen das:

  1. Korrelations-ID: Eine am Beginn des Flusses erzeugte ID (oder der Geschäftsschlüssel) wird mit jeder Nachricht, jedem HTTP-Aufruf und jeder Logzeile mitgeführt. Bei HTTP-Aufrufen ist der Header traceparent aus der W3C-Spezifikation Trace Context ein Standardträger dafür; Werkzeuge wie OpenTelemetry können diesen Header automatisch weitergeben.
  2. Strukturiertes Log: Logzeilen werden statt als Freitext als JSON mit festen Feldern geschrieben. So werden im Log-Management-Werkzeug Filterung und Zählung nach Feldern möglich.
{
  "ts": "2026-11-10T09:14:22.481Z",
  "level": "error",
  "flow": "bestellung-erp",
  "step": "erp_post",
  "correlation_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "business_key": "WEB-10452",
  "attempt": 3,
  "http_status": 422,
  "error_code": "DEBITOR_NICHT_GEFUNDEN",
  "duration_ms": 812
}

In dieser Struktur sind die Felder flow und step die Grundlage für die Erzeugung von Metriken, das Feld business_key die Grundlage dafür, dass der Support Kundenfragen beantworten kann. Personenbezogene Daten (Name, Telefon, Adresse) und Zugangsdaten (Token, Passwort) werden nicht geloggt; der Geschäftsschlüssel genügt für die meisten Analysen. Wird die bei der Fehlersuche aktivierte Einstellung „vollständigen Body loggen“ in der Produktion vergessen, wird die Logdatei zum Speicher personenbezogener Daten. Vergessen Sie nicht, sie abzuschalten.

Zu überwachende Integrationsmetriken

Die folgenden Metriken machen für jeden Fluss einen Großteil der stillen Störungen sichtbar:

Metrik Was sie erkennt Quelle
Zeitpunkt der letzten erfolgreichen Synchronisierung Job, der gar nicht läuft oder hängt Am Ende des Jobs geschriebener Zeitstempel
Zahl verarbeiteter Datensätze (pro Fluss) Leere Datei, erfolgreicher Lauf mit null Datensätzen Job-Zusammenfassung
Queue-Tiefe Consumer kommt nicht hinterher Broker oder Queue-Tabelle
Alter der ältesten wartenden Nachricht Hängende Nachricht, langsamer Consumer Broker oder Queue-Tabelle
Fehlerzahl (nach Code und Art) Anstieg dauerhafter und vorübergehender Fehler Strukturiertes Log
Zahl der Dead-Letter-Einträge Nachrichten mit aufgebrauchten Wiederholungsversuchen DLQ
Ende-zu-Ende-Latenz Zeit zwischen Ereignis und Schreiben auf der Gegenseite Korrelierte Zeitstempel

Die Queue-Tiefe allein ist irreführend: Eine tiefe, aber schnell abfließende Queue am Kampagnentag ist gesund; eine flache Queue, in der eine einzige Nachricht seit Stunden hängt, nicht. Überwachen Sie Tiefe und Alter der ältesten Nachricht gemeinsam. Klassifizierung der Fehlerarten und Aufbau des Dead-Letters beschreibt der Leitfaden zu API-Fehlerbehandlung, Retry und Backoff.

Alarmschwellen und Umgang mit Alarmrauschen

Ein System, das bei jedem Fehler einen Alarm erzeugt, wird schnell zu einem System, auf das niemand mehr schaut. Der Operator schreibt eine E-Mail-Regel, Alarme fließen in einen Ordner, und die echte Störung geht mit ihnen unter. Beim Alarmdesign helfen diese Grundsätze:

  • Alarmieren Sie auf das Symptom, nicht auf die Ursache. Statt „ERP-API hat einmal 503 geliefert“ sollten Bedingungen mit geschäftlicher Auswirkung Alarme sein, etwa „letzte erfolgreiche Übertragung im Bestellfluss älter als 30 Minuten“. Einzelne Fehler bleiben in Logs und Dashboards.
  • Stellen Sie die Schwelle nach dem Geschäftskalender ein. Dass nachts keine Bestellung eingeht, kann normal sein; null Bestellungen über eine Stunde während der Geschäftszeit zeigen dagegen ein Problem auf der Website oder im Fluss. Verwenden Sie je nach Zeitfenster unterschiedliche Schwellen oder einen Vergleich mit dem erwarteten Volumen.
  • Definieren Sie eine Mindestdauer. Abzuwarten, ob die Bedingung einige Minuten anhält, filtert Alarme durch kurze Schwankungen heraus.
  • Überwachen Sie auch das Fehlen einer Metrik. Stirbt der Prozess, der die Metrik erzeugt, wird die Schwellenbedingung nie ausgelöst. „Metrik kommt nicht an“ sollte ein eigener Alarm sein.
  • Jeder Alarm braucht einen Eigentümer und eine kurze Eingriffsnotiz. Der Alarmtext sollte Flussnamen, mögliche Ursachen und den ersten Prüfschritt enthalten. Wer den Alarm um drei Uhr nachts öffnet, sollte nicht suchen müssen, wo er nachsehen soll.

In einer Umgebung mit Prometheus lässt sich die Regel „letzte erfolgreiche Synchronisierung“ wie folgt schreiben. Der Metrikname ist ein Beispiel; der Job muss am Ende jedes erfolgreichen Laufs den Zeitstempel veröffentlichen. Details zur Regelsyntax finden Sie in der Dokumentation Prometheus alerting rules.

groups:
  - name: integration
    rules:
      - alert: BestandsSyncVerzoegert
        expr: time() - integration_last_success_timestamp_seconds{flow="bestand"} > 1800
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Bestandssynchronisierung seit 30 Minuten nicht erfolgreich abgeschlossen"
      - alert: BestandsSyncMetrikFehlt
        expr: absent(integration_last_success_timestamp_seconds{flow="bestand"})
        for: 15m
        labels:
          severity: warning

In Umgebungen ohne Prometheus lässt sich dieselbe Logik mit einer geplanten SQL-Prüfung und einer Benachrichtigung per E-Mail/Teams umsetzen. Das Werkzeug ist zweitrangig. Die Bedingung muss das Geschäftsergebnis messen. Ebenso kann ein extern laufender „Heartbeat“-Dienst genutzt werden: Der Job sendet bei jedem erfolgreichen Lauf eine Anfrage an eine bestimmte Adresse, und bleibt die Anfrage in der erwarteten Zeit aus, erzeugt der Dienst einen Alarm. Das ist die günstigste Methode, eine verlorene Cron-Definition zu erkennen.

Prüfung der Datenkonsistenz mit Abgleichsbericht

Metriken zeigen, dass der Fluss läuft; dass die Daten korrekt sind, beweist nur ein Vergleich beider Seiten. Der Abgleich (Reconciliation) gleicht die Datensätze in Quell- und Zielsystem periodisch ab und meldet Abweichungen. Bei Webhook- und Queue-basierten Flüssen ist er auch der zuverlässigste Weg, verpasste Ereignisse zu erkennen; die Rolle dieser Muster beschreibt der Beitrag Integrationsmuster zwischen ERP und Web.

Beispiel einer Abgleichsabfrage für den Bestellfluss: Datensätze, die in den letzten 48 Stunden im Web angelegt und bezahlt wurden, aber keine vom ERP zurückgemeldete Bestellnummer haben. Die letzten 30 Minuten sind ausgenommen, um die normale Verarbeitungsverzögerung auszuklammern.

SELECT o.id, o.created_at, o.status
  FROM orders o
  LEFT JOIN erp_order_map m ON m.web_order_id = o.id
 WHERE o.created_at BETWEEN now() - interval '48 hours'
                        AND now() - interval '30 minutes'
   AND o.status NOT IN ('cancelled', 'pending_payment')
   AND m.erp_order_no IS NULL
 ORDER BY o.created_at;

Diese Abfrage vertraut der eigenen Zuordnungstabelle der Web-Seite. Eine stärkere Prüfung besteht darin, für denselben Zeitraum aus dem ERP die Liste der „Bestellungen mit Web-Referenz“ abzurufen und in beide Richtungen mit der Liste im Web zu vergleichen: Datensätze, die im Web, aber nicht im ERP stehen (verloren), und solche, die im ERP doppelt vorkommen (Duplikat), werden getrennt gemeldet. Bei Stammdaten wie Bestand und Preis werden Menge oder Preis pro Artikelnummer verglichen; bei vielen Artikeln werden zuerst Summen pro Kategorie verglichen und nur abweichende Gruppen auf Zeilenebene untersucht.

Legen Sie auch für Abweichungen einen Prozess fest: Welche Abweichung wird automatisch korrigiert (z. B. erneutes Einreihen einer fehlenden Bestellung), welche geht in die manuelle Prüfung, wer ist verantwortlich? Ein Abweichungsbericht ohne Eigentümer wird nicht gelesen.

Checkliste Integrationsmonitoring

  • Sind für jeden Fluss Name, Eigentümer, Quell- und Zielsystem, erwartete Laufhäufigkeit und längste akzeptable Verzögerung dokumentiert?
  • Stehen Korrelations-ID und Geschäftsschlüssel in den Logs aller Komponenten unter demselben Feldnamen?
  • Werden Logs strukturiert an zentraler Stelle gesammelt und enthalten keine personenbezogenen Daten?
  • Werden für jeden Fluss der Zeitpunkt des letzten erfolgreichen Laufs und die Zahl verarbeiteter Datensätze als Metrik veröffentlicht?
  • Werden Queue-Tiefe und Alter der ältesten Nachricht gemeinsam überwacht?
  • Ist das Fehlen einer Metrik als eigener Alarm definiert?
  • Haben Alarme einen Eigentümer, eine Eingriffsnotiz und Schwellen nach Geschäftszeiten?
  • Läuft für kritische Flüsse ein periodischer Abgleichsbericht, und werden auch Ergebnisse ohne Abweichung festgehalten?
  • Ist ein Korrekturprozess für Dead-Letter-Einträge und Abgleichsabweichungen definiert?

Verwenden Sie diese Liste als Abnahmekriterium bei der Inbetriebnahme einer neuen Integration; so ist Monitoring keine nachträglich ergänzte Aufgabe mehr. Zu den Kennzahlen auf Empfängerseite bei Webhook-basierten Flüssen lesen Sie auch den Leitfaden zum Design von Webhook-Empfängern. Zum Umfang von Monitoring und Alarmierung für Ihre Integrationsflüsse sehen Sie sich unsere Seiten Web-Monitoring und Uptime-Überwachung und ERP-, CRM- und API-Integrationen an.

Häufig gestellte Fragen

Warum erkennt Uptime-Monitoring keine Integrationsfehler?

Uptime-Monitoring misst nur, ob ein Dienst antwortet. Integrationsfehler entstehen dagegen meist, während die Dienste laufen: Ein Job läuft gar nicht, Nachrichten hängen in der Queue, oder Daten werden mit falschem Mapping geschrieben. Um das zu erkennen, braucht es Kontrollen auf Geschäftsebene wie den Zeitpunkt der letzten erfolgreichen Synchronisierung, die Zahl verarbeiteter Datensätze und den Abgleich.

Wie oft sollte ein Abgleichsbericht laufen?

Die Häufigkeit bestimmt die längste akzeptable Verzögerung des Flusses. Bei kritischen Flüssen wie Bestellungen genügt in den meisten Szenarien ein stündlicher oder mehrmals täglicher Abgleich, bei Stammdaten wie Artikeln ein täglicher oder wöchentlicher. Der Bericht sollte sein Ergebnis bei jedem Lauf festhalten, auch wenn er keine Abweichung findet.

Was ist der Unterschied zwischen Korrelations-ID und Geschäftsschlüssel?

Die Korrelations-ID ist eine technische ID, die erzeugt wird, um einen einzelnen Flusslauf oder eine Anfrage über Komponenten hinweg zu verfolgen. Der Geschäftsschlüssel ist ein Wert, den die Fachseite kennt, etwa die Bestellnummer. Beide werden gemeinsam protokolliert; das technische Team sucht nach der Korrelations-ID, der Support nach dem Geschäftsschlüssel.

Wie lässt sich Alarmrauschen verringern?

Statt für einzelne technische Fehler werden Alarme für Bedingungen definiert, die geschäftliche Auswirkungen zeigen; es wird abgewartet, ob die Bedingung eine Weile anhält, und Schwellen werden nach Geschäftszeiten eingestellt. Jeder Alarm hat einen Eigentümer und eine Eingriffsnotiz. Alarme, auf die lange niemand reagiert hat, werden überprüft und entweder korrigiert oder entfernt.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge