Resposta direta
Log de integração sem nível de erro é um registro que descreve o que aconteceu, mas não permite decidir o que fazer. A implementação começa pela pergunta que o time precisa responder ao abrir o log: isso exige ação agora, pode esperar ou é apenas histórico. A partir dela, define-se um conjunto pequeno de níveis, com significado acordado entre quem opera e quem mantém a integração, e a regra de quem é acionado em cada um. Sem esse acordo, incluir o campo nível apenas desloca o problema: o log passa a ter uma coluna a mais e a mesma triagem manual.
- Objetivo
- Orientar implementação
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata o nível de erro como decisão de operação, com dono e ação por nível, em vez de atributo técnico da mensagem.
A decisão vem antes do campo
Um log de integração costuma nascer como apoio à depuração. Ele registra a chamada, o retorno e a mensagem de exceção. Isso basta para quem escreveu o código e não basta para quem assume a operação em outro horário.
A classificação por nível só faz sentido depois de uma definição anterior: o que a operação precisa saber ao abrir o log. Em geral são três situações. O processo parou. O processo seguiu com dado incompleto. O processo seguiu e o evento é apenas histórico. O nível existe para separar essas três, não para descrever a exceção.
O que o registro precisa carregar para ser triável
Nível sem contexto não ajuda. Um registro de erro precisa identificar a transação, o sistema de origem, o sistema de destino, a etapa ou regra que falhou e o horário. Quando a integração trabalha com lotes, o identificador do lote e a faixa de registros afetados evitam que a triagem vire garimpo.
Vale separar falha técnica de recusa de negócio. A primeira é indisponibilidade, tempo esgotado ou resposta inválida. A segunda é o dado rejeitado por uma regra acordada, como cadastro sem documento obrigatório. As duas exigem ações diferentes e donos diferentes. Misturadas no mesmo nível, a fila de erro perde utilidade e tudo passa a ser tratado como urgência.
O que o nível de erro não resolve
Classificar não corrige a causa. Se a integração não tem tratamento de exceção, reprocessamento definido ou dado de origem confiável, o log fica mais legível e o problema continua o mesmo. Também não substitui acordo de prazo e responsabilidade: sem alguém designado para cada nível, a classificação é apenas uma etiqueta.
Há casos em que o recurso é excesso. Integrações com pouco volume e uma única pessoa responsável podem ser acompanhadas por uma fila simples de pendências. E o nível não mede impacto sozinho: a mesma falha pode ser grave durante um fechamento e irrelevante numa carga de teste. Quem classifica precisa saber em que momento do processo o erro ocorreu.
Recurso prático
Níveis de log definidos pelo efeito no processo
| Nível | Critério de classificação | Ação e responsável |
|---|---|---|
| Erro | A integração não entregou o dado e o processo a jusante parou ou vai parar | Operação aciona o responsável técnico e informa a área afetada, com identificador da transação no registro |
| Recusa de negócio | O dado chegou e foi rejeitado por uma regra acordada, como cadastro sem campo obrigatório | Triagem do time de negócio decide entre corrigir na origem, reprocessar ou encerrar o item |
| Alerta | O dado chegou, mas incompleto ou fora do padrão esperado, sem interromper o processo | Verificação periódica por quem opera a integração, com registro do que foi feito |
| Informativo | Evento esperado, sem desvio: início, fim, volume processado, reprocessamento concluído | Ninguém é acionado; serve para reconstruir o histórico quando houver dúvida sobre o que passou |
O erro mais comum é classificar pelo texto da exceção e não pelo efeito no processo: a mesma falha de conexão é erro quando interrompe o faturamento e informativo quando ocorre numa carga de teste sem uso imediato.
Sobre o que está escrito aqui
Conceitos relacionados: nível de severidade · mensagem de log · triagem de falhas · contrato de integração · responsável de plantão. Exemplos são ilustrativos. Não há cliente, resultado, preço, prazo ou certificação nesta página. Quando o formato indicado é Projeto de implementação, ele descreve uma possibilidade de trabalho — a conversa inicial avalia contexto e aderência.
Para continuar
- Integrações, sistemas e qualidade de dados — Página central do tema
- Números que não batem: por que a divergência… — planilhas divergentes
- Falhas silenciosas em integrações: como perce… — falhas silenciosas
Páginas relacionadas
O mesmo problema em outro objetivo
- Log de integração sem nível de erro: isolar a falha pelo fluxo — Diagnosticar
- Log de integração sem nível de erro: o que registrar — Organizar um processo
- Log de integração sem nível de erro: o que cada saída prova — Comparar alternativas
- Log de integração sem nível de erro: o que medir na saída — Explicar medição
- Log de integração sem nível de erro: o que exigir no contrato — Orientar avaliação e contratação
Outras leituras em Integrações, sistemas e qualidade de dados
- Integração sem documentação: por onde reconstruir o contrato — Integração que funciona sem documentação: reconstruir o contrato pelos dados, definir responsável e controlar cada mudança.
- Teste de integração só em ambiente controlado: o que exigir — O que avaliar e o que exigir quando o fornecedor só demonstra integração em ambiente controlado, sem carga real nem cenário de falha.
- Cópia de segurança sem teste de leitura: o que comparar — Compara formas de testar leitura de cópias de segurança: teste completo, restauração parcial e verificação de arquivo, com custo e limite de cada uma.
- Fila sem limite de tempo: como pôr prazo e dono em cada etapa — O que definir para uma fila de processamento ter prazo, responsável e critério de encerramento, e o que essa estrutura não resolve.
- Cadastro sem chave única: como comparar as formas de casar — Compara as saídas possíveis para casar cadastros sem chave única: regra determinística, pontuação de semelhança e revisão manual, com o custo de cada uma.