Se o seu dashboard está bonito, mas o incidente só aparece quando o cliente já reclamou, o problema quase nunca é o Prometheus sozinho. os spring boot actuator metrics prometheus erros comuns costumam estar na exposição do endpoint, na coleta incompleta, na cardinalidade alta e em alertas escritos para parecerem corretos, não para pegarem falhas reais. Se a base desse fluxo ainda nao estiver redonda, vale revisar O que é o Spring Boot e para que serve? antes de avancar.
Em produção, isso vira um cenário irritante: a aplicação está lenta, o pod reinicia, o banco degrada, e a observabilidade continua verde. a boa notícia é que dá para corrigir isso com ajustes pequenos e objetivos, sem transformar seu projeto em uma plataforma de monitoramento complexa. Depois de ajustar esse trecho, o proximo passo natural e seguir para Spring Boot Health Check Actuator Monitoramento sem falhas.
Para quem está organizando a base do stack, vale lembrar o papel do O que é o Spring Boot e para que serve?. actuator e Prometheus entram como extensão natural dessa base: um para expor sinais da aplicação, o outro para coletar e permitir alertas confiáveis.
Spring Boot Actuator metrics Prometheus erros comuns na prática
Actuator, Micrometer e Prometheus funcionam bem juntos quando cada peça está configurada com intenção. o erro mais comum é tratar observabilidade como checkbox: adiciona a dependência, habilita um endpoint e assume que pronto. na prática, o stack só ajuda quando o endpoint está exposto com controle, as métricas representam a realidade e o scrape realmente enxerga o que importa. Depois de ajustar esse trecho, o proximo passo natural e seguir para Spring boot 422 ou 400 validacao api rest: erros comuns e ajuste.
Em um sistema de pedidos com pico no horário de almoço, por exemplo, um time pode confiar em métricas globais de requisição enquanto o gargalo era apenas uma rota específica de checkout. em outro caso, a aplicação parecia saudável porque o health check ficava verde, mas o pool de conexões do banco já estava no limite. o sinal existia, só não estava sendo medido da forma certa. Depois de ajustar esse trecho, o proximo passo natural e seguir para Como configurar logback no spring boot sem poluir logs: erros.
Erro 1: expor o endpoint errado ou esquecer o prometheus
O primeiro tropeço é surpreendentemente básico. a aplicação sobe, o Actuator funciona, mas o endpoint de Prometheus não está disponível. às vezes ele nem foi exposto. Na prática, às vezes está protegido por segurança sem exceção. Ainda assim, às vezes o caminho mudou em produção e ninguém percebeu.
A pior parte é que isso produz uma falsa sensação de segurança. o time abre o navegador, vê o /actuator/health respondendo, e assume que o restante está ok. não está. Na prática, prometheus precisa enxergar o endpoint certo, no formato certo, com status 200 e sem bloqueio inesperado.
Erro 2: coletar métricas sem entender o que elas representam
Outra armadilha bem comum é adicionar métricas sem critério. o painel fica cheio de contadores, timers e gauges, mas eles não explicam o problema real. uma média de latência pode parecer aceitável enquanto o p95 já está estourado. Na prática, um contador de requisições pode crescer normalmente enquanto uma rota específica está falhando.
Em produção, isso aparece em duas situações clássicas. a primeira é o serviço que responde bem no geral, mas degrada em picos curtos e passa despercebido. a segunda é o backend com tarefas assíncronas, onde o request/response parece saudável, mas filas internas já estão acumulando atraso. Na prática, se a métrica não traduz o comportamento operacional, ela só enfeita o dashboard.
Erro 3: cardinalidade alta que destrói a utilidade da métrica
Esse é o erro que mais cobra juros. tudo parece funcionar até o volume crescer. aí você usa um ID de usuário, um path inteiro ou um valor livre como tag, e cada variação gera uma nova série temporal. Na prática, o custo sobe, as consultas ficam lentas e o Prometheus passa a armazenar muito barulho e pouco sinal.
Comparação direta: uma métrica com tags estáveis como método, status e rota normalizada ajuda a ver tendências. já uma métrica com userId, orderId ou URL completa dá uma sensação de detalhe, mas mata a escalabilidade da observabilidade. melhor visibilidade quase sempre vem de menos variação, não de mais detalhe.
Spring boot actuator metrics prometheus erros comuns: Os 7 erros que deixam a observabilidade enganando você
Os problemas mais dolorosos não costumam acontecer isoladamente. normalmente são uma combinação de configuração incompleta, métrica mal pensada e alerta fraco. isso cria a ilusão de monitoramento: o painel existe, o scrape roda, mas a equipe continua sem confiança.
Erro 4: health check confundido com observabilidade
O endpoint de health é importante, mas ele não substitui métricas. Um serviço pode estar UP e ainda assim degradado, saturado ou preso em uma dependência lenta. se o time usa health como termômetro principal, vai descobrir problemas tarde demais.
O caminho melhor é usar health como sinal binário e métricas para comportamento. em sistemas mais maduros, o health ajuda na orquestração e no roteamento, enquanto Prometheus e alertas mostram degradação antes da queda.
Erro 5: alertas baseados em média, não em sintoma
Este erro faz muita gente perder madrugada. a média de latência fica bonita, então o alerta não dispara. só que meia dúzia de chamadas está travando a experiência do usuário. Na prática, ou o time cria um alerta exagerado em cima de uma métrica instável e acaba treinando todo mundo a ignorá-lo.
Regra boa precisa refletir sintoma real. se a dor é indisponibilidade, alerte em falha de scrape, erro persistente ou indisponibilidade do endpoint. se a dor é lentidão, olhe para taxa de erro, p95/p99 e comportamento sustentado por janela de tempo. Na prática, alerta que dispara sem contexto vira ruído. Ainda assim, alerta que não dispara em incidente vira decoração.
Erro 6: security e exposure tratados depois do deploy
Deixar o actuator aberto demais é ruim. deixar fechado demais, também. o erro recorrente é tratar segurança e exposição como ajuste posterior, quando já existe pipeline, dashboard e automação montados. Na prática, depois aparecem os sintomas: o Prometheus não consegue ler, o endpoint fica inacessível do namespace certo ou alguém resolve abrir tudo só para “destravar rápido”.
O ajuste bom fica no meio: expor apenas o necessário, validar acesso do ambiente de observabilidade e proteger endpoints que não devem ser públicos. em vez de assumir acesso por default, prefira testar o caminho completo antes de liberar produção.
Erro 7: dashboard bonito sem teste de regra e sem manutenção
É muito fácil montar um painel que impressiona na demonstração e envelhece mal. quando ninguém valida se a regra ainda faz sentido após uma mudança de rota, liberação de cache ou alteração de timeout, a observabilidade vira um artefato parado.
Em uma mudança de pipeline de pagamentos, por exemplo, o time trocou o nome da rota e esqueceu a regra de alerta antiga. o dashboard continuava cheio de gráficos, mas o alerta nunca mais disparou. o problema não era o painel. Na prática, era a falta de manutenção da lógica de observabilidade junto com a evolução da aplicação.
Secção prática: configuração enxuta que realmente ajuda
Uma configuração útil começa simples e explícita. a ideia é expor o que importa, manter as métricas estáveis e garantir que Prometheus consiga scrape sem surpresas.
Dependências e configuração base
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
</dependencies>management:
endpoints:
web:
exposure:
include: health,info,prometheus
endpoint:
health:
show-details: when_authorized
metrics:
tags:
application: pedidos-apiEssa base já resolve uma parte grande dos erros de observabilidade: o endpoint passa a existir de forma previsível, o scrape encontra o alvo e as métricas levam um identificador estável para contexto.
Um endpoint customizado com métrica útil
@RestController
@RequestMapping("/orders")
public class OrderController {
private final Counter failedOrders;
public OrderController(MeterRegistry meterRegistry) {
this.failedOrders = Counter.builder("orders_failed_total")
.description("Quantidade de pedidos falhos")
.register(meterRegistry);
}
@PostMapping
public ResponseEntity<String> create(@RequestBody OrderRequest request) {
if (request.customerId() == null || request.amount() == null) {
failedOrders.increment();
return ResponseEntity.badRequest().body("Pedido inválido");
}
return ResponseEntity.ok("Pedido criado");
}
}Repare no que não entrou aqui: customerId como tag, payload inteiro como label e detalhes variáveis demais. o contador é simples porque o objetivo é medir falha operacional, não fazer auditoria por usuário.
Melhor abordagem versus pior abordagem
A melhor abordagem mede um comportamento estável e recorrente, como falha por tipo, status HTTP, fila acumulada ou latência por rota normalizada. a pior abordagem tenta capturar tudo de uma vez, especialmente valores únicos. a primeira permite alertar e comparar ao longo do tempo. Na prática, a segunda parece rica no começo, mas vira um peso caro e pouco confiável.
Se o seu cenário pede investigar detalhamento por usuário ou pedido, isso costuma pertencer a logs estruturados e tracing, não a métricas. métrica boa responde tendência. log responde contexto. Na prática, misturar os dois papéis deixa a observabilidade confusa.
Se você quer aprofundar o lado de alertas e disponibilidade, o próximo passo natural é o Spring Boot Health Check Actuator Monitoramento sem falhas. ele complementa bem a parte de exposição do Actuator e ajuda a montar uma linha de defesa mais confiável.
Quando usar e quando evitar esse desenho
Spring Boot Actuator com Prometheus funciona muito bem em APIs, workers, serviços de integração e sistemas que precisam de alertas operacionais rápidos. quando o time tem maturidade mínima para manter regras, a combinação entrega visibilidade real sem complicar demais a stack.
Evite forçar esse desenho como solução para tudo. se a equipe não consegue sustentar manutenção de métricas, dashboards e alertas, o resultado costuma ser barulhento. também vale evitar cardinalidade alta em serviços com grande volume de entidades dinâmicas, como marketplaces ou plataformas com muitos IDs diferentes. Na prática, nesses casos, a estrutura da métrica precisa ser ainda mais disciplinada.
Em projetos onde o problema principal é entender o fluxo de erro da API e padronizar respostas, faz sentido olhar também para Spring boot 422 ou 400 validacao api rest: erros comuns e ajuste. às vezes o sintoma do incidente aparece primeiro como erro de validação mal tratado, e não como saturação de infraestrutura.
Se o desafio for excesso de ruído operacional, a disciplina de logs ajuda muito na correlação entre métrica e evento. o guia Como configurar logback no spring boot sem poluir logs: erros encaixa bem como próximo passo para manter sinais úteis sem inundar o time com mensagens inúteis.
Erro comum: causa, sintoma e correção
Um bloco prático ajuda a diagnosticar rápido quando a observabilidade parece funcionar, mas não entrega confiança.
Erro comum: métricas sumiram depois do deploy
Causa: actuator exposto sem incluir /prometheus ou segurança bloqueando o scrape
Sintoma: target DOWN no Prometheus, 404 no endpoint ou 401 intermitente
Correção: expor explicitamente health, info e prometheus, testar o endpoint no mesmo caminho e credenciais do scrapingEsse tipo de falha aparece muito em produção porque o ambiente de desenvolvimento costuma ser mais permissivo. o deploy sobe, o dashboard abre, e só depois alguém percebe que a coleta real nunca ficou estável.
Spring boot actuator metrics prometheus erros comuns: referencias externas
Para validar detalhes de implementacao e aprofundar a configuracao, vale consultar a documentacao oficial do Spring Security, o guia de claims no JWT.io e a documentacao do Spring Boot.
FAQ
Como configurar Spring Boot Actuator e Prometheus corretamente?
Inclua o actuator, adicione o registry do Prometheus, exponha explicitamente o endpoint de métricas e teste o acesso de fora da aplicação. em produção, o ideal é validar o mesmo caminho e as mesmas credenciais usadas pelo Prometheus.
Por que minhas métricas do Spring Boot não aparecem no Prometheus?
As causas mais comuns são endpoint não exposto, dependência ausente, bloqueio de segurança ou path incorreto no scrape config. se o endpoint responde no browser mas não no Prometheus, o problema costuma estar na rota, autenticação ou formato do payload.
Como evitar cardinalidade alta nas métricas do Spring Boot Actuator?
Use tags estáveis, normalize rotas e evite valores únicos como IDs, e-mails e URLs completas. se a necessidade é investigar um caso específico, prefira logs estruturados e tracing em vez de encher a métrica com variáveis demais.
Conclusão: observabilidade boa é a que sobrevive ao incidente
Observabilidade de verdade não é a que deixa o dashboard mais bonito. é a que continua útil quando a aplicação fica lenta, quando o banco degrada, quando o alerta precisa falar alto e quando alguém precisa entender o que aconteceu sem adivinhar. os erros de observabilidade quase sempre vêm de detalhes pequenos: exposição incompleta, métrica mal escolhida, cardinalidade exagerada e alerta fraco.
Se você corrigir esses pontos, a diferença aparece rápido. o Prometheus para de mentir por omissão, o Actuator deixa de ser só um endpoint “de saúde” e os alertas começam a representar incidente real. essa é a linha entre monitoramento decorativo e monitoramento que ajuda o time de fato.
Próximos passos práticos: revise o que está exposto, confira as tags das métricas, valide a regra dos alertas e simule um incidente antes que ele aconteça de verdade. se quiser consolidar a base, vale seguir para o material de monitoramento do Actuator e depois ajustar logs e tratamento de erros da API para fechar o ciclo com mais confiança.
Leitura complementar: Spring Boot Health Check Actuator Monitoramento sem falhas, Como configurar logback no spring boot sem poluir logs: erros e Spring boot 422 ou 400 validacao api rest: erros comuns e ajuste. os proximos passos sao validar esse fluxo no seu projeto, ajustar o caso de uso real e cobrir a implementacao com testes.