Timestamps em APIs, bancos e logs

Depuração em produção costuma significar alinhar eventos de um trace HTTP, uma linha de banco e três arquivos de log — cada um com sua representação de tempo.

Fluxo de correlação

1. Escolha um instante de referência — ex.: hora do relato do usuário ou timestamp do request ID
2. Normalize tudo para epoch UTC em ms (ou ns se tiver)
3. Aplique tolerância a skew de relógio — notebooks e containers derivam; ±2 minutos é comum em sistemas frouxos
4. Filtre janela adjacente — referência ± 5 minutos antes do grep profundo
5. Documente a unidade de origem nas notas (nginx: sec, app: ISO UTC, db: timestamptz)

APIs

JSON REST pode expor:

{ "createdAt": 1700000000000, "updatedAt": "2023-11-14T22:13:20.000Z" }

Tipos mistos no mesmo payload acontecem quando serviços evoluem. Parse cada campo nos seus próprios termos.

Schemas GraphQL e protobuf em geral documentam tipos escalares — leia antes de escrever comparações no cliente.

Bancos de dados

• PostgreSQL TIMESTAMPTZ armazena UTC internamente — bom padrão
• Colunas epoch BIGINT exigem lembrar para sempre sec vs ms
• DATETIME sem fuso (legado MySQL) guarda “hora de parede como dada” — perigoso para apps globais

Ao unir logs de app com SQL, converta ambos os lados para a mesma representação de instante primeiro.

Logs distribuídos

Use trace IDs que embutem ou acompanhem timestamps. Se só existirem strings de relógio de parede, converta uma linha amostra de cada serviço usando um evento conhecido (marcador de deploy, heartbeat) para estimar skew.

Conclusão

Depuração entre serviços é normalização + busca em janela, não adivinhar relógios locais. Converta primeiro, compare depois, amplie a janela por último.