Automações
Rastreio de Automação (Trace)
Na prática, o trace funciona como uma linha do tempo técnica da automação: registra gatilho, condições, variáveis, caminhos e ações de uma execução específica. Em Home Assistant, traces podem mostrar cada etapa e seu resultado; em Node-RED, o diagnóstico depende de mensagens e nós de debug. O recurso reduz o tempo de investigação, mas precisa de retenção, correlação e redaction. Sem timestamps, run_id e contexto, um trace grande vira apenas uma sequência difícil de interpretar.
⚙ Definição Técnica
Rastreio de Automação, ou trace, é o registro estruturado do caminho percorrido por uma instância de automação desde o gatilho até a conclusão, interrupção ou falha. O trace preserva a sequência de etapas, os resultados de condições, os ramos escolhidos, as variáveis relevantes, as ações chamadas, os tempos de início e fim, os erros e o contexto de causalidade. Diferentemente de um log textual genérico, o trace possui estrutura ligada à definição da automação e permite reconstruir por que determinada ação ocorreu ou não. Em Home Assistant, o recurso mostra graficamente caminhos de automações e scripts; em Node-RED, uma combinação de nós Debug, status e IDs de mensagem cumpre papel semelhante; em orquestradores, spans e traces distribuídos usam identificadores correlacionados. O objetivo é reduzir o tempo de diagnóstico e oferecer evidência de execução. A implantação exige política de retenção, tamanho, privacidade, correlação e persistência. Um trace sem dados suficientes não explica; um trace que captura tudo pode vazar segredos e sobrecarregar armazenamento.
Tipos comuns de gatilhos
Trace de execução bem-sucedida
Registra o caminho normal, o gatilho usado, condições verdadeiras, ações concluídas e duração. Mesmo sem erro, é útil para confirmar que a regra executou a versão esperada e medir latência. Uma luz pode acender em 80 ms num dia e 3 s em outro. O trace revela se o atraso veio de espera, serviço ou dispositivo. Para não gerar volume excessivo, a plataforma pode reter apenas as últimas 5, 10 ou 50 execuções por automação, ou amostrar. Em funções críticas, retenção maior pode ser necessária. O trace deve mostrar run_id, trigger_id e timestamps. A ausência de erro não prova efeito físico; ele registra o que o motor observou e o retorno da integração.
Trace de condição que bloqueou o fluxo
Uma automação dispara, mas nenhuma ação ocorre porque presença, horário, iluminância ou modo não atendeu. Sem trace, o usuário percebe apenas “não funcionou”. O registro deve indicar cada condição, valor lido, resultado e instante. Para templates, preserve a expressão e os valores intermediários quando possível. Não basta mostrar false. Um sensor unavailable convertido para zero precisa aparecer. O trace também deve distinguir condição falsa de erro de renderização. Se múltiplas condições usam curto-circuito, as posteriores podem não ser avaliadas. Isso precisa ficar claro. O benefício é ajustar a lógica com evidência, evitando mudar limites aleatoriamente.
Trace de falha em ação externa
A execução alcança uma API, dispositivo ou serviço e recebe timeout, HTTP 429, 500, desconexão ou erro de autenticação. O trace registra a etapa, duração, classe do erro e tentativa. Dados sensíveis devem ser removidos. A mensagem precisa ser suficiente para decidir se a falha é temporária ou permanente. Um erro 401 sugere credencial; 429, limite; timeout, indisponibilidade ou rede. Em ações físicas, o estado final pode ser desconhecido. O trace deve marcar “resultado indeterminado” e não apenas failed. Se houve retentativa, mostre cada tentativa e intervalo. Para serviços externos, request_id permite correlacionar com logs do provedor.
Trace de execução paralela ou em fila
Concorrência exige distinguir instâncias. Cada execução recebe run_id e, idealmente, parent_id e branch_id. O trace deve mostrar quando ficou na fila, quando iniciou e quais ramos sobrepuseram. Sem isso, ações de duas instâncias aparecem fora de ordem. Para modo queued, registre wait time e posição aproximada. Para parallel, recursos compartilhados e IDs de ramo. Uma condição de corrida pode ser reconstruída apenas se os timestamps tiverem resolução suficiente. Em sistemas distribuídos, relógios precisam estar sincronizados por NTP. O trace local não vê tudo; correlação com broker, hub e dispositivo pode exigir IDs propagados.
Trace de execução interrompida, reiniciada ou cancelada
Modos restart, single e cancelamentos podem encerrar fluxos antes da última ação. O trace precisa registrar motivo: novo gatilho, timeout, desligamento, atualização, usuário ou erro. A interrupção pode deixar efeito parcial. Se uma sequência ligou bomba e seria desligada depois, cancelar sem cleanup é perigoso. O trace deve mostrar a última etapa concluída e se houve bloco de finalização. Em reinício do controlador, traces voláteis podem desaparecer. Para funções críticas, eventos de início e fim devem ser persistidos externamente. A reconstrução precisa considerar que ausência de etapa final não significa necessariamente que o dispositivo permaneceu no estado anterior.
Considerações de Implementação
Capturar payload completo pode expor segredos e hábitos
Webhooks, APIs, calendários e eventos carregam tokens, cabeçalhos, localização, nomes e conteúdo pessoal. O trace deve redigir Authorization, cookies, chaves, senhas e campos classificados. Para dados de presença, retenha apenas o necessário. A interface precisa controlar acesso. Exportações e backups herdam o risco. Uma política de 7, 30 ou 90 dias depende da função e do volume. O diagnóstico não justifica coleta ilimitada. Em vez de corpo completo, registre schema, tamanho, event_id e campos relevantes. A redaction deve ocorrer antes de persistir.
Trace não substitui monitoramento nem confirmação física
O motor pode registrar que enviou turn_on com sucesso, enquanto a lâmpada ficou offline logo depois ou o estado foi otimista. Trace explica a execução, não garante resultado no ambiente. Para funções importantes, combine com feedback de estado, sensores independentes e métricas de disponibilidade. Também não substitui alertas: alguém precisa saber que a falha ocorreu. Logs passivos consultados semanas depois não reduzem impacto. O sistema deve transformar padrões de erro em diagnóstico e notificação, sem gerar fadiga.
Retenção precisa equilibrar investigação e custo
Automações de movimento podem executar milhares de vezes por mês. Guardar cada variável e payload aumenta banco. Defina quantidade por automação, janela de tempo ou amostragem. Erros podem ter retenção maior que sucessos. Traces de segurança podem exigir trilha imutável. Compressão e armazenamento externo são opções. A política deve considerar tamanho médio, frequência e requisitos. Excluir cedo demais impede investigar eventos raros; guardar tudo degrada desempenho. Métricas agregadas preservam tendência sem reter detalhes de cada execução.
Correlação entre camadas aumenta valor do trace
Um run_id deve acompanhar chamadas a scripts, webhooks, filas e serviços quando possível. Assim, o trace do motor pode ser ligado aos logs do proxy, broker, hub e API. Padrões de observabilidade distribuída usam trace_id e span_id; residências podem adotar versão simples. Sem correlação, cada sistema mostra horário aproximado e a investigação depende de adivinhação. Relógios precisam de NTP. Para privacidade, IDs devem ser opacos. A correlação deve sobreviver a retentativas, mantendo attempt_id separado.