Automationen mit Traces systematisch untersuchen

Eine Lampe bleibt dunkel, obwohl eine Automation sie einschalten sollte. Dieser einzelne Eindruck verrät noch nicht, ob die Automation überhaupt gestartet ist. Vielleicht traf ihr Auslöser nicht ein, vielleicht verhinderte eine Bedingung die Aktion, vielleicht wurde eine andere Lampe angesprochen. Wer jetzt gleichzeitig Auslöser, Wartezeit und Ziel verändert, kann zufällig eine funktionierende Konfiguration erhalten. Er weiß danach aber weiterhin nicht, welcher Teil falsch war. Systematische Fehlersuche beginnt deshalb mit einer möglichst kleinen überprüfbaren Behauptung.

Für den Einstieg eignet sich eine Automation, die keine echten Geräte bewegt und keine Nachrichten an andere Personen sendet. Das folgende Übungsbeispiel verwendet zwei frei erfundene Schalterhelfer und eine interne Benachrichtigung. Es beschreibt einen Testaufbau, keine vorhandene Installation und keinen hier ausgeführten Test. Die Methode lässt sich anschließend auf reale Abläufe übertragen, sobald deren Auswirkungen bekannt sind. Entscheidend ist, Beobachtungen und Vermutungen während der Untersuchung auseinanderzuhalten.

Zuerst den erwarteten Ablauf aufschreiben

Vor jeder Änderung wird ein Satz formuliert, der Anfang, Voraussetzung und Ergebnis verbindet: Wenn der Testschalter von aus nach ein wechselt und die Freigabe eingeschaltet ist, soll eine interne Meldung erscheinen. Damit ist ausdrücklich kein allgemeiner Wunsch wie „Benachrichtigung bei eingeschaltetem Schalter“ gemeint. Die Formulierung legt einen Übergang fest. Ein bereits eingeschalteter Schalter erfüllt zwar einen Zustand, erzeugt dadurch aber noch keinen neuen Wechsel. Diese Unterscheidung verhindert viele unklare Testversuche.

Daneben gehört eine negative Erwartung: Bei ausgeschalteter Freigabe darf derselbe Wechsel keine Meldung erzeugen. Eine Korrektur ist erst plausibel, wenn beide Fälle bestehen bleiben. Sonst wird womöglich nur die Schutzbedingung entfernt und ein scheinbarer Erfolg erkauft. Bei einem echten Gerät wäre außerdem festzulegen, was bei einem unbekannten Eingangswert passieren soll. Für die erste Übung bleibt diese zusätzliche Frage bewusst außerhalb des Aufbaus, damit zunächst genau eine Entscheidung sichtbar wird.

Zu jedem Versuch werden Ausgangszustand, ausgeführter Schritt und Beobachtung kurz notiert. „Um ungefähr diese Zeit ging es nicht“ ist für einen einzelnen Lauf zu ungenau. Besser ist eine Notiz wie „Freigabe aus, Testschalter zunächst aus, anschließend eingeschaltet, keine Meldung erwartet“. Die tatsächliche Uhrzeit wird lokal ergänzt. Eine solche Versuchsliste braucht keine große Tabelle und keine dauerhafte Sammlung persönlicher Zustände. Sie dient dazu, den richtigen Lauf wiederzufinden und denselben Versuch wiederholen zu können.

Ein überschaubares Übungsobjekt anlegen

Die beiden im Beispiel genannten Helfer müssen in einer eigenen Testumgebung angelegt beziehungsweise durch passende eigene Testhelfer ersetzt werden. Die Kennungen sind ausschließlich Platzhalter. Der folgende YAML-Block ist ein einzelnes illustratives Automationsobjekt für den YAML-Editor einer Automation; in einer Liste mehrerer Automationen benötigt er den passenden Listenkontext. Er wurde nicht gegen eine laufende Instanz dieses Projekts getestet.

