epilot Integrationen im Betrieb: Monitoring, Fehler, Wartung

Die Wartung einer epilot Integration beginnt in dem Moment, in dem die Schnittstelle live geht. Ab dann muss sie zuverlässig laufen, Fehler sichtbar machen und mit jeder Änderung in epilot oder in Ihren Umsystemen Schritt halten. Dieser Artikel zeigt, was im Betrieb einer Schnittstelle zu tun ist und wer es tun kann.

Geschrieben hat ihn Marcel R. G. Berger. Ich bin seit über 20 Jahren Softwareentwickler und Softwarearchitekt und arbeite mit epilot als externer Consultant und Entwickler für Apps und Individualisierungen. Der Text richtet sich an IT-Verantwortliche bei Netzbetreibern, Stadtwerken und Energieversorgern, die eigene Schnittstellen rund um epilot betreiben oder planen.

Was passiert mit einer epilot Integration nach dem Go-live?

Nach dem Go-live wird aus einem Projekt ein Dienst, der jeden Tag funktionieren muss. Die Schnittstelle verarbeitet echte Daten, und jeder Fehler betrifft echte Vorgänge.

Damit verschieben sich die Fragen. Während der Umsetzung geht es darum, ob die Zuordnung stimmt. Im Betrieb geht es darum, ob Sie merken, wenn etwas nicht mehr stimmt, und wie schnell sich die Ursache finden lässt.

Typische Aufgaben im Betrieb einer Schnittstelle sind:

• Überwachen, ob die Mapper laufen und ihre Umsysteme erreichen
• Fehler erkennen, einordnen und betroffene Vorgänge erneut verarbeiten
• Abhängigkeiten, Java-Laufzeit und Container-Images aktuell halten
• Zuordnungen anpassen, wenn sich epilot oder ein Umsystem ändert
• Dokumentation, Runbooks und Tests auf dem Stand halten

Wie ein solcher Mapper aufgebaut ist, beschreibt der Artikel Mapper zwischen epilot und Umsystemen mit Quarkus. Hier geht es um die Zeit danach. Welche Systeme typischerweise beteiligt sind, beschreibt der Überblick Umsysteme an epilot anbinden.

Wie überwachen Sie Mapper mit Health Checks und Logging?

Mapper werden über Health Checks, strukturiertes Logging und Alarme überwacht. Health Checks zeigen, ob ein Dienst bereit ist, Logs zeigen, was er mit einem Datensatz gemacht hat, und Alarme sorgen dafür, dass jemand davon erfährt.

Health und Readiness Probes

Quarkus bringt mit SmallRye Health eigene Endpunkte für den Zustand eines Dienstes mit. Der Quarkus-Leitfaden zu SmallRye Health nennt /q/health/live für die Frage, ob der Prozess lebt, /q/health/ready für die Frage, ob er Anfragen annehmen kann, und /q/health/started für den Start. Eine Container-Plattform fragt diese Endpunkte regelmäßig ab.

Eigene Prüfungen lassen sich mit @Liveness oder @Readiness ergänzen. Ein Beispiel für eine Readiness-Prüfung, die die Erreichbarkeit eines Umsystems meldet:

@Readiness
@ApplicationScoped
public class TargetSystemReadiness implements HealthCheck {

    @Inject
    TargetSystemPing ping;

    @Override
    public HealthCheckResponse call() {
        return ping.isReachable()
                ? HealthCheckResponse.up("target-system")
                : HealthCheckResponse.down("target-system");
    }
}

TargetSystemPing ist eine eigene Klasse des Projekts. Wichtig ist die Abgrenzung: Die Liveness-Prüfung sollte nur den eigenen Prozess betrachten. Hängt sie von einem Umsystem ab, startet die Plattform den Mapper neu, obwohl er selbst gesund ist und nur auf das Umsystem wartet.

Strukturiertes Logging

Strukturiertes Logging bedeutet, dass jede Logzeile maschinenlesbare Felder enthält, etwa die Kennung der Nachricht, den Vorgang und das Ergebnis. Der Quarkus-Leitfaden zu Logging beschreibt, wie sich die Ausgabe auf JSON umstellen lässt.

quarkus.log.console.json.enabled=true

So lässt sich ein einzelner Datensatz über epilot, Mapper und Umsystem hinweg verfolgen. Personenbezogene Daten gehören dabei nicht ungefiltert ins Log. Es reicht, Kennungen zu protokollieren, über die sich der Vorgang finden lässt.

Alarme

