Fehlerbehandlung und Protokollierung in Integrationen #

Diese Seite ist für Integrationsentwickler. Eine Integration scheitert früher oder später: Das andere System ist nicht erreichbar, ein Datensatz ist ungültig, ein Zugangsdatum läuft ab. Ob das ein Nichtereignis oder ein Vorfall ist, hängt davon ab, wie der Code scheitert, wiederholt und berichtet. Die Protokollierungswerkzeuge des Kernels stehen unter eZDebug und Protokollierung.

Inhalt #

1. Drei Arten von Fehlern
2. Wiederholungen und der Dead Letter
3. Transaktionen
4. In die Protokolle schreiben
5. Die Protokolle lesen
6. Was nie in ein Protokoll gehört

Drei Arten von Fehlern #

Ein Lauf, der Datensätze überspringt, muss das trotzdem sagen: Die Zusammenfassungszeile zählt sie, und der Exit-Code oder ein Statuskennzeichen teilt der Überwachung mit, dass der Lauf nicht sauber war.

Wiederholungen und der Dead Letter #

• Wiederholen Sie vorübergehende Fehler mit exponentiellem Backoff und einer Obergrenze (zum Beispiel 2, 4, 8 ... Minuten, höchstens eine Stunde), und beachten Sie Retry-After des anderen Systems.
• Verschieben Sie das Element nach einer festen Zahl von Versuchen in einen Zustand Dead Letter (ein Status in Ihrer Outbox-Tabelle oder die Dead-Letter-Ablage von expqueue) und alarmieren Sie. Ein Element, das ewig wiederholt wird, verdeckt ein echtes Problem.
• Machen Sie Wiederholungen sicher: Der Empfänger muss eine wiederholte Zustellung an einem Idempotenzschlüssel erkennen (Einen Export schreiben).

Transaktionen #

eZContentFunctions::createAndPublishObject() verwaltet seine eigene Transaktion. Wenn Ihr Code mehrere zusammengehörige Zeilen Ihrer eigenen Tabellen schreibt, klammern Sie sie ein:

<?php
$db = eZDB::instance();
$db->begin();
$db->query( 'UPDATE myintegration_outbox SET sent = ' . time() . ' WHERE id = ' . (int)$rowID );
$db->query( 'INSERT INTO myintegration_delivery ( outbox_id, answered ) VALUES ( ' . (int)$rowID . ', ' . time() . ' )' );
$db->commit();

Halten Sie eine Transaktion nie über einen Aufruf an ein anderes System hinweg offen: Eine langsame Antwort hält Datenbanksperren für jeden Redakteur.

In die Protokolle schreiben #

Welche Stufen die Protokolldateien erreichen, legt site.ini [DebugSettings] AlwaysLog[] fest (standardmäßig error). Verwenden Sie für die Spur der Integration eine eigene eZLog-Datei, damit Betreiber sie finden, ohne die Kernel-Protokolle zu durchsuchen.

Eine gute Zusammenfassungsmeldung (eZLog stellt das Datum voran):

import erp-products: rows=20412 created=12 updated=388 unchanged=19990 hidden=3 skipped=19 failed=0 seconds=274

Die Protokolle lesen #

• Setup > Logdateien (die Protokollansicht) listet, verfolgt und durchsucht die Protokolldateien und ihre Rotationen, mit Maskierung personenbezogener Daten (Die Protokollansicht).

• Fehlerreferenzen: Eine Fehlerseite zeigt eine Referenz wie ERR-0123456789, die auch in error.log geschrieben wird; die Protokollansicht und php bin/php/console exp:logs --reference=ERR-... zeigen jede Zeile dieser Anfrage (Einen Fehler über seine Referenz finden).

• Aus einer Shell:

  php bin/php/console exp:logs --list
  php bin/php/console exp:logs --tail=var/log/myintegration.log --lines=50
  php bin/php/console exp:logs --search=erp-product --file=var/log/error.log --rotations

• Das Audit-Protokoll beantwortet „wer hat was geändert": Schreibzugriffe über expservices, Nutzung und Ablehnung von API-Schlüsseln, Entfernen von Inhalten (Audit). Eine Integration, die für Benutzer handelt, kann über die Audit-API eigene Ereignisse festhalten.

• Protokolldateien rotiert der Cronjob-Teil logs (explogrotate.php) (Protokollrotation).

Was nie in ein Protokoll gehört #

• Passwörter, API-Schlüssel, Token, Signaturgeheimnisse, Sitzungs-IDs.
• Vollständige Nutzdaten mit personenbezogenen Daten; protokollieren Sie stattdessen Schlüssel und Anzahlen.
• Kartendaten jeder Art.

Die Protokollansicht maskiert E-Mail- und IP-Adressen und Token, aber Maskierung ist ein Sicherheitsnetz, keine Erlaubnis, sie zu schreiben.

Verwandte Seiten #

• eZDebug und Protokollierung
• Fehlersuche und Protokolle für App-Ersteller
• Integrationen überwachen
• Protokollansicht und Rotation für Hoster
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.