Integrationen überwachen
Integrationen scheitern nicht laut. Sie scheitern um 02:00 Uhr, in einem Job, den niemand beobachtet, und das erste Symptom ist ein Käufer, der fragt, warum der Preis auf der Rechnung nicht der Preis auf dem Bildschirm ist. Fünf Minuten am Tag verhindern fast alles davon.
Die vier Protokolle
Jedes beantwortet eine andere Frage. Zu wissen, welches man öffnet, spart den größten Teil der Zeit, die sonst in die Untersuchung ginge.
| Protokoll | Wo | Beantwortet |
|---|---|---|
| Event-Stream | Events › Event Stream | Ist das Event überhaupt passiert? |
| Delivery attempts | Webhooks › Outbound, an einem Ziel | Hat es den Empfänger erreicht? |
| Runs | Integration Studio | Ist der geplante Job gelaufen, und was hat er getan? |
| Audit-Log | Integration Studio | Wer hat die Integrationskonfiguration wann geändert? |
Lesen Sie sie in dieser Reihenfolge, wenn etwas nicht stimmt. „Das ERP hat die Bestellung nicht bekommen" zerfällt sofort in drei sehr verschiedene Probleme — je nachdem, in welchem Protokoll die Spur endet.
Der Event-Stream
Jedes Event, das Ihr Tenant erzeugt hat, unabhängig davon, ob irgendein Webhook es zugestellt hat. Zeilen zeigen die Event ID, das Topic und wann es Received wurde. Öffnen Sie eines, sehen Sie die Data, die Metadata, ob es Retryable ist, und — den nützlichen Teil — Routed to: welche Ziele dieses Topic abonnieren.
Dieses letzte Feld beantwortet den häufigsten Fehlalarm in diesem Bereich. Steht dort, dass kein Ziel das Topic abonniert, hat das Event korrekt gefeuert, und niemand wollte davon hören. Das ist ein Abonnementproblem, kein Zustellproblem.
Behalten Sie auch das Volumen im Blick. Ein Event-Zähler, der auf das Zehnfache springt, heißt meist: Eine Massenoperation hat Events je Datensatz gefeuert — etwa eine Massenbearbeitung über 30.000 Produkte. Das wissen Sie besser vor dem Server Ihres Integrators.
Delivery attempts
An einem Webhook-Ziel: das Event, die Versuchsnummer (Try), der Status, der HTTP-Code und When.
So lesen Sie es:
| Muster | Bedeutet |
|---|---|
| Alles gelingt bei Versuch 1 | Gesund |
| Regelmäßige Wiederholungen, die dann gelingen | Der Empfänger ist langsam oder startet neu. An Ihrem vollsten Tag wird er scheitern |
Anhaltend 4xx | Ihr Payload, Topic oder Ihre Credentials sind falsch |
Anhaltend 5xx | Deren System ist kaputt |
| Erfolgreich, aber langsam | Eine Warnung, kein Erfolg. Steigende Latenz geht Timeouts voraus |
| Gar nichts | Das Abonnement, nicht die Zustellung. In den Event-Stream sehen |
Ein Ziel, das dauerhaft fehlschlägt, wird irgendwann automatisch deaktiviert, damit ein toter Endpoint keinen unbegrenzten Rückstau ansammelt. Aktivieren Sie es vom selben Bildschirm aus wieder, sobald der Empfänger repariert ist — und prüfen Sie dann, was verpasst wurde, denn das Wiederaktivieren spielt die Historie nicht nach.
Runs
Geplante Workflows und Datei-Jobs. Was hier zählt, ist nicht nur „fehlgeschlagen", sondern erfolgreich mit Abweisungen: Ein Preisimport, der 38.000 Zeilen geladen und 2.000 abgewiesen hat, meldet Erfolg und hat Ihren Katalog teilweise falsch hinterlassen. Lesen Sie die Zeilenzahlen, nicht das Status-Badge. Siehe Syncs überwachen.
Die drei Alarme, die sich lohnen
Leiten Sie alle auf eine Team-Adresse, nie auf jemandes Postfach. Der Sinn ist ja, dass sie auch funktionieren, wenn jemand im Urlaub ist.
1. Ein Lauf ist fehlgeschlagen. Der offensichtliche, den alle setzen.
2. Ein Lauf war erfolgreich, hat aber Zeilen abgewiesen. Der gefährliche. Stiller Teilerfolg ist der Weg, auf dem ein Katalog halb aktualisiert endet, ohne dass irgendwo etwas rot ist.
3. Bis zur erwarteten Zeit kam nichts an. Der, den alle vergessen, und der, der den schlimmsten Fehler fängt. Stirbt der ERP-Job, der die nächtliche Datei erzeugt, schlägt kein Import fehl — es passiert gar nichts. Jedes Protokoll ist sauber, jedes Dashboard grün, und Ihr Shop liefert die Preise der letzten Woche aus, bis ein Kunde es bemerkt.
Diesen dritten Alarm bauen Sie als positive Erwartung: Bis 03:00 Uhr sollte ein abgeschlossener Lauf von Profil X existieren. Die Abwesenheit ist die Bedingung.
Schlüsselnutzung
Öffnen Sie zweimal im Jahr Einstellungen › API-Schlüssel und lesen Sie die Liste als Inventar, nicht als Bildschirm:
| Frage | Wenn die Antwort schlecht ausfällt |
|---|---|
| Wissen wir, wofür jeder Schlüssel ist? | Widerrufen. Ein Schlüssel, den niemand erklären kann, ist ein Schlüssel, den niemand kontrolliert |
| Passt der Scope noch zur Aufgabe? | Verengen. Scopes werden beim Troubleshooting geweitet und danach nie verengt |
| Nutzt ihn noch etwas? | Ein ungenutzter Schlüssel ist tot oder kurz davor, jemanden zu überraschen |
Trägt irgendetwas *? | Durch die tatsächlich genutzten Scopes ersetzen |
| Hat jemand das Projekt verlassen? | Seine Sandbox-Schlüssel widerrufen |
Legen Sie Ihr eigenes Schlüsselinventar daneben — Schlüsselname, Integration, Verantwortlicher, wen man beim Widerruf anruft —, und das Review dauert zwanzig Minuten statt einen Vormittag.
Ein Problem korrelieren
Wenn Ihr Integrator sagt „die API hat am Dienstag Fehler geworfen", macht ein Feld daraus etwas Beantwortbares.
Jede Antwort trägt eine X-Request-ID. Protokolliert er sie, lässt sich
ein konkreter fehlgeschlagener Aufruf nachverfolgen. Tut er es nicht,
vergleichen Sie Zeitstempel über zwei Systeme mit verschiedenen Uhren.
Machen Sie es zur Go-live-Anforderung: X-Request-ID bei jedem Aufruf
protokollieren, und in jedem Supportfall zitieren. Es ist das billigste
Einzelstück in diesem ganzen Bereich.
Wie „gesund" aussieht
Eine brauchbare Grundlinie, damit Sie das Abnormale erkennen:
- Fehlerrate stetig und niedrig. Was zählt, ist ihre Form — ein Sprung von 0,1 % auf 3 % zählt, obwohl 3 % klein klingt.
429-Antworten: selten oder keine. Ein stetes Rinnsal heißt: Eine Integration lebt am Limit entlang und kippt an Ihrem vollsten Tag. Siehe Rate-Limits, Kontingente und Fair Use.- Webhook-Erfolg im ersten Versuch nahe 100 %.
- Failed-Queue leer. Ist sie es nicht, muss jemand über das Nachspielen entscheiden, und diese Entscheidung hat eine Frist.
- Latenz stabil. Steigende Latenz ist der Frühindikator für alles andere.
Die täglichen fünf Minuten
- Fehlgeschlagene Läufe seit gestern?
- Ein Lauf, der mit Abweisungen erfolgreich war?
- Ist die Failed-Queue der Webhooks leer?
- Sind alle erwarteten Nachtdateien angekommen?
- Ein
429in den letzten 24 Stunden?
Fünf Fragen, eine Person, vor dem ersten Kaffee. Alles auf dieser Seite existiert, damit diese fünf in fünf Minuten beantwortbar sind.
Weiter
- Häufige API-Probleme — die Fehler lesen, die hier auftauchen.
- Mit API-Änderungen umgehen — die Fehler, die im Voraus terminiert sind.