Traces — Begrijpen waarom Home Assistant deed wat het deed

In het vorige hoofdstuk heb je gezien dat je een automatisering niet meteen moet vertrouwen alleen omdat ze één keer goed lijkt te werken.

Je voorspelt eerst wat er zou moeten gebeuren.
Daarna lok je bewust een situatie uit.
Vervolgens controleer je wat Home Assistant werkelijk doet.

Dat werkt goed zolang de uitkomst duidelijk is.

De lamp gaat aan.
Of de lamp gaat niet aan.

Maar zodra een automatisering uit meerdere onderdelen bestaat, ontstaat er een nieuwe vraag:

Waarom deed Home Assistant dit?

Misschien werd de trigger wel geactiveerd, maar hield een voorwaarde de automatisering tegen.

Misschien werd een Choose-tak anders gekozen dan je verwachtte.

Misschien begon een wachttijd wel, maar werd de automatisering ondertussen opnieuw gestart.

Of misschien werd een actie helemaal bereikt, maar reageerde het apparaat zelf niet.

Alleen naar het eindresultaat kijken is dan niet meer genoeg.

Je wilt als het ware kunnen terugkijken naar de route die Home Assistant door de automatisering heeft afgelegd.

Daarvoor bestaan traces.

Wat is een trace?

Een trace is een registratie van één uitvoering van een automatisering.

Je kunt het vergelijken met voetsporen.

Normaal zie je alleen waar Home Assistant uiteindelijk is uitgekomen.

Met een trace kun je terugkijken:

waardoor de automatisering werd gestart;
welke waarden Home Assistant op dat moment zag;
welke voorwaarden waar of onwaar waren;
welke route door Choose werd genomen;
welke acties werden uitgevoerd;
waar eventueel werd gewacht;
en waar de uitvoering stopte.

Je kijkt dus niet alleen naar:

De lamp ging niet aan.

maar bijvoorbeeld naar:

De bewegingssensor startte de automatisering, maar de luxvoorwaarde was niet waar. Daarom werd de actie om de lamp in te schakelen niet uitgevoerd.

Dat is een veel bruikbaardere conclusie.

Een trace is geen foutmelding

Dit onderscheid is belangrijk.

Een trace wordt niet alleen gemaakt wanneer er iets fout gaat.

Ook een goed uitgevoerde automatisering kan een trace hebben.

Een trace vertelt vooral:

Wat gebeurde er tijdens deze ene uitvoering?

Soms zie je daarin daadwerkelijk een fout.

Maar vaak ontdek je dat Home Assistant technisch precies heeft gedaan wat jij hebt ingesteld.

Alleen was dat niet wat jij bedoelde.

Dat verschil kom je bij automatiseringen regelmatig tegen.

Ons voorbeeld uit De Werkplaats

We gebruiken dezelfde soort automatisering als in het vorige hoofdstuk.

In De Werkplaats willen we de verlichting inschakelen wanneer:

er beweging wordt gedetecteerd;
én het buiten of binnen donker genoeg is.

In gewone taal:

Als er beweging in De Werkplaats wordt gedetecteerd en het lichtniveau lager is dan 400 lux, zet dan de werkplaatsverlichting aan.

De opbouw is ongeveer:

Trigger

Beweging wordt gedetecteerd.

Voorwaarde

Lux is lager dan 400.

Actie

Werkplaatsverlichting inschakelen.

Op het eerste gezicht is dit een eenvoudige automatisering.

Toch kan ze op verschillende manieren eindigen.

Eerst voorspellen

Stel dat je overdag De Werkplaats binnenloopt.

De bewegingssensor ziet je.

Het lichtniveau is 850 lux.

Wat verwacht je?

De automatisering mag wel starten, omdat beweging de trigger is.

Maar de verlichting hoort niet aan te gaan, omdat de voorwaarde niet waar is.

Dat verschil is belangrijk:

gestart worden is niet hetzelfde als alle acties uitvoeren.

Dat kunnen we met een trace controleren.

Waar vind je traces?

Open in Home Assistant de automatisering die je wilt onderzoeken.