id: "beispiel_trace_uebung"
alias: "Beispiel: Freigabe im Trace prüfen"
description: "Übung mit zwei Testhelfern und interner Meldung."
triggers:
  - trigger: state
    entity_id: input_boolean.beispiel_testschalter
    from: "off"
    to: "on"
conditions:
  - condition: state
    entity_id: input_boolean.beispiel_freigabe
    state: "on"
actions:
  - action: persistent_notification.create
    data:
      title: "Trace-Übung"
      message: "Testschalter und Freigabe haben den Testpfad erreicht."
      notification_id: "beispiel_trace_uebung"
mode: single

Die interne Meldung vermeidet für diese Übung eine zusätzliche Abhängigkeit von einem Mobiltelefon. Ihre feste Kennung hält wiederholte Versuche am gleichen Meldeobjekt zusammen; eine vorhandene Meldung mit derselben Kennung wird aktualisiert. Vor einer Beobachtung kann die Testmeldung daher entfernt werden, damit eine alte Anzeige nicht als neuer Erfolg zählt. Die verfügbaren Felder beschreibt die offizielle Dokumentation zu Persistent Notification.

Der Aufbau enthält absichtlich keine Verzögerung und keine Verzweigung. Das ist keine Empfehlung, produktive Abläufe immer zu vereinfachen, sondern eine Entscheidung für einen gut beobachtbaren Versuch. Zwei voneinander unabhängige Helfer erlauben es, Auslösung und Freigabe getrennt zu verändern. Würde ein einziger Schalter beide Aufgaben übernehmen, könnten einige Fehlerklassen gar nicht sichtbar werden. Gute Testobjekte machen die entscheidenden Unterschiede leicht herstellbar.

Den passenden Trace auswählen

Home Assistant stellt für gelaufene Automationen Traces bereit, die den ausgeführten Weg mit den einzelnen Schritten zeigen. Bei in YAML angelegten Automationen ist dafür eine id erforderlich. In der Trace-Ansicht lässt sich außerdem erkennen, welche Konfiguration zum ausgewählten Lauf gehörte. Diese Angaben sind besonders nach einer Bearbeitung hilfreich. Ein älterer Lauf untersucht nicht automatisch die inzwischen geänderte Fassung. Die Grundlagen erläutert die offizielle Seite zur Fehlersuche bei Automationen.

Im Übungsfall wird zunächst die Freigabe ausgeschaltet und der Testschalter von aus nach ein bewegt. Erwartet wird ein begonnener Lauf, dessen Freigabeprüfung negativ ausfällt. Diese negative Prüfung ist kein Defekt. Sie zeigt, dass die Automation ihre beabsichtigte Grenze berücksichtigt. Anschließend wird der Testschalter wieder ausgeschaltet, die Freigabe eingeschaltet und derselbe Wechsel wiederholt. Erst jetzt gehört die Aktion zum erwarteten Pfad. Die zwei Versuche unterscheiden sich damit an genau einer relevanten Voraussetzung.

Beim Lesen eines Traces sollte die Suche am ersten unerwarteten Schritt beginnen. Wenn schon die Freigabe nicht dem erwarteten Wert entspricht, hilft ein Blick auf das Meldungsziel zunächst wenig. Umgekehrt muss bei einem erreichten Aktionsschritt nicht wieder die Auslöselogik umgebaut werden. Diese Reihenfolge hält die Untersuchung nah an der vorhandenen Beobachtung. Sie verhindert, dass ein späteres Symptom als Erklärung für einen früheren Ablaufpunkt verwendet wird.

Fehlende Auslösung und falsche Voraussetzung trennen

Wenn zum bewussten Versuch kein passender Lauf auffindbar ist, wird zunächst der Versuchsaufbau geprüft. War die Automation eingeschaltet? Wurde tatsächlich der Testhelfer verändert, auf den sie verweist? Stand er vorher auf aus? Ist die betrachtete Automation dieselbe wie die bearbeitete? Solche Fragen wirken unspektakulär, haben aber einen großen Vorteil: Jede lässt sich einzeln beantworten. Eine vorschnelle Änderung der Aktion würde keine davon klären.

