Grafana e Prometheus: da coleta à interpretação
Publicado em 08 de outubro de 2026
Parte 2 de 8 — série Observabilidade na prática.
A API de catálogo demora, mas o painel que deveria mostrar sua atividade está vazio. No cenário hipotético da série, isso ainda não permite dizer se a API deixou de atender, se a coleta falhou ou se o filtro escondeu as séries. A investigação começa seguindo o caminho do dado.
Prometheus coleta e armazena séries temporais. Grafana consulta esse backend e apresenta os resultados. Saber onde cada trabalho acontece permite procurar a falha na camada certa: origem, scrape, expressão ou visualização.
Seguir o caminho da métrica
Suponha que a API exponha api_requests_total, um contador que cresce a cada requisição atendida. O nome é ilustrativo, não uma métrica que apareça automaticamente ao instalar um produto. A aplicação precisa implementá-lo e expô-lo; o Prometheus coleta as amostras e o Grafana consulta essas séries.
O valor acumulado do contador não é a taxa de requisições. rate(api_requests_total[5m]) estima a taxa por segundo para cada série usando as amostras da janela, com tratamento de resets. Os cinco minutos são apenas uma escolha didática: a janela deve conter amostras suficientes e corresponder à pergunta. Se houver várias séries, a taxa é calculada antes de uma agregação como a soma.
Esse fluxo tem pelo menos quatro pontos de verificação:
- Origem: o processo gera a medição com o nome e as dimensões esperadas?
- Coleta: o Prometheus alcança o alvo e registra as séries?
- Consulta: a expressão PromQL seleciona a série certa para o período escolhido?
- Visualização: o painel usa o datasource, a unidade e o tipo de gráfico adequados?
O painel desse contador precisa distinguir total acumulado de requisições por segundo. Para duração, a escolha é outra: um histograma representa uma distribuição de observações; seus dados precisam de consultas próprias para produzir médias ou percentis. Nome, tipo de instrumento, expressão e unidade precisam combinar.
O que uma série temporal representa
Uma série é identificada pelo nome da métrica e por pares de chave e valor chamados labels. Labels como serviço, padrão de rota ou classe de resposta podem separar dimensões úteis. Prefira um padrão como /produtos/{id} à URL com o identificador de cada produto. Mas cada combinação cria mais séries. Labels que aceitam valores livres — por exemplo, um ID de requisição ou texto completo de URL — podem multiplicar rapidamente a cardinalidade.
Cardinalidade alta exige mais memória e armazenamento, aumenta o custo de consultas e pode tornar o Prometheus menos útil justamente quando se precisa investigá-lo. Antes de adicionar um label, pergunte se alguém realmente precisa dividir gráficos por esse valor. Dados únicos para cada ocorrência costumam pertencer a logs ou traces, com políticas próprias, em vez de labels de métricas.
O modelo de coleta também importa. Prometheus usa normalmente um modelo de consulta periódica aos alvos. Um scrape que falha produz up=0 para aquele alvo. A ausência das séries da aplicação pode ter outras causas, como filtro, staleness ou falta de instrumentação. Se o alvo for removido da configuração, até sua série up deixa de existir após o tratamento de staleness. Valor zero e ausência de série comunicam estados distintos.
Dashboards que respondem a uma pergunta
Um painel útil não é uma coleção de gráficos, mas um atalho para uma decisão. Uma visão de disponibilidade pode mostrar alvos de coleta e probes de aplicação. Uma visão de recursos pode comparar CPU, memória e disco ao longo do tempo. Uma visão de banco pode destacar conexões e transações.
Cada gráfico deve deixar claro o intervalo de tempo, a unidade, a agregação e as dimensões usadas. Se o resultado é agregado entre vários serviços, diga isso. Se uma série não apareceu, investigue se a métrica não existe, se a consulta filtrou demais ou se realmente não houve eventos.
Um caso recorrente na operação é o painel “No data”. Ele não significa automaticamente erro. Dependendo de como o exporter expõe a métrica e de como a consulta a filtra, um gráfico de espera por lock pode não ter pontos quando nenhuma sessão está esperando; em outros casos, o resultado será zero. Em outra situação, o painel pode aplicar uma variável ao formato errado e enviar uma consulta inválida ao backend. A forma prática de distinguir os casos é executar a consulta no explorador, conferir o erro do datasource e testar as opções do filtro com cuidado.
Variáveis tornam dashboards reutilizáveis, mas modificam a consulta final. Prefira opções controladas e teste os valores de cada seletor. Uma consulta pode ser válida sem filtro e falhar quando uma variável representa “todos”. Mantenha a consulta e a legenda tão simples quanto a pergunta permitir. Os formatadores :regex e :raw têm usos diferentes: o primeiro escapa valores para regex, enquanto o segundo os repassa sem formatação. Trocar um pelo outro exige conhecer as opções e a expressão final; :raw não é uma correção universal para filtros quebrados.
Persistência, retenção e acesso
O Prometheus grava sua base de séries temporais em armazenamento local. Retenção e limites de armazenamento são decisões operacionais, não detalhes que podem ser deixados para depois. Período maior preserva mais histórico, mas consome recursos. Acompanhe o crescimento real antes de escolher limites e revise-os quando o número de alvos, a frequência de coleta ou a cardinalidade mudar.
Também planeje autenticação, rede e cópias de segurança para cada componente. Grafana não torna privado um datasource que está aberto na rede. Uma interface que escuta em todas as interfaces pode ficar acessível a mais clientes do que o pretendido. Leia o modelo de acesso da implantação e teste-o de fora do processo local. Tratar essa stack como ferramenta de administração exige proteger tanto os dados quanto os caminhos de consulta.
Um teste de ponta a ponta
Antes de criar um painel complexo, confirme uma série simples numa origem de teste ou num alvo sem dados sensíveis. Verifique que o Prometheus identifica o alvo como saudável, que a consulta retorna valores e que o Grafana apresenta unidade e intervalo esperados. Depois, interrompa deliberadamente a coleta nesse ambiente de laboratório e observe como o estado aparece. Esse ensaio ajuda a separar “serviço sem dados” de “sistema de coleta sem resposta”.
Para o catálogo, um painel vazio deve abrir uma investigação sobre o dado, não encerrar a investigação sobre o serviço. Uma série útil tem significado, origem e unidade conhecidos. Quando a consulta falhar, percorrer esse caminho costuma ser mais eficiente que reescrever a expressão às cegas.
Na série: anterior — Observabilidade começa pelas perguntas; próxima — OpenTelemetry Collector: organizando o fluxo da telemetria.