Afhankelijk van de gebruikte Home Assistant-versie kan de precieze plaats of benaming iets veranderen, maar bij de automatisering kun je de recente uitvoeringen en bijbehorende traces bekijken.

Open één van die uitvoeringen.

Je ziet vervolgens de automatisering als een reeks stappen.

Home Assistant laat daarbij zien welke onderdelen zijn doorlopen.

Dat maakt een trace vooral visueel erg nuttig.

Je hoeft niet meteen YAML of logbestanden te lezen.

Kijk eerst naar de trigger

Begin altijd bovenaan.

Welke trigger heeft deze uitvoering gestart?

Dat klinkt vanzelfsprekend, maar dit is een belangrijke eerste controle.

Een automatisering kan namelijk meerdere triggers hebben.

Bijvoorbeeld:

beweging;
een bepaald tijdstip;
een verandering van lichtniveau;
of het indrukken van een knop.

Wanneer iets onverwachts gebeurt, wil je eerst weten:

Welke trigger heeft Home Assistant eigenlijk gebruikt?

Dat voorkomt dat je verderop naar een probleem zoekt terwijl het probleem al bij het startpunt zit.

De trigger bleek wel te werken

Stel dat je in onze trace ziet:

Beweging gedetecteerd — automatisering gestart.

Dan weet je meteen iets belangrijks.

De bewegingssensor heeft zijn werk gedaan.

De trigger is herkend.

Je hoeft op dat moment dus niet eerst:

de sensor opnieuw toe te voegen;
de integratie te verwijderen;
Home Assistant opnieuw op te starten;
of allerlei andere instellingen te veranderen.

Je hebt al informatie waarmee je het zoekgebied kleiner kunt maken.

Dat is precies de manier waarop we in deze gids problemen willen benaderen:

verander niet meteen van alles, maar bepaal eerst waar het gedrag afwijkt van je verwachting.

Daarna naar de voorwaarden

Na de trigger komt Home Assistant bij onze luxvoorwaarde.

Daar zie je bijvoorbeeld dat Home Assistant controleerde of:

lichtniveau < 400 lux

Op dat moment was het gemeten lichtniveau:

850 lux

De voorwaarde is dus niet waar.

De uitvoering stopt daar.

De actie om de verlichting aan te zetten wordt niet bereikt.

Daarmee is het raadsel opgelost.

De automatisering werkt.

Alleen waren de omstandigheden anders dan misschien op het eerste gezicht duidelijk was.

Dit is waarom traces zo waardevol zijn

Zonder trace zou je kunnen denken:

De bewegingssensor werkt niet.

Of:

De automatisering is kapot.

Met de trace zie je:

De bewegingssensor werkte wel. De luxvoorwaarde voorkwam terecht dat de lamp werd ingeschakeld.

Dat is een totaal andere conclusie.

Een goede foutanalyse begint daarom niet met aanpassen.

Ze begint met waarnemen.

Test nu dezelfde automatisering in het donker

We veranderen één ding.

Niet de automatisering.

Alleen de situatie.

Maak het donker genoeg zodat de luxwaarde bijvoorbeeld 180 lux wordt.

Controleer eerst de sensorwaarde in Home Assistant.

Voorspel vervolgens wat er gebeurt wanneer je beweging veroorzaakt.

Je verwacht nu:

de bewegingssensor activeert de trigger;
Home Assistant controleert de luxvoorwaarde;
180 is lager dan 400;
de voorwaarde is dus waar;
Home Assistant voert de actie uit;
de verlichting gaat aan.

Voer de test uit.

Open daarna opnieuw de trace.

Loop de stappen één voor één na.

Dat is veel leerzamer dan alleen tevreden constateren dat de lamp brandt.

Een trace vertelt je welke route werd genomen

Bij eenvoudige automatiseringen is het pad nog overzichtelijk.

Maar eerder in deze gids hebben we ook Choose gebruikt.

Daarbij kan Home Assistant uit meerdere routes kiezen.

Bijvoorbeeld:

