Cómo monitoreamos una herramienta que corre en varios totems físicos al mismo tiempo
Extendimos la telemetría de herramientas de escritorio para agrupar eventos por totem físico y resolvimos un problema real de zona horaria en el camino.
Nuestro sistema de telemetría para herramientas de escritorio de clientes nació para un caso simple: una única instalación por cliente, corriendo en una sola máquina. Así fue con la herramienta de automatización de conciliación financiera en Python, el primer caso de uso de este sistema (contamos los detalles de ese case en el post Cómo automatizar la conciliación financiera con Python y PDF). Endpoints públicos reciben eventos de uso y reportes de error, y el panel administrativo muestra el estado de cada instalación. Un cliente nuevo rompió esa premisa.
El desafío: una herramienta, varios totems
El avatar 3D interactivo que construimos para una empresa de activaciones de marca que opera en shoppings y ferias corporativas (detallamos la solución completa en el case Avatar interactivo 3D para shoppings y ferias) no corre en una sola máquina. La misma herramienta corre al mismo tiempo en varios totems físicos, distribuidos en distintos lugares. Telemetría por instalación no tenía sentido aquí: la misma herramienta corre al mismo tiempo en varios totems, y cada totem necesitaba aparecer por separado en el panel.
Cómo extendimos la telemetría existente
En vez de construir un sistema paralelo, extendimos el que ya existía. La página de telemetría del panel administrativo ahora muestra una tabla Totens (N), agrupando los eventos recibidos por identificador de totem. Esto solo ocurre cuando la herramienta específica opta por ese agrupamiento: es una flag de configuración por herramienta, y hoy solo una herramienta usa esa flag.
Días activos y qué significa estar atrasado
La tabla de totems expone dos datos con orígenes distintos. "Días activos" es autorreportado: el propio totem cuenta e informa cuántos días estuvo activo, el servidor solo repasa ese número. El estado "atrasado", en cambio, lo calcula el servidor a partir del último evento visto: si hace más de una hora que no llega ningún evento de ese totem, aparece como atrasado en el panel. Es una división de responsabilidad simple: el totem sabe su propio historial, el servidor solo sabe decir si todavía está escuchando a ese totem.
El gotcha: timestamp sin zona horaria
El cálculo de "atrasado" escondía un problema que solo apareció en desarrollo local. El driver que usamos para conectar con el Postgres de Neon (vía HTTP) devuelve los timestamps sin información de zona horaria. En producción, en Vercel, esto no causa daño: el servidor corre en UTC, y un timestamp sin zona interpretado como UTC es un timestamp en UTC de verdad. En desarrollo local, en el huso horario de Brasilia (UTC-3), el mismo timestamp sin zona se interpretaba como horario local, y el cálculo de "atrasado" salía con un desvío de 3 horas.
No llegó a convertirse en bug en producción, pero fue un gotcha real durante la validación local, del tipo que solo aparece cuando la zona horaria de la máquina de quien está probando difiere de la del servidor de producción.
Este sistema es el mismo que sostiene el avatar 3D interactivo en producción hoy, y la misma base que ya sostenía la conciliación financiera antes de él. Si tu operación también depende de alguna herramienta corriendo en varios puntos al mismo tiempo, y necesitas saber con confianza cuándo alguna dejó de responder, contanos el contexto.