> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/rules-engine/debugging-rules.md).
# Debugging von Regeln
Debuggen Sie eine Kilo IoT-Automatisierungsregel vor dem Deploy — Schrittknoten, Variablen beobachten, Ausdrücke gegen den Testkontext prüfen.
Eine Regel, die auf der Arbeitsfläche korrekt aussieht, kann sich dennoch anders verhalten als erwartet — ein Gateway leitet den Ablauf in den falschen Zweig, ein Ausdruck wird gegen eine Datenstruktur ausgewertet, mit der Sie nicht gerechnet haben, eine Variable enthält etwas anderes als angenommen. Der Debug-Modus hilft Ihnen, das herauszufinden *bevor* die Regel in der Produktion bereitgestellt wird, indem die Regel Schritt für Schritt ausgeführt und genau untersucht wird, was an jedem Knoten passiert.
Der Debug-Modus ist ein interaktiver Debugger, der in den visuellen Editor integriert ist. Sie geben der Regel eine Test-Nutzlast, dann gehen Sie ihre Ausführung Knoten für Knoten durch — pausieren, wo Sie möchten, beobachten, wie sich Variablen ändern, prüfen Ausdrücke und entscheiden, wie jeder Seiteneffekt behandelt wird. Das ist der Unterschied zwischen dem Bereitstellen einer Regel und *hoffen*, und einer Regel, der Sie tatsächlich beim Ausführen zugesehen haben.
## Eine Debug-Sitzung starten
1. Öffnen Sie die Regel im [visuellen Editor](/kilo-docs-de/kilo-iot-server/rules-engine/visual-editor.md).
2. Klicken Sie in der oberen Leiste des Regel-Editors auf **Kontext festlegen** um die **Debug-Sitzung starten** Bereich. (Die obere Leiste enthält außerdem eine **Debug starten** Schaltfläche, Tastenkürzel **F12**.)
3. Der Bereich fordert Sie auf, **anfängliche Kontextvariablen bereitzustellen** — die Eingabe, gegen die die Regel ausgeführt wird. Es öffnet sich mit einer bereits hinzugefügten Zeile namens `value`, und jede Zeile ist ein **Name** und ein **Wert**:
* **Name** ist der Variablenname, den Ihre Regel erwartet (zum Beispiel `value`, `temperature`, `status`).
* **Wert** ist der Testwert. Er kann eine Zahl sein, `wahr` / `falsch`, `null`, Text oder JSON — der Bereich interpretiert das für Sie.
4. Klicken Sie auf **Messwert hinzufügen** um weitere Kontextvariablen hinzuzufügen; entfernen Sie jede überflüssige Zeile, die Sie nicht benötigen.
5. Klicken Sie auf **Laden und starten**. Die Regel wird geladen und pausiert, bereit für den ersten Schritt.
Der anfängliche Kontext steht für das, was ein Gerät in der Produktion senden würde. Setzen Sie ihn auf die Werte, die Sie testen möchten — den Grenzfall, den Schwellwert, den Messwert, den Sie als Ursache für Probleme vermuten.
### Benennen Sie jede Variable genau so, wie Ihre Regel darauf verweist
Regeln lesen den Kontext über `vars`, daher benennen Sie jede Zeile so, dass sie zu den Ausdrücken in Ihrer Regel passt. Eine Gateway-Bedingung wie `vars.RH > 70` benötigt eine Zeile mit dem Namen **`RH`** — `humidity` oder `value` reicht nicht. Wenn eine Bedingung auf einen Namen verweist, den der Kontext nicht enthält, bleibt die Regel an diesem Element stehen, sobald Sie dorthin gelangen.
Kopieren Sie die Namen aus Ihren Gateway-Bedingungen, statt sie aus dem Gedächtnis einzugeben, und prüfen Sie die Schreibweise, bevor Sie beginnen.
Zwei Zeilen, die Sie nicht hinzufügen müssen:
* Der Bereich öffnet sich mit einer Zeile namens `value`, was zu Regeln passt, die gestartet werden durch **Sensorwert**. Eine Produktionsregel, die gestartet wird durch **Triggerbedingung** erhält nicht `vars.value`, entfernen Sie also diesen Testwert oder benennen Sie ihn um, damit er zum Trigger-Kontext passt.
* Der Debugger stellt `sensor_id` automatisch bereit. In der Produktion stammt er vom ausgewählten Sensor oder Trigger-Signal, je nach Startquelle.
## Die Sitzung startet pausiert
Das Laden einer Sitzung führt die Regel nicht aus. Das Diagramm wird geöffnet, die Ausführung am Startereignis platziert, und es wartet auf Sie — **nichts wird ausgeführt, bis Sie auf Ausführen oder eine der Schritt-Steuerungen drücken**.
Wenn die Sitzung geladen ist, sehen Sie, wie die Arbeitsfläche schreibgeschützt wird, die Debug-Symbolleiste unten im Editor erscheint, der Debug-Bereich rechts mit Ihren Anfangsvariablen geöffnet wird und das Start-Ereignis blau umrandet ist. Die blaue Umrandung zeigt, dass die Sitzung aktiv ist und wartet.
Wenn das Diagramm stillzustehen scheint, drücken Sie **Ausführen (F10)** um bis zum ersten Haltepunkt oder bis zum Ende fortzufahren, oder **Überspringen (F9)** um jeweils ein Element weiterzugehen.
## Die Debug-Steuerung
Sobald eine Sitzung geladen ist, schwebt unten auf der Arbeitsfläche eine Debug-Symbolleiste mit fünf Steuerelementen. Sie befindet sich nicht in der Kopfzeile neben Speichern und Erstellen — schauen Sie unten im Diagramm nach.
* **Ausführen (F10)** — führt die Regel aus, bis sie einen Haltepunkt erreicht oder beendet ist.
* **Überspringen (F9)** — führt den nächsten Knoten aus und stoppt, wobei sein Ergebnis angezeigt wird.
* **Hineinspringen (F8)** — springt in den nächsten Knoten hinein und untersucht seine Interna — seine Eingaben, Skripte und Ausgaben — statt nur sein Ergebnis.
* **Ohne Haltepunkte ausführen (F11)** — bis zum Ende ohne Pausieren ausführen. Dabei werden alle Haltepunkte ausgeschaltet und für den Rest der Sitzung ausgeschaltet gelassen; aktivieren Sie sie bei Bedarf erneut über die Registerkarte Haltepunkte.
* **Stopp (F12)** — die Debug-Sitzung beenden.
**F12 funktioniert an beiden Enden einer Sitzung:** Drücken Sie es beim Bearbeiten, um das Debugging zu starten, und erneut während des Debuggings, um zu stoppen.
Die Schritt-Steuerungen sind verfügbar, solange die Sitzung pausiert ist. Während die Regel ausgeführt wird, während ein Dialog für einen Seiteneffekt auf eine Antwort wartet und nachdem das Laden einer Regel fehlgeschlagen ist, sind sie ausgegraut. Stopp bleibt durchgehend verfügbar.
## Was die Markierungen auf der Arbeitsfläche bedeuten
Elemente können während einer Sitzung drei verschiedene Markierungen tragen:
| Markierung | Bedeutung |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Blaue Umrandung** | Hier befindet sich die Ausführung gerade. Der nächste Schritt wird hier ausgeführt. |
| **Kleiner roter Punkt** über dem Element | Ein Haltepunkt. Ein gefüllter Punkt ist aktiviert; ein hohler Ring ist einer, den Sie ausgeschaltet haben. |
| **Rote Umrandung** | Das Element, das den zuletzt aufgetretenen Fehler ausgelöst hat. Sie verschwindet beim nächsten erfolgreichen Schritt. |
Eine rote Umrandung ist weder ein Haltepunkt noch die aktuelle Position — sie markiert das fehlgeschlagene Element, und der Ausdruck an diesem Element ist die Stelle, die Sie prüfen sollten. Siehe [Wenn ein Knoten fehlschlägt](#when-a-node-fails).
## Haltepunkte
Ein Haltepunkt pausiert die Ausführung an einem bestimmten Knoten, sodass Sie den Zustand genau an der Stelle prüfen können, die Sie interessiert.
* **Einen Haltepunkt setzen** — klicken Sie auf einen Knoten auf der Arbeitsfläche, um dort einen Haltepunkt ein- oder auszuschalten. Öffnen Sie den **Haltepunkte** Registerkarte im Debug-Bereich, um alle zu sehen; die Registerkartenüberschrift zeigt eine Anzahl an. Während einer Sitzung fügt jeder Klick auf der Arbeitsfläche einen Haltepunkt hinzu oder entfernt ihn wieder, klicken Sie also ein Element erneut an, um einen unbeabsichtigten Haltepunkt zu löschen.
* **Aktivieren oder deaktivieren** — jeder Haltepunkt hat einen roten Anzeigepunkt. Klicken Sie darauf, um den Haltepunkt auszuschalten, ohne ihn zu entfernen, und später wieder einzuschalten.
* **Bedingte Haltepunkte** — erstellen Sie zunächst einen normalen Haltepunkt und klicken Sie dann auf **Bedingung festlegen** und geben Sie einen CEL-Ausdruck ein. Der Haltepunkt pausiert die Ausführung dann *nur* wenn dieser Ausdruck wahr ist — zum Beispiel nur, wenn `vars.value > 30`. Ein bedingter Haltepunkt ist mit einem **Bedingt** Abzeichen markiert. Siehe [CEL-Referenz](/kilo-docs-de/kilo-iot-server/rules-engine/cel-reference.md) für die Ausdruckssyntax.
Mit bedingten Haltepunkten debuggen Sie ein sporadisch auftretendes Problem: Lassen Sie die Regel normal laufen und stoppen Sie sie nur bei dem Messwert, der das Fehlverhalten auslöst.
## Variablen untersuchen
Die **Variable** Registerkarte im Debug-Bereich zeigt den Zustand der Regel im aktuellen Schritt in zwei Abschnitten:
* **Änderungen** — die Variablen, die seit dem letzten Schritt hinzugefügt oder geändert wurden, hervorgehoben, damit Sie auf einen Blick sehen können, was der gerade ausgeführte Knoten tatsächlich getan hat. Gelöschte Variablen werden durchgestrichen angezeigt.
* **Alle Variablen** — der vollständige aktuelle Variablensatz mit ihren Werten.
Während der Pause können Sie auch **bearbeiten** den Zustand direkt: den Wert einer Variable ändern, eine neue Variable hinzufügen oder eine löschen. So können Sie die Regel in einen Zweig lenken, den Sie testen möchten, ohne die Sitzung mit anderen Eingaben neu starten zu müssen.
Wenn Sie **Hineinspringen** an einem Knoten verwenden, zeigt die Registerkarte Variable auch eine Detailkarte für das Element mit den **Eingaben**, **Skripten**, und **Ausgaben** — die internen Abläufe des Schritts, nicht nur sein Endergebnis.
## Ausdrücke beobachten und auswerten
Die **Beobachten** Registerkarte beobachtet Ausdrücke, während die Regel läuft:
* **Beobachtung hinzufügen** — geben Sie einen CEL-Ausdruck ein, und er wird bei jedem Schritt automatisch neu ausgewertet, sodass Sie einen abgeleiteten Wert verfolgen können (z. B. `vars.value - vars.threshold`) ohne die Variablenliste durchsuchen zu müssen.
* **Auswerten** — geben Sie einen einmaligen CEL-Ausdruck ein und werten Sie ihn sofort gegen den aktuellen Zustand aus. Nützlich, um einen Logikbaustein zu prüfen — „was würde diese Gateway-Bedingung jetzt zurückgeben?“ — ohne ihn zur Regel hinzuzufügen.
Beide verwenden dieselbe [CEL](/kilo-docs-de/kilo-iot-server/rules-engine/cel-reference.md) die Sie an anderer Stelle in der Regel schreiben, und beide lesen den Zustand der Regel über `vars` — eine Beobachtung einer Variable namens `RH` wird geschrieben `vars.RH`. Ein Ausdruck, der nicht kompiliert werden kann, wird bereits beim Hinzufügen abgewiesen, also verwenden Sie die Registerkarte Beobachten, um eine Bedingung auszuprobieren, bevor Sie sie in ein Gateway einfügen.
## Seiteneffekte
Einige Knoten tun mehr, als nur Daten zu transformieren — sie senden Benachrichtigungen, lösen Alarme aus oder rufen andere Systeme auf. Wenn die Debug-Ausführung einen Knoten mit einem Seiteneffekt erreicht, erscheint ein **Seiteneffekt** Dialog und fragt, wie damit verfahren werden soll. Drei Optionen:
* **Ausführen — den echten Handler ausführen.** Der Seiteneffekt geschieht tatsächlich, genau so, wie er in einer bereitgestellten Regel passieren würde: Ein Alarm wird ausgelöst und seine Empfänger werden benachrichtigt, und ein Befehl wird an das physische Gerät gesendet.
* **Überspringen — Variablen unverändert.** Der Seiteneffekt wird übersprungen und die Variablen der Regel bleiben unverändert.
* **Mock — eine Platzhalter-Antwort bereitstellen.** Sie liefern eine Ersatzantwort als JSON, und die Regel wird so fortgesetzt, als hätte der Handler sie zurückgegeben. Die Antwort muss gültiges JSON sein — wenn nicht, wird der Mock einfach nicht angewendet.
**Ausführen ist ausgewählt, wenn sich der Dialog öffnet**, ändern Sie die Auswahl also vor dem Klicken auf Anwenden, wenn die Aktion nicht tatsächlich ausgeführt werden soll. So können Sie eine Regel debuggen, die Alarme sendet, ohne tatsächlich einen Bereitschaftsingenieur anzupagen: Wählen Sie **Überspringen** oder **Mock** während Sie die Logik testen, und **Ausführen** nur wenn Sie die echte Zustellung ausdrücklich überprüfen möchten.
Nachdem Sie geantwortet haben, sind zwei Dinge zu erwarten:
* **Ihre Antwort wird für diesen Knoten wiederverwendet.** Wenn die Ausführung später in derselben Sitzung erneut denselben Knoten erreicht, erscheint der Dialog nicht erneut und Ihre frühere Auswahl wird angewendet. Die Auswahl **Ausführen** führt also auch bei jedem späteren Durchlauf tatsächlich aus. Starten Sie eine neue Sitzung, um erneut gefragt zu werden.
* **Durch Abbrechen wird die Ausführung zurückgesetzt.** Wenn Sie den Dialog ohne Auswahl schließen, kehrt die Ausführung auf den Zeitpunkt direkt vor dem Knoten zurück und der Knoten bleibt unausgeführt. Führen Sie den Schritt erneut aus, und der Dialog erscheint wieder.
## Wenn ein Knoten fehlschlägt
Wenn bei der Ausführung eines Knoten ein Fehler auftritt, wird der fehlgeschlagene Knoten auf der Arbeitsfläche rot umrandet, sodass Sie genau sehen können, welcher Knoten schiefgelaufen ist, ohne eine große Regel durchsuchen zu müssen. Ein **behebbarer** Fehler hält die Debug-Sitzung pausiert und geladen — Sie können die Variablen prüfen, den Zustand anpassen und fortfahren — während ein **nicht behebbarer** Fehler die Sitzung beendet.
Die meisten Fehler stammen von einem Ausdruck am fehlgeschlagenen Knoten. Öffnen Sie seine Eigenschaften und prüfen Sie drei Dinge:
1. **Jeder Name, den er verwendet, existiert auf der Registerkarte Variablen.** `vars.RH > 70` schlägt fehl, wenn nichts mit dem Namen `RH` als anfänglicher Kontext gesetzt oder von einem früheren Knoten erzeugt wurde. Bei einem Gateway stoppt das die Regel am Gateway — sie wird nicht über den Standardzweig weitergeleitet.
2. **Die `vars.` Präfix vorhanden ist.** `RH > 70` ist nicht dasselbe wie `vars.RH > 70`.
3. **Der Ausdruck gibt den richtigen Typ zurück.** Eine Gateway-Bedingung muss `wahr` oder `falsch`.
Fügen Sie den Ausdruck in **Auswerten** auf der Registerkarte Beobachten ein, um ihn gegen den aktuellen Zustand zu testen.
## Lebenszyklus der Sitzung
Eine Debug-Sitzung läuft **30 Minuten**, gemessen ab ihrem Start — das schrittweise Durchgehen der Regel verlängert sie nicht. Kurz bevor sie abläuft, sehen Sie eine Warnung, und Sie erhalten eine Benachrichtigung, wenn sie abläuft, geschlossen wird (mit Grund) oder die Verbindung verloren geht. Starten Sie eine neue Sitzung, um weiter zu debuggen.
Haltepunkte sind an die Elemente im geladenen Diagramm gebunden, sodass das erneute Laden des Editors sie entfernen kann. Eine Benachrichtigung teilt Ihnen mit, wie viele es sind, damit Sie sie erneut hinzufügen können.
Wenn das Starten einer Sitzung fehlschlägt, führt die Plattform in diesem Moment bereits die maximale Anzahl an Debug-Sitzungen aus. Versuchen Sie es in Kürze erneut.
## Tipps
* Debuggen Sie die Grenzfälle, nicht den Standardfall — setzen Sie den anfänglichen Kontext auf den Schwellwert, das fehlende Feld, den Messwert außerhalb des Bereichs.
* Kopieren Sie die Variablennamen aus Ihren Gateway-Bedingungen, wenn Sie den anfänglichen Kontext ausfüllen, statt sie aus dem Gedächtnis einzugeben.
* Verwenden Sie einen bedingten Haltepunkt, um ein sporadisches Problem zu erfassen: Lassen Sie die Regel normal laufen und stoppen Sie nur bei dem Messwert, der es auslöst.
* Bearbeiten Sie während der Sitzung eine Variable, um die Regel in einen bestimmten Zweig zu zwingen, statt mit neuen Eingaben neu zu starten.
* Seiteneffekte aktiviert lassen **Überspringen** oder **Mock** während Sie an der Logik arbeiten; wechseln Sie zu **Ausführen** nur für eine gezielte End-to-End-Prüfung.
* Sobald eine Regel sauber debuggt ist, bauen und deployen Sie sie — siehe [Builds und Bereitstellung](/kilo-docs-de/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md).
## Siehe auch
* [Visueller Editor](/kilo-docs-de/kilo-iot-server/rules-engine/visual-editor.md) — Der Debug-Modus der Arbeitsfläche läuft auf
* [CEL-Referenz](/kilo-docs-de/kilo-iot-server/rules-engine/cel-reference.md) — Ausdruckssyntax für bedingte Haltepunkte und Beobachtungen
* [Builds und Bereitstellung](/kilo-docs-de/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md) — Eine Regel ausliefern, sobald sie sauber debuggt
* [Fehlerbehebung](/kilo-docs-de/kilo-iot-server/rules-engine/troubleshooting.md) — Build-Fehler und Laufzeitprobleme
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/rules-engine/debugging-rules.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
