# Prometheus observabilidade: guia passo a passo para configurar

> Prometheus é uma ferramenta open-source de monitoramento e alerta para coleta de métricas de serviços. O guia passo a passo cobre configuração inicial, exportadores, regras de alerta e integração com Grafana. Prometheus oferece observabilidade sem custo de licenciamento, com dicas para evitar armadilhas como cardinalidade excessiva e retenção inadequada de dados. A configuração exige arquivo prometheus.yml, targets de scrape e alertmanager para notificações eficazes.

*Pingobox · Apps e Software · 02 de setembro de 2026 · Gustavo Sequeira*

Quer monitorar seus serviços sem depender de ferramentas caras? Este guia mostra como configurar observabilidade com Prometheus, do básico ao alerta, com dicas para evitar erros comuns.

## Guia passo a passo para configurar observabilidade com Prometheus

Configurar observabilidade com Prometheus significa transformar logs e sinais em métricas acionáveis. Ao final deste guia, você terá um servidor coletando métricas de um alvo real, com uma consulta funcional e um alerta básico. Os pré-requisitos são simples: acesso a um terminal Linux, Docker instalado e um serviço HTTP qualquer para monitorar (pode ser uma API local).

## Passo 1: Instale o Prometheus

Baixe a versão estável mais recente do site oficial (prometheus.io) ou use a imagem Docker. Em um ambiente de teste, o caminho rápido é:

docker run -p 9090:9090 -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

Confirme se a interface web abriu em localhost:9090. Se a página não carregar, verifique se a porta não está ocupada e se o volume montou o arquivo correto. Um erro comum é esquecer o -v e rodar sem configuração, o que limita a coleta ao próprio Prometheus.

## Passo 2: Defina os alvos de coleta

Crie o arquivo prometheus.yml com a lista de alvos. O exemplo abaixo monitora o próprio Prometheus e um serviço fictício na porta 8080:

scrape_configs:

- job_name: 'prometheus'

static_configs:

- targets: ['localhost:9090']
- job_name: 'meu-servico'

static_configs:

- targets: ['localhost:8080']

Para cada alvo, o Prometheus faz um HTTP GET em /metrics. Se o serviço não expõe métricas nesse endpoint, ele aparecerá como DOWN. Use a página de Targets em localhost:9090/targets para conferir o estado. Dica: comece com um alvo simples, como o próprio Prometheus, antes de adicionar serviços complexos.

## Passo 3: Exponha métricas no seu serviço

Se o serviço for uma aplicação própria, adicione uma biblioteca cliente, como prometheus_client para Python ou micrometer para Java. O endpoint /metrics deve retornar texto simples com métricas no formato Prometheus, por exemplo:

http_requests_total{method="get",code="200"} 1027

Um erro comum é expor métricas em formato incompatível, como JSON. O Prometheus espera o formato de texto plano com linhas nome{label="valor"} número. Valide a saída com curl http://localhost:8080/metrics antes de configurar o scrape.

## Passo 4: Consulte métricas com PromQL

Na interface web, vá para a aba "Graph" e escreva uma consulta. Por exemplo, para ver a taxa de requisições por segundo:

rate(http_requests_total[5m])

PromQL é a linguagem de consulta do Prometheus. Ela permite filtrar por labels, calcular taxas e agregar dados. Teste consultas simples antes de avançar para alertas. Um erro comum é usar rate em um contador que ainda não tem pelo menos dois pontos de coleta, o que retorna valor vazio.

## Passo 5: Configure alertas no Alertmanager

Alertas são definidos em regras dentro do Prometheus. Crie um arquivo alerts.yml:

groups:

- name: exemplo

rules:

- alert: ServicoFora

expr: up == 0 for: 1m labels: severity: critical annotations: summary: "Serviço fora do ar"

Referencie esse arquivo no prometheus.yml e reinicie o serviço. O Alertmanager cuida do envio de notificações, mas para o teste inicial basta ver o alerta na aba "Alerts". Não configure notificações antes de validar a regra, pois erros de sintaxe impedem a regra de carregar.

## Passo 6: Visualize com Grafana

O Grafana conecta-se ao Prometheus como fonte de dados. Adicione a URL http://localhost:9090 e crie um painel com um gráfico simples. Um erro comum é usar a query errada ou esquecer de configurar o intervalo de tempo. Importe um dashboard pronto da comunidade para acelerar, mas revise as métricas para garantir que fazem sentido para o seu caso.

## Checklist final

- [ ] Servidor Prometheus rodando na porta 9090
- [ ] Pelo menos um alvo aparecendo como UP em Targets
- [ ] Endpoint /metrics exposto no serviço monitorado
- [ ] Uma consulta PromQL retornando dados
- [ ] Uma regra de alerta carregada sem erros
- [ ] Grafana conectado e exibindo um gráfico

Com isso, você tem o ciclo básico de observabilidade funcionando. O próximo passo é explorar exporters prontos, como node_exporter para métricas de servidor, e pensar em quais métricas de negócio valem a pena acompanhar.

## FAQ

### O que é observabilidade em Prometheus?

Observabilidade é a capacidade de entender o estado interno de um sistema por meio de métricas, logs e rastreamentos. O Prometheus foca em métricas: ele coleta, armazena e consulta séries temporais, permitindo detectar problemas como picos de latência ou quedas de serviço.

### Quais são os principais componentes do Prometheus?

O servidor Prometheus coleta e armazena métricas. O Alertmanager processa alertas enviados pelo servidor. Exporters expõem métricas de sistemas que não falam nativamente o formato. O Grafana é opcional, mas comum, para visualização.

### Como o Prometheus se compara a outras ferramentas?

Diferente de soluções completas como Datadog, o Prometheus é open source e exige mais configuração manual. Em contrapartida, oferece modelo de dados dimensional e PromQL, uma linguagem de consulta flexível. Ele é bem adaptado para ambientes Kubernetes e microsserviços.

### Preciso usar Docker para instalar o Prometheus?

Não. O Docker facilita o teste, mas você pode baixar o binário direto do site oficial e rodar como um processo comum. A escolha depende do seu ambiente: em produção, Kubernetes ou systemd são opções comuns.

### Como sei se o Prometheus está coletando métricas corretamente?

Verifique a página de Targets na interface web: cada alvo deve estar com estado UP. Além disso, execute uma consulta simples, como up, e veja se retorna valores 1 para os serviços saudáveis.

### O que fazer se meu serviço não aparece nas métricas?

Confirme se o serviço está acessível na porta configurada e se o endpoint /metrics responde. Teste com curl. Se o formato da resposta não for o texto esperado, ajuste a biblioteca cliente ou o exporter usado.

---

Fonte (canonical): https://www.pingobox.com.br/apps-e-software/prometheus-observabilidade-guia-passo-a-passo-para-configurar/