Alarme machen aus Messwerten eine Benachrichtigung. Sinnvoll sind Alarme für Dienste, die nicht mehr bereit sind, für eine steigende Zahl fehlgeschlagener Verarbeitungen und für einen offenen Schutzschalter. Welche Werkzeuge dafür genutzt werden, richtet sich nach Ihrer vorhandenen Plattform.

Wie erkennen und beheben Sie Fehler bei epilot Webhooks?

Fehler bei epilot Webhooks erkennen Sie im Monitoring der Webhooks in epilot und in den Logs des Mappers. Beheben lassen sie sich, indem Sie die Ursache korrigieren und das Ereignis erneut abspielen.

Laut der Dokumentation zum Monitoring der epilot Webhooks wird jede Webhook-Anfrage als Ereignis mit Erfolgs- oder Fehlerstatus protokolliert. In jeder Webhook-Konfiguration lassen sich die Ereignisse nach Status filtern, Payload, Header und Antwortcode einsehen und jedes Ereignis erneut abspielen. Ein Replay sendet denselben Payload noch einmal und legt einen neuen Ereignis-Eintrag an. Die Ereignisse werden standardmäßig vier Wochen aufbewahrt.

Daraus ergibt sich ein einfacher Ablauf für den Betrieb:

1. Ein Alarm oder ein Blick ins Monitoring zeigt fehlgeschlagene Zustellungen.
2. Anhand des Antwortcodes und der Logs des Mappers wird die Ursache eingeordnet.
3. Die Ursache wird behoben, etwa eine fehlende Zuordnung oder ein nicht erreichbares Umsystem.
4. Die betroffenen Ereignisse werden in epilot erneut abgespielt.

Damit ein Replay sicher ist, muss der Mapper idempotent arbeiten. Wird derselbe Payload zweimal zugestellt, darf im Umsystem kein zweiter Datensatz entstehen. Dafür prüft der Mapper anhand eines fachlichen Schlüssels aus dem Payload, ob der Vorgang schon verarbeitet wurde.

Wichtig ist auch die Antwort des Mappers selbst. Ein Fehlercode an epilot sollte bedeuten, dass der Vorgang nicht verarbeitet wurde. Nur dann zeigt das Monitoring in epilot ein ehrliches Bild.

Wie gehen Mapper mit Rate Limits und Ausfällen von Umsystemen um?

Mapper gehen mit Rate Limits und Ausfällen über Wiederholungen mit Wartezeit, Zeitlimits und einen Schutzschalter um. Ziel ist, dass ein kurzer Ausfall keinen dauerhaften Fehler erzeugt und ein langer Ausfall das System nicht zusätzlich belastet.

Rate Limits der epilot API

Die Seite zu Rate Limits in der epilot Dokumentation beschreibt, dass die API beim Überschreiten eines Limits mit HTTP 429 antwortet. Der Header Retry-After gibt an, nach wie vielen Sekunden das Kontingent zurückgesetzt wird. Die Limits gelten laut Dokumentation je Organisation, lesende GET-Anfragen sind ausgenommen.

Ein Mapper, der nach epilot zurückschreibt, liest diesen Header und wartet entsprechend. Die Dokumentation empfiehlt außerdem, für größere Datenmengen die dafür vorgesehenen Batch-Schnittstellen zu nutzen.

Wiederholungen, Zeitlimits und Schutzschalter

Für die Aufrufe von Umsystemen nutze ich SmallRye Fault Tolerance. Der Quarkus-Leitfaden zu SmallRye Fault Tolerance beschreibt unter anderem diese Annotationen:

Annotation	Zweck im Betrieb
@Retry	wiederholt einen fehlgeschlagenen Aufruf
@ExponentialBackoff	verlängert die Wartezeit zwischen den Wiederholungen schrittweise
@Timeout	bricht Aufrufe ab, die zu lange dauern
@CircuitBreaker	stoppt Aufrufe an ein System, das gerade ausfällt, und prüft später erneut
@Fallback	legt fest, was passiert, wenn alle Versuche scheitern
@Bulkhead	begrenzt, wie viele Aufrufe gleichzeitig laufen

Nicht jeder Fehler gehört wiederholt. Ein Datensatz, den das Umsystem fachlich ablehnt, bleibt abgelehnt. Solche Fälle werden protokolliert und als Fehler gemeldet, damit jemand sie prüft. Wiederholt werden nur vorübergehende Fehler wie Zeitüberschreitungen oder nicht erreichbare Systeme.

Warum braucht eine Schnittstelle im Betrieb regelmäßige Updates?