overdag niets doen;
's avonds de gewone verlichting inschakelen;
's nachts alleen een zachte lamp gebruiken.

Wanneer Home Assistant een andere route kiest dan je verwacht, is alleen het eindresultaat soms moeilijk te verklaren.

Een trace laat zien welke keuze daadwerkelijk is gemaakt.

Dat maakt Choose ineens een stuk minder ondoorzichtig.

Voorbeeld met Choose

Stel dat je in De Werkplaats de volgende regeling hebt:

Als er beweging is:

tussen 07:00 en 22:30 → hoofdverlichting aan;
tussen 22:30 en 07:00 → alleen een kleine lamp aan.

Je loopt om 22:25 De Werkplaats binnen.

De hoofdverlichting gaat aan.

Dat verwacht je.

Tien minuten later test je opnieuw.

Nu gaat alleen de kleine lamp aan.

Ook dat klopt.

Maar stel dat om 22:35 toch de hoofdverlichting aangaat.

Dan kun je in de trace controleren:

welke tijd Home Assistant gebruikte;
welke voorwaarden van de Choose-takken werden gecontroleerd;
welke tak uiteindelijk werd gekozen.

Je hoeft dan niet te raden waar de fout zit.

Wachten wordt ook zichtbaar

Traces worden nog nuttiger zodra je automatisering wachttijden bevat.

Stel dat de verlichting in De Werkplaats na tien minuten zonder beweging uit moet.

Een uitvoering kan dan ongeveer zo verlopen:

beweging gedetecteerd;
verlichting ingeschakeld;
wachten;
geen beweging meer;
tien minuten voorbij;
verlichting uitschakelen.

Wanneer de lamp onverwacht blijft branden, wil je weten waar die uitvoering gebleven is.

De trace kan bijvoorbeeld laten zien dat Home Assistant nog steeds aan het wachten is.

Dan weet je dat de automatisering niet is vastgelopen.

Ze bevindt zich gewoon nog in een wachtstap.

En opnieuw starten?

Eerder hebben we besproken wat er gebeurt wanneer een automatisering opnieuw wordt gestart terwijl een eerdere uitvoering nog bezig is.

Dat gedrag hangt samen met de gebruikte uitvoeringsmodus.

Juist bij automatiseringen met:

wachttijden;
vertragingen;
herhalingen;
of meerdere snelle triggers

kan dat veel verschil maken.

Een trace helpt je zien welke uitvoering heeft plaatsgevonden en hoever die kwam.

Daardoor wordt een abstract begrip als de uitvoeringsmodus veel concreter.

Kijk naar één uitvoering tegelijk

Een belangrijke gewoonte bij traces is:

onderzoek één specifieke uitvoering.

Niet:

Soms doet hij raar.

Maar:

Om 20:14 liep ik De Werkplaats binnen. De lamp ging niet aan. Ik open precies die uitvoering.

Dat maakt het probleem afgebakend.

Je weet:

wanneer het gebeurde;
wat jij deed;
wat je verwachtte;
en welke trace daarbij hoort.

Dat is veel betrouwbaarder dan achteraf proberen te herinneren wat er ongeveer gebeurde.

Noteer eerst je verwachting

Voordat je een trace opent, helpt het om heel kort op te schrijven wat je verwachtte.

Bijvoorbeeld:

Beweging om 20:14. Lux is 230. De werkplaatslamp moet aangaan.

Daarna kijk je naar de trace.

Vergelijk stap voor stap.

Trigger

Verwacht: beweging activeert automatisering.
Waargenomen: ja.

Voorwaarde

Verwacht: 230 < 400.
Waargenomen: ja.

Actie

Verwacht: lamp wordt ingeschakeld.
Waargenomen: actie uitgevoerd.

Maar de lamp brandt niet.

Nu weet je iets belangrijks.

De logica van de automatisering lijkt goed te zijn doorlopen.

Het probleem zit waarschijnlijk niet meer in de trigger of de voorwaarde.

Een uitgevoerde actie betekent niet altijd dat het apparaat deed wat je verwachtte

Dit is een belangrijk onderscheid.

