Diagnóstico local para sistemas de PDV
Detalhes do projeto
Por que nasceu
O suporte via um sintoma genérico — “a plataforma de PDV caiu” — enquanto a causa real podia estar em dezenas de processos, portas, padrões de log, bancos, interfaces HTTP ou no endereço incorreto do nó. O diagnóstico manual dependia da memória de especialistas.
O que eu criei
Mapeei as dependências da plataforma a partir de incidentes em produção, defini o modelo de integridade e implementei o agente em Rust, os coletores, o console local, as ações permitidas, o instalador e a documentação operacional.
Como foi estruturado
- 01Coletar
Coletores configurados por TOML inspecionam processos, portas TCP, identidade de rede, logs, integridade dos bancos, verificações HTTP e recursos do host Windows sem fixar regras específicas da unidade no código.
- 02Correlacionar
O estado persistente correlaciona mudanças de PID, posições de leitura dos logs e avanço do sequenciador fiscal para detectar crash loops e regressões entre ciclos de coleta.
- 03Agir
Uma API HTTP local serve o console web, endpoints JSON e métricas Prometheus; uma lista auditada de ações permitidas viabiliza a recuperação sem execução arbitrária de comandos.
Restrições e trade-offs
+
Restrições que moldaram o sistema
- 01O agente precisava rodar em hosts Windows com poucas dependências e sobreviver a reinicializações sem intervenção.
- 02O diagnóstico precisava continuar útil quando o caminho de rede central estivesse indisponível.
- 03Os controles de recuperação não poderiam virar um shell remoto genérico dentro da loja.
Trade-offs
- 01Um binário Rust compacto e poucas dependências priorizaram implantação previsível em vez de um framework maior de observabilidade.
- 02A operação local reduziu a visibilidade central inicialmente, mas preservou o diagnóstico durante incidentes de conectividade.
- 03Ações configuradas limitam a flexibilidade de propósito; segurança e auditoria importam mais que controle arbitrário.
Outras decisões de arquitetura
- Um binário Rust compacto foi priorizado em vez de um framework maior de observabilidade para manter a implantação Windows previsível e com poucas dependências.
- A operação local preservou o diagnóstico durante falhas de conectividade central, aceitando inicialmente menor visibilidade agregada da frota.
Valor para a operação
Uma indisponibilidade genérica passou a indicar componente, causa provável e próxima ação permitida em um ciclo de diagnóstico de cinco segundos.
Princípio de engenharia
“Boa observabilidade não produz mais logs; ela preserva estado e explica qual dependência mudou antes de o sintoma aparecer.”