Eine Schnittstelle braucht regelmäßige Updates, weil sich ihre Umgebung ständig ändert. Bibliotheken, die Java-Laufzeit und das Basis-Image des Containers bekommen Sicherheitskorrekturen, und Quarkus selbst erscheint in neuen Versionen.

Ein Mapper, der nie aktualisiert wird, läuft oft noch lange weiter. Er sammelt aber bekannte Schwachstellen an, und der Sprung auf eine aktuelle Version wird mit jedem Monat größer.

Zur Pflege gehören deshalb drei Ebenen:

• Abhängigkeiten im Build, also Quarkus und weitere Bibliotheken in Maven oder Gradle
• die Java-Laufzeit, auf der der Dienst läuft
• das Basis-Image des Containers mit seinen Systempaketen

Der Quarkus-Leitfaden zu Container-Images beschreibt, wie das Image direkt aus dem Build entsteht, etwa über Jib, Docker oder Podman. Damit lässt sich ein Image nach einem Update automatisiert neu bauen, testen und ausliefern. Auch ohne Änderung am eigenen Code ist ein neu gebautes Image sinnvoll, wenn das Basis-Image korrigiert wurde.

Konfiguration und Secrets außerhalb des Codes

Adressen, Zugangsdaten und Signaturgeheimnisse stehen nicht im Code, sondern kommen aus Umgebungsvariablen oder einem Secret-Speicher. Die Quarkus-Referenz zur Konfiguration zeigt, aus welchen Quellen Quarkus Werte liest.

Für den Betrieb hat das zwei Vorteile. Dasselbe Image läuft in Test und Produktion, nur mit anderer Konfiguration. Und ein Schlüssel lässt sich wechseln, ohne den Dienst neu zu bauen.

Was passiert, wenn sich epilot oder ein Umsystem ändert?

Wenn sich die Konfiguration in epilot oder ein Umsystem ändert, muss oft auch die Zuordnung im Mapper angepasst werden. Ein neues Feld in einem epilot Schema, ein geänderter Code in einem Fachsystem oder eine neue Version einer API sind typische Auslöser.

Gerade bei epilot passiert das häufig, und das ist gewollt. Fachabteilungen passen Datenmodelle, Journeys und Automationen selbst an, weil epilot eine hervorragende No-Code- und Low-Code-Plattform ist. Die Schnittstelle muss mit diesen Änderungen Schritt halten. Wo die Grenze zwischen Konfiguration und Code verläuft, beschreibt der Artikel Wann reicht Low-Code bei epilot nicht mehr?.

Damit Änderungen nicht überraschend kommen, helfen zwei Absprachen:

• Änderungen an Feldern, die eine Schnittstelle nutzt, werden vorher angekündigt.
• Zuordnungen sind im Repository dokumentiert, sodass sichtbar ist, welche Felder betroffen sind.

Tests als Sicherheitsnetz

Tests sind das Sicherheitsnetz für jede Änderung im Betrieb. Für jede Zuordnung gibt es Beispieldaten aus epilot und die erwartete Ausgabe für das Umsystem. Der Quarkus-Leitfaden zum Testen zeigt, wie @QuarkusTest den ganzen Dienst startet und seine Endpunkte prüft.

Ändert sich eine Regel, zeigen die Tests sofort, welche Fälle betroffen sind. Und nach einem Update von Abhängigkeiten zeigen sie, ob der Mapper noch genauso arbeitet wie vorher.

Welche Dokumentation braucht der Betrieb einer Schnittstelle?

Der Betrieb einer Schnittstelle braucht eine Beschreibung der Datenflüsse, der Zuordnungen und der Konfiguration sowie Runbooks für typische Störungen. Ohne diese Unterlagen hängt der Betrieb an einzelnen Personen.

Ein Runbook beschreibt Schritt für Schritt, was bei einer bestimmten Störung zu tun ist. Typische Einträge sind:

• Ein Umsystem ist nicht erreichbar: wie Sie es erkennen, was der Mapper automatisch tut und wann Ereignisse erneut abgespielt werden
• Webhooks schlagen nach einer Änderung in epilot fehl: wo die Zuordnung steht und wie sie getestet wird
• Ein Secret muss gewechselt werden: wo es liegt und wie der Dienst den neuen Wert übernimmt
• Eine neue Version soll ausgeliefert werden: wie gebaut, getestet und zurückgerollt wird

Dokumentation gehört ins selbe Repository wie der Code. So bleibt sie mit jeder Änderung auf dem Stand, und wer den Code übernimmt, übernimmt sie gleich mit.

