pnclENGINEObter acesso à API

NOTAS DE CAPACIDADE

Odds velhas: pergunte ao feed antes dos seus logs

Um incidente de frescor começa com uma pergunta: de quem é o relógio que parou. Os endpoints de saúde do feed respondem em uma requisição cada.

O seu painel mostra odds velhas e o instinto é abrir os seus próprios logs. Segure esse instinto por cinco minutos. A primeira pergunta em qualquer incidente de frescor é de quem é o relógio que parou, seu ou do feed, e o feed responde a isso diretamente. Depurar o próprio pipeline antes de perguntar é como um soluço do provedor vira uma tarde desperdiçada.

Pergunte ao feed antes dos seus logs

Dois endpoints de status existem exatamente para esse momento, como o guia de health check documenta, verificado em 2026-10-30. Um /ping público retorna um simples ok para sondas que não conseguem autenticar. Um /health autenticado retorna o estado operacional dos dois feeds: status, live_write_age_ms, a fonte que está carregando os dados ao vivo no momento, e um campo version que é o mesmo cursor que os seus endpoints de board retornam como last.

Uma requisição cada, e a chamada ao /health conta contra o seu plano como qualquer outra, então uma vez por minuto por ambiente é a cadência certa.

Leia a resposta inteira, não a primeira linha

Os campos de topo descrevem o feed ao vivo. O serviço de pré-jogo é um objeto aninhado com status, idade de escrita e version próprios, e o status de topo não muda por um problema de pré-jogo. Um monitor que lê só o campo de topo é cego para metade do feed.

Duas armadilhas importam num incidente. Um status de pré-jogo unreachable significa que o próprio health check não conseguiu alcançar aquele serviço: trate como desconhecido, não como caído. E as idades de escrita normalmente ficam bem abaixo de um segundo, então uma leitura nas dezenas de milhares de milissegundos já é uma história, diga o campo status o que disser.

A comparação de cursores decide a culpa

O campo mais forte da resposta é version, porque ele é comparável. O seu poller guarda o cursor da última leitura. Se o version do feed bate com o seu cursor guardado, o feed não passou de você: a estagnação é sua. Se o version do feed está à frente e continua escrevendo, o feed está vivo e o seu pipeline é quem não está lendo.

Essa única comparação substitui toda a fase especulativa do incidente. Sem adivinhar deploys, sem reler o seu parser. Ou o feed parou, ou o seu lado parou, e o cursor diz qual.

Quando o feed está degradado de verdade

Uma leitura degradada é razão para segurar, não para martelar. Continue servindo o último snapshot bom com a idade visível, alargue o intervalo de polling para não somar carga enquanto o feed se recupera, e deixe o orçamento de frescor acionar os seus próprios alertas em vez do loop de erros.

O guia de monitoramento de pipeline cobre as métricas do lado do consumidor que vigiam o resto do incidente: idade do snapshot no seu lado, progresso do cursor, taxas de erro. Os endpoints de saúde respondem à pergunta anterior que essas métricas não conseguem: se o problema está a montante de tudo o que você controla.

Cinco minutos, dois endpoints, uma comparação de cursores. Depure nessa ordem e a maioria dos incidentes de frescor termina antes dos seus logs serem abertos.