Como monitoramos uma ferramenta que roda em vários totens físicos ao mesmo tempo

Nosso sistema de telemetria para ferramentas desktop de clientes nasceu para um caso simples: uma única instalação por cliente, rodando numa única máquina. Foi assim com a ferramenta de automação de conciliação financeira em Python, o primeiro caso de uso desse sistema (contamos os detalhes desse case no post Como automatizar conciliação financeira com Python e PDF). Endpoints públicos recebem eventos de uso e relatórios de erro, e o painel administrativo mostra o estado de cada instalação. Um cliente novo quebrou essa premissa.

O desafio: uma ferramenta, vários totens

O avatar 3D interativo que construímos para uma empresa de ativações de marca que atua em shoppings e feiras corporativas (detalhamos a solução completa no case Avatar interativo 3D para shoppings e feiras) não roda numa máquina só. A mesma ferramenta roda ao mesmo tempo em vários totens físicos, espalhados em locais diferentes. Telemetria por instalação não fazia sentido aqui: a mesma ferramenta roda ao mesmo tempo em vários totens, e cada totem precisava aparecer separado no painel.

Como estendemos a telemetria existente

Em vez de construir um sistema paralelo, estendemos o que já existia. A página de telemetria do painel administrativo agora mostra uma tabela Totens (N), agrupando os eventos recebidos por identificador de totem. Isso só acontece quando a ferramenta específica opta por esse agrupamento: é uma flag de configuração por ferramenta, e hoje só uma ferramenta usa essa flag.

Dias ativos e o que significa estar atrasado

A tabela de totens expõe duas informações com origens diferentes. "Dias ativos" é auto-reportado: o próprio totem conta e informa quantos dias esteve ativo, o servidor só repassa esse número. Já o estado "atrasado" é calculado pelo servidor a partir do último evento visto: se faz mais de uma hora sem receber nenhum evento daquele totem, ele aparece como atrasado no painel. É uma divisão de responsabilidade simples: o totem sabe o próprio histórico, o servidor só sabe dizer se ainda está ouvindo aquele totem.

O gotcha: timestamp sem fuso horário

O cálculo de "atrasado" escondia um problema que só apareceu em desenvolvimento local. O driver que usamos para conectar no Postgres do Neon (via HTTP) devolve os timestamps sem informação de fuso horário. Em produção, na Vercel, isso não causa dano: o servidor roda em UTC, e um timestamp sem fuso interpretado como UTC é um timestamp em UTC de verdade. Em desenvolvimento local, no fuso de Brasília (UTC-3), o mesmo timestamp sem fuso era interpretado como horário local, e o cálculo de "atrasado" saía com um desvio de 3 horas.

Não chegou a virar bug em produção, mas foi um gotcha real durante a validação local, do tipo que só aparece quando o fuso da máquina de quem está testando diverge do fuso do servidor de produção.

Esse sistema é o mesmo que sustenta o avatar 3D interativo em produção hoje, e a mesma base que já sustentava a conciliação financeira antes dele. Se sua operação também depende de alguma ferramenta rodando em várias pontas ao mesmo tempo, e você precisa saber com confiança quando alguma delas parou de responder, conta pra gente o contexto.