Wer übernimmt die Wartung der epilot Integration nach der Umsetzung?

Nach der Umsetzung gibt es zwei Wege, und Sie entscheiden. Der Code gehört in beiden Fällen Ihnen.

Im ersten Weg übergebe ich den Code in Ihr eigenes Repository. Ihre IT oder ein anderer Partner betreibt und entwickelt ihn dann weiter. Im zweiten Weg übernehme ich Betreuung und Weiterentwicklung über einen Wartungsvertrag.

Kriterium	Übergabe in Ihr Repository	Wartungsvertrag
Eigentum am Code	liegt bei Ihnen	liegt bei Ihnen
Betrieb und Monitoring	Ihre IT oder ein Partner Ihrer Wahl	Betreuung durch mich nach Absprache
Updates und Sicherheitskorrekturen	übernimmt Ihr Team	übernehme ich
Anpassung von Zuordnungen	übernimmt Ihr Team	übernehme ich
Voraussetzung	Java-Kenntnisse im Team oder beim Partner	Zugang zu Repository und Umgebungen nach Absprache
Grundlage	Dokumentation, Runbooks und Tests im Repository	Dokumentation, Runbooks und Tests im Repository

Beide Wege lassen sich auch nacheinander gehen. Ein Wartungsvertrag schließt eine spätere Übergabe nicht aus, weil Code und Dokumentation ohnehin in Ihrem Repository liegen können. Warum das Eigentum am Code so wichtig ist, erklärt der Artikel Wem gehört der Integrationscode?.

Dabei ergänze ich das Consulting-Team von epilot, ich ersetze es nicht. epilot bleibt Ihr Ansprechpartner für die Plattform. Ich kümmere mich um die Schnittstellen, die außerhalb davon laufen.

Warum ist ein stabiler Schnittstellenbetrieb für Netzbetreiber so wichtig?

Für Netzbetreiber ist ein stabiler Schnittstellenbetrieb wichtig, weil Vorgänge zuverlässig und nachvollziehbar durch mehrere Systeme laufen müssen. Ein still verlorener Datensatz fällt oft erst auf, wenn ein Kunde nachfragt.

Drei Punkte stehen dabei im Vordergrund:

• Stabile Prozesse: Wenn Vorgänge über mehrere Systeme laufen, muss jeder Übergang funktionieren.
• Nachvollziehbarkeit: Strukturierte Logs, das Monitoring in epilot und versionierte Zuordnungen zeigen, was mit einem Vorgang passiert ist und welche Regel zu welchem Zeitpunkt galt. Das hilft bei internen und externen Prüfungen.
• Kontinuität: Dokumentation, Runbooks und Tests sorgen dafür, dass der Betrieb nicht an einer einzelnen Person hängt.

So arbeite ich auch im aktuellen Projekt bei einem Netzbetreiber in Hessen. Viele Prozesse laufen dort außerhalb von epilot, und mehrere Drittsysteme sind über individuell entwickelte Schnittstellen angebunden. Die Mapper-Tools entstehen in Java mit Quarkus, laufen containerisiert und sind auf Skalierbarkeit und Wartbarkeit ausgelegt. Mehr dazu steht im Abschnitt Aus der Praxis auf der Startseite.

Vertragspartner ist die DigitalFreedom Global LLC. Für Netzbetreiber ist auf Wunsch deutsches Recht möglich. Daten bleiben in Europa, die Verarbeitung folgt der DSGVO, und wo nötig wird ein Vertrag zur Auftragsverarbeitung geschlossen. Details stehen im Abschnitt Vertragspartner auf der Startseite.

Wie starten Sie mit Betrieb und Wartung Ihrer Schnittstelle?

Sie starten mit einem kostenlosen Erstgespräch, in dem wir Ihre Schnittstellen und Ihren Betrieb durchgehen. Danach ist klar, ob eine Übergabe in Ihr Repository, ein Wartungsvertrag oder beides nacheinander passt.

1. Erstgespräch: kostenlos und unverbindlich über Microsoft Teams.
2. Bestandsaufnahme: welche Mapper laufen, wie sie überwacht werden und wo Dokumentation oder Tests fehlen.
3. Individuelles Angebot: zugeschnitten auf Ihre Systeme und Ihre Anforderungen an den Betrieb.

Alle Leistungen biete ich auf Basis eines individuellen Angebots an. Welche Leistungen dazu gehören, steht im Abschnitt Was ich für epilot-Kunden mache. Einen Termin wählen Sie direkt im Buchungskalender.