Monitorando pipelines e runs
Diante de uma falha, a primeira medida é abrir o run e ler o log e o resumo do analista que a Nekt gera por IA. Ele já costuma dizer a causa e o que fazer. Como diagnosticar, agir e reprocessar antes que o cliente perceba.
- Abrir o run e ler o log e o resumo do analista
- Seguir as ações recomendadas e reprocessar
- Acompanhar a saúde e a atualidade do dado
O agendamento de uma pipeline é uma promessa: o dado vai estar lá, atualizado, quando alguém precisar. Monitorar é garantir que essa promessa seja cumprida. A pior forma de descobrir que um pipeline quebrou é pelo cliente perguntando por que o número está desatualizado. Quando isso acontece, você perdeu um pedaço da confiança. Este guia é sobre chegar na falha antes dela chegar no cliente, e sobre a coisa mais importante quando ela acontece: na Nekt, você quase nunca precisa adivinhar o que deu errado. Cada execução deixa um log detalhado e um resumo escrito por IA que explica a causa e o que fazer.
Por que monitorar
Dado parado quebra a confiança mais rápido do que dado errado. Um número errado às vezes passa despercebido, mas um dashboard congelado numa segunda-feira de manhã é notado na hora. E o problema quase nunca é dramático: um sync que falhou de madrugada, uma credencial que expirou, uma fonte que mudou de schema sem avisar. Tudo isso, se ninguém estiver olhando, só aparece quando já virou reclamação. Monitorar é transformar esses silêncios em sinais que você vê primeiro.
O histórico de execuções
Cada vez que um pipeline roda, ele gera um run: um registro do que aconteceu naquela execução. O histórico de runs é o seu painel de saúde. Três coisas contam mais que o resto:
- Status: terminou com sucesso ou falhou? É o primeiro olhar.
- Duração: quanto tempo levou? Um run que costuma levar 2 min e de repente leva 40 min é um alerta, mesmo que tenha dado "sucesso".
- Volume: quantas linhas entraram? Um número muito fora do normal (para mais ou para menos) merece um olhar.
Um recorte típico de runs recentes se parece com isto:
Diante de uma falha: leia o log e o resumo do analista
Aqui está a parte mais importante deste guia, e a que mais muda o seu dia a dia. Quando um run falha, a primeira medida não é sair investigando a fonte, nem mexer na transformação, nem abrir o dashboard do provedor. A primeira medida é abrir o run que falhou e ler o que a Nekt já preparou para você: o log detalhado daquela execução e o resumo do analista, uma análise que a Nekt gera automaticamente por IA para cada run.
Para pipelines críticas, você deve sempre ativar os alertas para receber notificação de falhas via e-mail, assim você conseguirá agir antes mesmo de o problema estourar.
O resumo do analista lê o log por você e escreve, em linguagem simples, duas coisas: o que aconteceu e as ações recomendadas. Na prática, ele já costuma dizer a causa (por exemplo, "credencial expirada, 401 Unauthorized") e o que fazer para resolver (atualizar credenciais, reconectar a fonte, reprocessar). Você não precisa decifrar stack trace: a Nekt traduz o erro técnico numa explicação e num plano de ação.
O que aconteceu Sua conexão com a fonte falhou porque as credenciais não estão mais autorizadas. A fonte respondeu 401 Unauthorized ao tentar autenticar, o run parou logo no início e nenhuma linha foi processada. Ações recomendadas 1) Atualizar as credenciais da fonte 2) Verificar as permissões da conta conectada 3) Reprocessar o pipeline
Perceba o que isso economiza. Sem o resumo, um
401 Unauthorized no meio de um log de centenas de linhas
exige que você saiba onde procurar e o que aquilo significa. Com o
resumo, a resposta chega escrita: a causa é a credencial, a ação é
reconectar e reprocessar. O log continua ali, inteiro, para quando
você quiser o detalhe. Mas o ponto de partida deixa de ser a
investigação e passa a ser a leitura.
O roteiro, quando um run falha, vira três passos:
- Abra o run e leia o resumo do analista e o log. Comece pelo "O que aconteceu". Ele quase sempre já aponta a causa. O log fica logo abaixo se você precisar confirmar o detalhe.
- Siga as ações recomendadas. A Nekt lista, em ordem, o que fazer: atualizar credenciais, reconectar a fonte, ajustar a transformação, verificar permissões. Execute na ordem sugerida.
- Reprocese. Corrigida a causa, rode de novo e confirme pelo histórico: status verde e volume dentro do esperado.
Antes de mexer em qualquer coisa, reprocesse uma vez. Uma parte real das falhas é transitória: a fonte piscou, a rede caiu por um instante. Se o segundo run passa limpo, você economizou uma investigação. Se falha de novo, aí sim abra o run: o resumo do analista e o log vão dizer se a causa é estrutural e qual é.
Traduzindo o que o resumo aponta
O resumo do analista já traz a causa e a ação em cada caso. Ainda assim, ajuda ter no bolso o mapa das famílias de falha mais comuns, para reconhecer o padrão na hora em que ler:
| O que o resumo costuma apontar | Causa por trás | Ação recomendada |
|---|---|---|
| 401 / credencial não autorizada, falha logo no início | Autenticação: token ou credencial da fonte expirou | Atualizar credenciais, reconectar a fonte, reprocessar |
| Erro citando uma coluna ou campo inexistente | Mudança de schema: a fonte renomeou ou removeu um campo | Ajustar a transformação ao novo schema, reprocessar |
| Run verde, mas 0 linhas processadas | Filtro vazio, fonte sem dados novos, ou janela de datas errada | Conferir a fonte direto e a lógica de filtro |
| Timeout ou duração muito acima do normal | Volume grande demais, ou fonte lenta/instável no momento | Reprocessar; se repetir, reduzir a janela ou o grão |
| Falha só num pipeline que depende de outro | O pipeline de origem falhou antes (efeito cascata) | Corrigir a origem primeiro, depois reprocessar o de baixo |
Alertas: ser avisado, não descobrir na mão
Olhar o histórico de runs toda manhã funciona até o dia em que você esquece, ou está de férias, ou o workspace cresce para 40 pipelines. Monitorar na mão não escala. O objetivo final é inverter a lógica: em vez de você ir atrás da falha, a falha vem até você. Um aviso quando um run falha chega antes do cliente perceber. E quando o aviso chega, o roteiro é sempre o mesmo: abra o run, leia o resumo do analista e o log, siga as ações recomendadas, reprocesse. Comece simples, um alerta nos pipelines mais críticos já muda o jogo, e vá cobrindo o resto.
Numa agência, o relatório de um cliente parou de atualizar numa sexta. Ninguém viu. Na segunda o cliente perguntou por que os números de mídia estavam iguais aos da semana anterior. Ao abrir o run, o resumo do analista já dizia tudo: "O que aconteceu: o token do Meta Ads expirou e a fonte respondeu 401. Ações recomendadas: reconectar a fonte e reprocessar." Cinco minutos para resolver, sem precisar caçar a causa. Depois disso, a agência passou a monitorar duas coisas em cada pipeline de cliente: atualidade (parado há quanto tempo) e volume (trouxe menos linhas que o normal), e adotou o hábito de sempre abrir o run e ler o resumo antes de mexer em qualquer coisa. O aviso agora chega no sábado de manhã, não na reclamação de segunda.