Een trace kan laten zien dat Home Assistant de opdracht heeft uitgevoerd om een lamp in te schakelen.

Maar daarna kan er nog iets misgaan.

Bijvoorbeeld:

het apparaat is niet bereikbaar;
de integratie heeft een probleem;
de lamp heeft geen voeding;
de entiteit verwijst naar een ander apparaat dan je dacht;
of de toestand is kort daarna door iets anders veranderd.

De trace vertelt je dus veel over de automatisering zelf.

Maar niet ieder probleem in je slimme huis ontstaat binnen die automatisering.

Ook dat is nuttige informatie.

Je weet dan waar je verder moet zoeken.

Let op de waarden op het moment van uitvoeren

Een veelgemaakte denkfout is dat je kijkt naar de huidige waarde van een sensor en daarmee probeert te verklaren wat eerder gebeurde.

Stel dat je om 20:14 de Werkplaats binnenliep.

De automatisering deed niets.

Om 20:20 kijk je naar de lichtsensor.

Die staat nu op 320 lux.

Je denkt:

Dat is lager dan 400. De voorwaarde had dus waar moeten zijn.

Maar misschien was de waarde om 20:14 nog 430 lux.

Een trace helpt je juist terug te kijken naar de omstandigheden tijdens die uitvoering.

Dat is veel betrouwbaarder dan redeneren vanuit de huidige toestand.

Traces en templates

Bij templates wordt dit nog belangrijker.

Een template kan bijvoorbeeld berekenen:

of het werkelijk donker genoeg is;
hoeveel minuten iets actief is;
of meerdere sensoren samen aan een bepaalde toestand voldoen.

Wanneer een template niet oplevert wat jij verwacht, kan de trace helpen om de uitvoering te volgen.

Je ziet dan beter op welk punt de logica afwijkt.

Dat betekent niet dat een ingewikkelde template ineens vanzelfsprekend wordt.

Maar je weet tenminste waar je moet kijken.

Geef onderdelen duidelijke namen

Wanneer een automatisering langer wordt, kan een trace behoorlijk veel stappen bevatten.

Daarom helpt het om onderdelen duidelijke beschrijvingen of namen te geven waar Home Assistant dat toestaat.

Vergelijk:

Numerieke toestandsvoorwaarde

met:

Alleen doorgaan onder 400 lux

Of:

Keuze 1

met:

Overdag — hoofdverlichting

Duidelijke namen maken niet alleen de editor leesbaarder.

Ze maken ook traces begrijpelijker.

Je helpt daarmee je toekomstige zelf.

Gebruik traces niet pas wanneer alles ingewikkeld is

Het is verleidelijk om te denken:

Traces heb ik pas nodig wanneer ik heel ingewikkelde automatiseringen ga maken.

Maar juist bij eenvoudige automatiseringen leer je het systeem het makkelijkst kennen.

Open daarom ook eens een trace van een automatisering die gewoon goed werkt.

Volg de route.

Vraag jezelf af:

Waar begon de uitvoering?
Welke voorwaarde werd gecontroleerd?
Welke waarde gebruikte Home Assistant?
Welke actie volgde daarna?
Waar eindigde de uitvoering?

Wanneer je dat bij een werkende automatisering begrijpt, herken je afwijkingen later veel sneller.

Een kleine oefening

Gebruik een eenvoudige automatisering in De Werkplaats.

Bij voorkeur één met:

één trigger;
één voorwaarde;
één actie.

Bijvoorbeeld de bewegingsgestuurde verlichting.

Voer daarna twee tests uit.

Test 1 — voorwaarde niet waar

Zorg dat het lichtniveau boven de ingestelde grens ligt.

Voorspel:

De automatisering start wel, maar de lamp blijft uit.

Activeer de bewegingssensor.

Open de trace.

Controleer waar de uitvoering stopt.

Test 2 — voorwaarde wel waar

Zorg dat het lichtniveau onder de ingestelde grens ligt.

Voorspel:

De automatisering start en de lamp gaat aan.

Activeer opnieuw de bewegingssensor.

Open ook deze trace.