Ein Zustandsauslöser mit ausdrücklich angegebenem Anfangs- und Zielwert reagiert auf den passenden Übergang. Die genaue Semantik weiterer Auslöser, etwa numerischer Schwellen, sollte separat geprüft werden; aus einem Zustandsbeispiel lässt sie sich nicht pauschal ableiten. Die offizielle Dokumentation der Auslöser ist dafür die maßgebliche Referenz. Im Test wird deshalb stets bewusst der Ausgangswert hergestellt, bevor der nächste Versuch startet.

Zeigt der Lauf dagegen eine abgelehnte Bedingung, wird ihr Eingang betrachtet. Dabei zählt der Wert im untersuchten Ablauf, nicht nur die momentan sichtbare Oberfläche. Ein später eingeschalteter Freigabehelfer erklärt nicht rückwirkend, warum ein früherer Versuch hätte durchlaufen müssen. Die lokale Versuchsnotiz hilft, beide Zeitpunkte auseinanderzuhalten. Falls die Bedienoberfläche eine andere Erwartung erzeugt hat, wird zusätzlich geprüft, ob ihre Karte tatsächlich denselben Helfer zeigt oder lediglich ähnlich beschriftet ist.

Manuelles Ausführen beantwortet eine andere Frage

Die Funktion zum Ausführen der Aktionen überspringt Auslöser und vorgeschaltete Bedingungen. Sie eignet sich damit zum Prüfen der Aktionsfolge, ersetzt aber keinen vollständigen Versuch über den vorgesehenen Auslöser. Auch Daten eines echten Auslöseereignisses stehen auf diesem Weg nicht automatisch in gleicher Weise zur Verfügung. Diese Einschränkung ist in der oben verlinkten offiziellen Fehleranalyse dokumentiert. Ein erfolgreiches manuelles Ausführen ist deshalb ein Teilbefund und kein Nachweis für den gesamten Ablauf.

Im Übungsbeispiel lässt sich damit eine nützliche Trennung erreichen. Erscheint die Meldung beim direkten Aktionslauf, ist der Aktionsweg grundsätzlich erreichbar. Bleibt sie beim regulären Schalterwechsel aus, richtet sich die weitere Untersuchung auf die davorliegenden Schritte. Fehlt sie auch beim direkten Aufruf, wird zuerst die Aktion betrachtet. Die Gegenprobe engt die Suche ein, ohne eine komplizierte Theorie vorauszusetzen. Sie darf allerdings keine unbeabsichtigten Wirkungen auslösen; deshalb wurde hier eine interne Testmeldung gewählt.

Bei produktiven Abläufen braucht dieser Schritt mehr Überlegung. Eine Aktionsfolge kann mehrere Geräte betreffen oder andere Skripte aufrufen. Vor einem direkten Test wird daher vollständig gelesen, was ausgeführt würde. Bei unklaren Folgen wird eine Kopie des Ablaufs mit harmlosen Testzielen untersucht. Diese Kopie beweist nicht, dass das reale Gerät funktioniert. Sie beantwortet die engere Frage, ob die logische Verzweigung unter kontrollierten Eingaben nachvollziehbar ist.

Ausführung und beobachtete Wirkung verbinden

Ein erreichter Aktionsschritt und die gewünschte Wirkung sind zwei unterschiedliche Beobachtungen. Im Beispiel kann eine alte Meldung die Sichtprüfung verwirren. Bei einer Lampe könnte die falsche Zielentität angesprochen worden sein; bei einer komplexeren Folge könnte eine spätere Aktion das Ergebnis wieder verändern. Statt aus dem Trace unmittelbar auf die Außenwelt zu schließen, wird das Ziel deshalb separat kontrolliert. Dabei bleibt die Frage konkret: Welches Objekt sollte sich wie verändern, und woran wäre eine neue Änderung erkennbar?

