Quando uma API falha em producao, a pergunta nao e apenas qual erro aconteceu. A pergunta real e: qual requisicao falhou, quem foi afetado, qual endpoint recebeu a chamada, quanto tempo demorou, que dependencias foram acionadas e onde a linha do tempo se perdeu?
Sem correlacao de requisicao, os logs viram trechos soltos. Um erro aparece no backend, outro no Nginx, outro no banco, outro no cliente da API. A equipe sabe que algo quebrou, mas nao consegue seguir a requisicao do inicio ao fim.
Este guia mostra como pensar logs para APIs Spring Boot de forma pratica, especialmente em sistemas pequenos que precisam melhorar suporte, diagnostico, deploy e confianca sem implantar uma plataforma complexa no primeiro dia.
1. Comece pelo objetivo do log
Log nao existe para encher arquivo. Ele existe para responder perguntas durante suporte, incidente ou validacao de deploy.
Bons logs ajudam a descobrir:
- qual endpoint foi chamado;
- qual metodo HTTP foi usado;
- qual status foi retornado;
- quanto tempo a requisicao demorou;
- qual request ID acompanha a chamada;
- qual usuario tecnico, cliente ou integracao estava envolvido;
- qual dependencia externa falhou;
- qual excecao foi capturada;
- qual versao estava publicada.
A pagina de evidencias tecnicas ajuda a pensar esses sinais como prova consultavel, nao como ruido tecnico.
2. Use um identificador por requisicao
Um request ID e um identificador unico para seguir uma chamada ao longo do sistema. Ele pode vir de um header enviado pelo cliente ou ser gerado na entrada da API.
Headers comuns:
X-Request-Id;X-Correlation-Id;traceparent, quando existe rastreamento distribuido;- um identificador interno gerado por filtro ou interceptor.
O importante e que esse valor apareca em todos os logs relacionados a mesma requisicao. Assim, quando o cliente informa horario e erro, a equipe consegue filtrar a linha do tempo.
3. Use MDC para enriquecer logs no Spring Boot
No ecossistema Java, o MDC ajuda a carregar contexto no ciclo da requisicao. Um filtro pode colocar request ID, rota, metodo, usuario tecnico ou tenant no contexto de logging. Depois, cada log emitido naquela thread inclui esses campos.
Cuidados importantes:
- limpe o MDC ao final da requisicao;
- evite guardar dados pessoais desnecessarios;
- nao registre senhas, tokens ou payload sensivel;
- garanta que chamadas assincronas nao percam contexto sem perceber;
- padronize nomes de campos para facilitar busca.
O artigo Observabilidade minima em APIs Spring Boot aprofunda essa ideia de visibilidade sem exagero operacional.
4. Registre entrada, saida e tempo de resposta
Uma API precisa registrar o suficiente para responder se o problema esta na entrada, no processamento ou na saida.
Em muitos casos, um log de acesso estruturado ja ajuda muito:
- request ID;
- metodo HTTP;
- caminho da rota;
- status de resposta;
- tempo total em milissegundos;
- tamanho aproximado de resposta, quando fizer sentido;
- origem tecnica ou cliente consumidor, quando seguro;
- versao da aplicacao.
Esse tipo de log ajuda a identificar rotas lentas, aumento de erro 500, resposta 404 inesperada e efeitos colaterais de deploy.
5. Separe log de negocio de log tecnico
Nem todo evento importante e uma excecao. Alguns logs explicam o fluxo de negocio: pedido criado, lead recebido, e-mail enviado, material solicitado, pagamento recusado, integracao ignorada por regra.
Registre eventos de negocio com contexto suficiente para suporte, mas sem vazar dado sensivel. Em vez de salvar documento, token ou mensagem completa, prefira identificadores internos, status e motivo tecnico.
Essa separacao ajuda a empresa a descobrir se o sistema falhou ou se executou uma regra esperada.
6. Trate excecoes com identificador para suporte
Quando ocorre erro inesperado, a resposta ao cliente nao deve expor stack trace. Mas o log precisa guardar a excecao com request ID e contexto suficiente.
Um tratamento global de excecoes pode:
- registrar erro com request ID;
- retornar resposta segura;
- usar status HTTP coerente;
- separar validacao, regra de negocio, recurso ausente e falha inesperada;
- incluir codigo de erro interno quando fizer sentido.
O artigo Como investigar erro 500 em Spring Boot mostra como usar logs, banco, integracoes e tratamento de excecoes para sair da tentativa e erro.
7. Inclua dependencias externas na linha do tempo
Muitas falhas parecem erro da API, mas nascem em outro lugar: SMTP, gateway, ERP, servico externo, DNS, banco, storage ou API de terceiro.
Para cada dependencia relevante, tente registrar:
- nome tecnico da integracao;
- request ID da requisicao principal;
- tempo gasto na chamada externa;
- status recebido;
- timeout ou erro controlado;
- tentativa de retry, quando existir;
- resultado de fallback, quando existir.
Sem esse mapa, a equipe pode aumentar servidor ou refatorar codigo quando o gargalo real esta em uma chamada externa sem timeout.
8. Cuide de dados sensiveis nos logs
Logs tambem podem virar risco. Eles costumam circular em suporte, backup, ferramentas externas e arquivos compactados. Por isso, evite registrar informacoes desnecessarias.
Nao registre:
- senhas;
- tokens de acesso;
- chaves privadas;
- cookies de sessao;
- dados pessoais completos sem necessidade;
- payloads inteiros de formularios;
- cartao, documento ou informacao financeira sensivel.
Quando precisar investigar payload, use amostras anonimizadas ou campos tecnicos suficientes para reproduzir o problema.
9. Conecte logs com deploy e incidente
Depois de um deploy, os primeiros logs mostram se a publicacao esta saudavel. Eles tambem ajudam a decidir se a versao pode ficar no ar.
Durante validacao pos-deploy, confira:
- se a versao nova aparece nos logs;
- se rotas principais respondem com status esperado;
- se nao ha excecao recorrente;
- se tempo de resposta ficou dentro do esperado;
- se formulario, e-mail e integracoes registram eventos corretos;
- se erros de migracao, banco ou configuracao aparecem logo no inicio.
O checklist pos-deploy em VPS complementa essa rotina com validacao de Nginx, Docker, backend, banco, sitemap, ads.txt e tags.
10. Use logs para decidir o proximo passo
Log bom nao termina na leitura. Ele orienta acao. Depois de entender o problema, a equipe deve decidir se corrige codigo, ajusta configuracao, melhora banco, adiciona timeout, muda payload, refatora fluxo ou cria alerta.
Para cada incidente, registre:
- request IDs analisados;
- rotas afetadas;
- periodo da falha;
- causa mais provavel;
- correcao aplicada;
- evidencia de que melhorou;
- acao preventiva.
A pagina de playbooks tecnicos oferece um roteiro para transformar erro recorrente em triagem, contencao, correcao, prevencao e evidencia.
Checklist de logs para API Spring Boot
- Gerar ou aceitar um request ID por requisicao.
- Propagar o identificador em logs da API.
- Incluir metodo, rota, status e tempo de resposta.
- Usar MDC com limpeza ao final da requisicao.
- Registrar excecoes com contexto seguro.
- Evitar dados sensiveis, tokens e payload completo.
- Medir chamadas externas e timeouts.
- Associar logs a deploy, versao e ambiente.
- Guardar request IDs analisados nos incidentes.
- Revisar logs depois de cada deploy importante.
Logs com correlacao transformam investigacao em linha do tempo. A equipe deixa de procurar agulha em arquivo enorme e passa a seguir uma requisicao concreta, com horario, rota, contexto e resultado.
Para pequenas empresas, isso reduz tempo de suporte, melhora confianca em deploys e evita decisoes caras baseadas em palpite. Antes de trocar servidor ou reescrever endpoint, vale perguntar: os logs ja contam a historia completa da requisicao?
Termos tecnicos desta leitura
Alguns conceitos aparecem com frequencia neste tema. Abrir o glossario ajuda a comparar definicoes, exemplos e leituras relacionadas sem sair do contexto do artigo.