Vergelijk beide uitvoeringen.

Juist doordat maar één omstandigheid anders is, kun je goed zien welk effect die voorwaarde heeft.

De trace als verhaal

Je kunt een trace uiteindelijk lezen als een klein verhaal:

Er kwam beweging binnen.
Daardoor startte de automatisering.
Home Assistant controleerde het lichtniveau.
Dat was 180 lux.
De grens was 400 lux.
De voorwaarde was dus waar.
Daarna werd de opdracht gegeven om de lamp in te schakelen.

Of:

Er kwam beweging binnen.
De automatisering startte.
Het lichtniveau was 730 lux.
De voorwaarde was niet waar.
Daarom stopte de automatisering daar.

Als je dat verhaal kunt navertellen, begrijp je de automatisering.

En dat is uiteindelijk belangrijker dan alleen weten waar je moet klikken.

Niet meteen repareren

Wanneer je in een trace iets onverwachts ziet, probeer dan niet direct drie instellingen tegelijk aan te passen.

Stel eerst vast wat je hebt geleerd.

Bijvoorbeeld:

De trigger werkt.

De verkeerde Choose-tak wordt genomen.

De voorwaarde krijgt een andere waarde dan ik verwachtte.

De actie wordt wel bereikt.

Pas daarna verander je één onderdeel.

Voer vervolgens dezelfde test opnieuw uit.

Dan weet je of jouw wijziging werkelijk het verschil heeft gemaakt.

Traces maken fouten kleiner

Dat klinkt misschien vreemd.

Een trace voorkomt een fout niet.

Maar een trace maakt een probleem vaak kleiner.

Zonder trace is de vraag:

Waarom werkt mijn automatisering niet?

Met een trace wordt de vraag bijvoorbeeld:

Waarom is deze luxvoorwaarde om 20:14 onwaar geworden?

Dat tweede probleem is veel makkelijker te onderzoeken.

En precies dat is systematisch foutzoeken:

een groot, vaag probleem steeds verder verkleinen totdat je nog maar één concreet onderdeel hoeft te onderzoeken.

Niet iedere onverwachte uitkomst is een technische fout

Je zult tijdens het bekijken van traces iets belangrijks ontdekken.

Veel automatiseringen die volgens ons gevoel "fout" gaan, bevatten helemaal geen technische storing.

De automatisering kan precies uitvoeren wat je hebt ingesteld.

Het probleem zit dan bijvoorbeeld in:

een verkeerde grenswaarde;
een verkeerd gekozen entiteit;
een voorwaarde waar je niet meer aan had gedacht;
een tijdsvenster dat net anders loopt;
een Choose-tak die eerder wordt gekozen dan bedoeld;
of een uitvoeringsmodus die niet past bij het gewenste gedrag.

Dat zijn geen spectaculaire storingen.

Maar juist dit soort fouten kom je in de praktijk vaak tegen.

Wat je uit dit hoofdstuk moet meenemen

Een trace laat je terugkijken naar één concrete uitvoering van een automatisering.

Daarmee kun je zien:

waardoor de automatisering startte;
welke voorwaarden werden beoordeeld;
welke route werd gevolgd;
welke acties werden bereikt;
waar werd gewacht;
en waar de uitvoering stopte.

Gebruik traces niet alleen wanneer iets fout lijkt te gaan.

Bekijk ook werkende automatiseringen.

Voorspel eerst wat Home Assistant volgens jou moet doen.

Voer daarna een duidelijke test uit.

Open vervolgens de trace en vergelijk verwachting en werkelijkheid stap voor stap.

Wanneer je dat doet, verandert foutzoeken van gokken in onderzoeken.

En dat hebben we nodig voor het volgende hoofdstuk.

Want hoewel automatiseringen op heel veel manieren kunnen worden opgebouwd, blijken dezelfde problemen steeds opnieuw terug te komen.

In “De meest voorkomende fouten bij automatiseringen” bekijken we welke fouten je waarschijnlijk vroeg of laat tegenkomt — en vooral hoe je ze aan de hand van wat je inmiddels weet snel kunt herkennen.