Wenn mehrere Automationen dasselbe Ziel beeinflussen, wird der Versuch zeitlich begrenzt und die zugehörige Aktivität verglichen. Eine mögliche zweite Regel ist zunächst eine Hypothese. Sie wird erst zur Erklärung, wenn ihr zeitlicher Zusammenhang und ihre Wirkung nachvollziehbar sind. Blind alle anderen Regeln abzuschalten erschwert dagegen die Einordnung und kann gewünschte Funktionen unterbrechen. Besser ist es, die beteiligten Abläufe zunächst zu identifizieren und einen kontrollierten Test mit dokumentierter Ausgangslage vorzubereiten.

Protokolle ergänzen diese Betrachtung, wenn der Trace auf einen technischen Fehler hinweist oder notwendige Eingangswerte fehlen. Dabei wird nur der relevante Zeitraum ausgewertet. Für eine öffentliche Frage werden personenbezogene Inhalte, Adressen und Zugangsdaten aus Auszügen entfernt. Ein hilfreicher Bericht enthält die reduzierte Beispielkonfiguration, die erwartete Reaktion, die tatsächlich beobachtete Abweichung und den letzten nachvollziehbaren Schritt. Eine komplette private Installation ist dafür weder erforderlich noch besonders lesbar.

Ein weiterer hilfreicher Vergleich ist die Wiederholung eines unveränderten Versuchs. Liefert dieselbe Ausgangslage unterschiedliche Ergebnisse, wird zuerst nach einem bislang unbeachteten Einfluss gesucht. Dazu können eine noch vorhandene Meldung, eine zwischenzeitlich veränderte Freigabe oder ein gleichzeitig ausgeführter Ablauf gehören. Die Wiederholung soll keine Statistik vortäuschen. Sie prüft lediglich, ob der beschriebene Versuch ausreichend genau festgelegt wurde. Erst wenn diese Grundlage stabil ist, lohnt sich eine feinere Untersuchung von Zeitpunkten oder zusätzlichen Bedingungen. Andernfalls würde eine aufwendigere Messung nur die Unschärfe des Aufbaus genauer protokollieren.

Die Korrektur durch Gegenproben absichern

Nach der ersten plausiblen Ursache wird genau eine Änderung vorgenommen. Anschließend werden der positive und der negative Versuch wiederholt. Zusätzlich lohnt sich ein Versuch mit bereits eingeschaltetem Testschalter: Er macht sichtbar, ob die ursprüngliche Erwartung eines erneuten Übergangs verstanden wurde. Für jeden Durchlauf wird eine neue, eindeutig zuordenbare Beobachtung gesucht. Bleibt das Ergebnis widersprüchlich, wird die Änderung nicht mit weiteren Vermutungen überdeckt, sondern die noch offene Annahme benannt.

Eine kurze Abschlussnotiz hält Ursache, Korrektur und getestete Grenze fest. Beispielsweise könnte sich in einer eigenen Untersuchung ergeben, dass die Bedienkarte auf einen anderen Helfer verwies. Dann gehört diese konkrete Verwechslung in die Notiz, nicht die unpräzise Aussage, die Automation sei „repariert“ worden. Das Beispiel ist eine mögliche Diagnose, kein Bericht über einen tatsächlich gefundenen Projektfehler. Auch eine ungelöste Untersuchung kann sauber abgeschlossen werden, wenn feststeht, welche Stufe funktioniert und welche Frage offenbleibt.

Die Testhelfer und die Übungsautomation werden nach Abschluss bewusst behalten, deaktiviert oder entfernt. Ihre Bezeichnung sollte den Testzweck weiterhin erkennen lassen. Eine zurückgelassene Meldung oder ein ähnlich benannter Helfer darf nicht später selbst die nächste Verwechslung verursachen. So endet die Fehlersuche mit einer verständlicheren Konfiguration und einem nachvollziehbaren Ergebnis, statt nur mit einem zufällig gelungenen Schaltvorgang.