> 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-pt/kilo-iot-server/rules-engine/debugging-rules.md).
# Depurar Regras
Depure uma regra de automação do Kilo IoT antes da implementação — nós de etapa, variáveis de observação, verifique expressões no contexto de teste.
Uma regra que parece correta no canvas ainda pode comportar-se de formas inesperadas — uma gateway envia o fluxo para o ramo errado, uma expressão é avaliada contra uma estrutura de dados que não antecipou, uma variável contém algo diferente do que assumiu. O modo de depuração permite-lhe descobrir isso *antes* de a regra ser implementada em produção, ao executá-la passo a passo e inspecionar exatamente o que acontece em cada nó.
O modo de depuração é um depurador interativo integrado no editor visual. Fornece à regra um payload de teste e depois percorre a sua execução um nó de cada vez — fazendo pausas onde quiser, observando as variáveis a mudar, verificando expressões e decidindo como cada efeito secundário é tratado. É a diferença entre implementar uma regra e *esperar*, e implementar uma regra que realmente já viu correr.
## Iniciar uma sessão de depuração
1. Abra a regra no [editor visual](/kilo-docs-pt/kilo-iot-server/rules-engine/visual-editor.md).
2. Na barra superior do editor de regras, clique em **Definir contexto** para abrir o separador **Iniciar sessão de depuração** painel. (A barra superior também inclui um **Iniciar depuração** botão, atalho **F12**.)
3. O painel pede-lhe para **fornecer variáveis de contexto iniciais** — a entrada com que a regra irá ser executada. Abre com uma linha já adicionada, chamada `valor`, e cada linha é uma **Nome** e um **Valor**:
* **Nome** é o nome da variável que a sua regra espera (por exemplo `valor`, `temperatura`, `estado`).
* **Valor** é a leitura de teste. Pode ser um número, `verdadeiro` / `falso`, `nulo`, texto ou JSON — o painel interpreta-o por si.
4. Clique em **Adicionar métrica** para adicionar mais variáveis de contexto; remova qualquer linha extra de que não precise.
5. Clique em **Carregar e iniciar**. A regra é carregada e fica em pausa, pronta para o primeiro passo.
O contexto inicial substitui o que um dispositivo enviaria em produção. Defina-o com os valores que pretende testar — o caso extremo, o limiar, a leitura que suspeita estar a causar problemas.
### Nomeie cada variável exatamente como a sua regra se refere a ela
As regras leem o contexto através de `vars`, por isso dê a cada linha um nome que corresponda às expressões na sua regra. Uma condição de gateway escrita `vars.RH > 70` precisa de uma linha chamada **`RH`** — `humidade` ou `valor` não serve. Se uma condição referir um nome que o contexto não contém, a regra pára nesse elemento quando lá chegar.
Copie os nomes das suas condições de gateway em vez de os digitar de memória e verifique a ortografia antes de começar.
Duas linhas que não precisa de adicionar:
* O painel abre com uma linha chamada `valor`valor **, que se adapta a regras iniciadas por**. Uma regra de produção iniciada por **Condição de acionamento** não recebe `vars.value`, por isso remova ou renomeie este valor de teste para corresponder ao contexto do acionamento.
* O depurador fornece `sensor_id` automaticamente. Em produção, vem do sensor selecionado ou do sinal de acionamento, dependendo da origem de início.
## A sessão começa em pausa
Carregar uma sessão não executa a regra. Abre o diagrama, coloca a execução no Evento de Início e espera por si — **nada é executado até premir Executar ou um dos controlos de Passo**.
Quando a sessão é carregada, verá o canvas tornar-se só de leitura, a barra de depuração aparecer na parte inferior do editor, o painel de depuração abrir-se à direita com as suas variáveis iniciais e um contorno azul no Evento de Início. O contorno azul mostra que a sessão está ativa e à espera.
Se o diagrama parecer ficar parado, prima **Executar (F10)** para continuar até ao primeiro ponto de interrupção ou até ao fim, ou **Passar por cima (F9)** para avançar um elemento de cada vez.
## Os controlos de depuração
Uma vez carregada uma sessão, uma barra de depuração flutua sobre a parte inferior do canvas com cinco controlos. Não fica na barra superior, junto a Guardar e Compilar — procure na parte inferior do diagrama.
* **Executar (F10)** — executa a regra até atingir um ponto de interrupção ou terminar.
* **Passar por cima (F9)** — executa o próximo nó e pára, mostrando o respetivo resultado.
* **Entrar (F8)** — entra no próximo nó e inspeciona os seus internos — as entradas, scripts e saídas — em vez de apenas o resultado.
* **Executar ignorando pontos de interrupção (F11)** — executa até ao fim sem pausar. Desliga todos os pontos de interrupção e mantém-nos desligados pelo resto da sessão; volte a ativá-los no separador Pontos de interrupção quando precisar deles novamente.
* **Parar (F12)** — termina a sessão de depuração.
**F12 funciona em ambas as extremidades de uma sessão:** prima-o enquanto estiver a editar para iniciar a depuração e, novamente, enquanto estiver a depurar para parar.
Os controlos de passo estão disponíveis enquanto a sessão está em pausa. Ficam desativados enquanto a regra está a correr, enquanto uma caixa de diálogo de Efeito Secundário aguarda resposta e depois de uma regra falhar ao carregar. Parar permanece disponível durante todo o tempo.
## O que significam os marcadores no canvas
Os elementos podem apresentar três marcas diferentes durante uma sessão:
| Marcador | Significado |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Contorno azul** | Onde a execução se encontra agora. O próximo passo executa-se aqui. |
| **Pequeno ponto vermelho** acima do elemento | Um ponto de interrupção. Um ponto preenchido está ativo; um anel vazio é um que desativou. |
| **Contorno vermelho** | O elemento que gerou o erro mais recente. É limpo no passo seguinte bem-sucedido. |
Um contorno vermelho não é nem um ponto de interrupção nem a posição atual — marca o elemento que falhou, e a expressão nesse elemento é onde deve olhar. Consulte [Quando um nó falha](#when-a-node-fails).
## Pontos de interrupção
Um ponto de interrupção pausa a execução num nó específico, para que possa inspecionar o estado exatamente no ponto que lhe interessa.
* **Definir um ponto de interrupção** — clique num nó no canvas para alternar um ponto de interrupção nele. Abra o separador **Pontos de interrupção** no painel de depuração para ver todos; o cabeçalho do separador mostra uma contagem. Durante uma sessão, cada clique no canvas adiciona ou remove um ponto de interrupção, por isso clique novamente num elemento para limpar um que não pretendia.
* **Ativar ou desativar** — cada ponto de interrupção tem um indicador vermelho. Clique nele para desativar o ponto de interrupção sem o remover e volte a ativá-lo mais tarde.
* **Pontos de interrupção condicionais** — crie primeiro um ponto de interrupção simples e depois clique em **Definir condição** nele e introduza uma expressão CEL. O ponto de interrupção então pausa a execução *apenas* quando essa expressão é verdadeira — por exemplo, apenas quando `vars.value > 30`. Um ponto de interrupção condicional é assinalado com um distintivo **Condicional** . Consulte [Referência CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) para a sintaxe das expressões.
Os pontos de interrupção condicionais são a forma de depurar um problema intermitente: deixe a regra correr normalmente e pare-a apenas na leitura que provoca o comportamento incorreto.
## Inspecionar variáveis
A **Aba** da variável no painel de depuração mostra o estado da regra no passo atual, em duas secções:
* **Alterações** — as variáveis que foram adicionadas ou alteradas desde o último passo, destacadas para que veja de relance o que o nó que acabou de executar realmente fez. As variáveis eliminadas são mostradas riscadas.
* **Todas as variáveis** — o conjunto completo atual de variáveis com os respetivos valores.
Enquanto está em pausa, também pode **editar** o estado diretamente: alterar o valor de uma variável, adicionar uma nova variável ou eliminar uma. Isto permite-lhe levar a regra para um ramo que quer testar sem ter de reiniciar a sessão com entrada diferente.
Quando usa **Entrar** num nó, o separador Variável também mostra um cartão de detalhe do elemento com o **Entradas**, **Scripts**, e **Saídas** — o funcionamento interno do passo, não apenas o resultado final.
## Expressões de observação e Avaliar
A **Observação** separador mantém debaixo de olho expressões enquanto a regra é executada:
* **Adicionar observação** — introduza uma expressão CEL e ela é reavaliada automaticamente em cada passo, para que possa acompanhar um valor derivado (por exemplo, `vars.value - vars.threshold`) sem vasculhar a lista de variáveis.
* **Avaliar** — introduza uma expressão CEL pontual e avalie-a imediatamente em relação ao estado atual. Útil para verificar uma parte da lógica — "o que devolveria este condição de gateway neste momento?" — sem a adicionar à regra.
Ambos usam o mesmo [CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) que escreve noutro ponto da regra, e ambos leem o estado da regra através de `vars` — uma observação sobre uma variável chamada `RH` é escrita `vars.RH`. Uma expressão que não compile é rejeitada ao adicioná-la, por isso use o separador Observação para experimentar uma condição antes de a colar numa gateway.
## Efeitos secundários
Alguns nós fazem mais do que transformar dados — enviam notificações, acionam alarmes ou contactam outros sistemas. Quando a execução de depuração chega a um nó com um efeito secundário, aparece uma caixa de diálogo de **Efeito Secundário** e pergunta como o tratar. Três opções:
* **Executar — executar o manipulador real.** O efeito secundário acontece de facto, exatamente como aconteceria numa regra implementada em produção: é acionado um alarme e os respetivos destinatários são notificados, e é enviado um comando para o dispositivo físico.
* **Saltar — variáveis inalteradas.** O efeito secundário é ignorado e as variáveis da regra ficam como estão.
* **Simular — fornecer uma resposta simulada.** Fornece uma resposta substituta em JSON e a regra continua como se o manipulador a tivesse devolvido. A resposta tem de ser JSON válido — se não for, a simulação simplesmente não é aplicada.
**Executar é selecionado quando a caixa de diálogo se abre**, por isso altere a seleção antes de clicar em Aplicar se não quiser que a ação aconteça de facto. É isto que lhe permite depurar uma regra que envia alertas sem realmente contactar um engenheiro de plantão: escolha **Saltar** ou **Simular** enquanto está a testar a lógica, e **Executar** apenas quando quiser especificamente verificar a entrega real.
Duas coisas a esperar depois de responder:
* **A sua resposta é reutilizada para esse nó.** Se a execução voltar mais tarde na sessão ao mesmo nó, a caixa de diálogo não reaparece e a sua escolha anterior é aplicada. Escolher **Executar** portanto envia de facto em cada passagem seguinte também. Inicie uma nova sessão para ser questionado novamente.
* **Cancelar repõe a execução.** Fechar a caixa de diálogo sem escolher faz a execução voltar para imediatamente antes do nó e deixa-o por executar. Faça mais um passo e a caixa de diálogo reaparece.
## Quando um nó falha
Se um nó gerar um erro durante a execução, o nó que falhou é contornado a vermelho no canvas, para que possa ver exatamente qual nó correu mal sem ter de procurar numa regra grande. Um **recuperável** erro mantém a sessão de depuração em pausa e carregada — pode inspecionar as variáveis, ajustar o estado e continuar — enquanto um **irrecuperável** erro termina a sessão.
A maioria dos erros vem de uma expressão no nó que falhou. Abra as respetivas propriedades e verifique três coisas:
1. **Cada nome que usa existe no separador Variáveis.** `vars.RH > 70` falha se nada chamado `RH` foi definido como contexto inicial ou produzido por um nó anterior. Num gateway, isto pára a regra no gateway — não a envia para o ramo predefinido.
2. **A `vars.` prefixo está lá.** `RH > 70` não é o mesmo que `vars.RH > 70`.
3. **A expressão devolve o tipo correto.** Uma condição de gateway tem de produzir `verdadeiro` ou `falso`.
Cole a expressão em **Avaliar** no separador Observação para a experimentar em relação ao estado atual.
## Ciclo de vida da sessão
Uma sessão de depuração decorre durante **30 minutos**, contados a partir do momento em que começa — percorrer a regra passo a passo não prolonga esse tempo. Verá um aviso pouco antes de expirar, e uma notificação se terminar por tempo, se fechar (com o motivo) ou se perder a ligação. Inicie uma nova sessão para continuar a depurar.
Os pontos de interrupção estão ligados aos elementos do diagrama que carregou, por isso recarregar o editor pode eliminá-los. Uma notificação indica-lhe quantos, para que os possa voltar a adicionar.
Se iniciar uma sessão falhar, a plataforma está nesse momento a executar o número máximo de sessões de depuração. Tente novamente daqui a pouco.
## Sugestões
* Depure os casos extremos, não o caminho feliz — defina o contexto inicial para o valor de limiar, o campo em falta, a leitura fora do intervalo.
* Copie os nomes das variáveis das suas condições de gateway ao preencher o contexto inicial, em vez de os escrever de memória.
* Use um ponto de interrupção condicional para apanhar um problema intermitente: execute a regra normalmente e pare apenas na leitura que o desencadeia.
* Edite uma variável a meio da sessão para forçar a regra para um ramo específico em vez de reiniciar com nova entrada.
* Mantenha os efeitos secundários ativados **Saltar** ou **Simular** enquanto vai iterando na lógica; mude para **Executar** apenas para uma verificação intencional de ponta a ponta.
* Quando uma regra depura sem problemas, compile-a e implemente-a — veja [Compilações e implementação](/kilo-docs-pt/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md).
## Ver também
* [Editor visual](/kilo-docs-pt/kilo-iot-server/rules-engine/visual-editor.md) — o modo de depuração do canvas funciona em
* [Referência CEL](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) — sintaxe de expressões para pontos de interrupção condicionais e observações
* [Compilações e implementação](/kilo-docs-pt/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md) — lance uma regra depois de ela depurar sem problemas
* [Resolução de problemas](/kilo-docs-pt/kilo-iot-server/rules-engine/troubleshooting.md) — erros de compilação e problemas de execução
---
# 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-pt/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.
