Tutorial: como monitorar Docker com Prometheus no Ubuntu 24.04

18 min de leitura  ·  Guia técnico

Monitorar Docker com Prometheus no Ubuntu 24.04 significa coletar métricas de CPU, memória, rede e disco de cada container em execução e armazená-las em um banco de dados de séries temporais para análise e alertas. Para configurar o monitoramento completo, siga estes passos:

1. Instale o Docker e o Docker Compose no Ubuntu 24.04
2. Suba o cAdvisor como container para expor métricas dos containers
3. Configure o Prometheus com o arquivo prometheus.yml apontando para o cAdvisor
4. Suba o Prometheus via Docker Compose e verifique os targets
5. Instale o Grafana e importe um dashboard pré-configurado para Docker
6. Configure alertas básicos via Alertmanager ou regras nativas do Prometheus

Pré-requisitos para monitorar Docker com Prometheus

Antes de iniciar a configuração do monitoramento de containers, certifique-se de que o ambiente atende aos seguintes requisitos:

• Sistema operacional: Ubuntu 24.04 LTS com acesso root ou usuário com sudo
• Docker: versão 26.x ou superior instalado e em execução (docker --version)
• Docker Compose: plugin v2 (docker compose version) — o comando é docker compose, sem hífen
• Portas liberadas no firewall: 9090 (Prometheus), 8080 (cAdvisor), 3000 (Grafana)
• Mínimo de recursos: 2 vCPUs e 2 GB de RAM no servidor VPS ou dedicado
• Acesso SSH ao servidor: consulte como acessar servidores VPS Linux da AviraHost se precisar de ajuda com a conexão
• Diretório de trabalho: crie /opt/monitoring para organizar os arquivos de configuração

Como instalar e preparar o ambiente Docker no Ubuntu 24.04

O monitoramento de containers com Prometheus exige que o Docker Engine esteja corretamente instalado e que o daemon esteja expondo métricas. No Ubuntu 24.04, o processo de instalação usa o repositório oficial da Docker Inc., garantindo a versão mais recente e suporte a longo prazo.

Atualize os pacotes do sistema e instale as dependências:

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release

Adicione o repositório oficial do Docker:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verifique se o Docker está em execução:

sudo systemctl enable docker --now
docker --version
docker compose version

Docker version 26.1.4, build 5650f9b
Docker Compose version v2.27.1

Habilite a exposição de métricas nativas do daemon Docker editando o arquivo de configuração:

sudo nano /etc/docker/daemon.json

Adicione o seguinte conteúdo:

{
  "metrics-addr": "0.0.0.0:9323",
  "experimental": true
}

Reinicie o daemon para aplicar as alterações:

sudo systemctl restart docker

Confirme que as métricas do daemon estão disponíveis:

curl http://localhost:9323/metrics | head -20

# HELP builder_builds_failed_total Number of failed image builds
# TYPE builder_builds_failed_total counter
builder_builds_failed_total{reason="build_canceled"} 0
...

Com o daemon expondo métricas na porta 9323, o Prometheus poderá coletar informações sobre o próprio motor Docker, como número de containers, imagens e volumes.

Configurando o cAdvisor para expor métricas de containers

O cAdvisor (Container Advisor) é o componente central para coletar métricas individuais de cada container em execução. Diferente do docker stats, que exibe dados apenas no terminal sem persistência, o cAdvisor expõe um endpoint HTTP no formato Prometheus, permitindo retenção histórica e integração com dashboards.

Crie o diretório de trabalho e o arquivo Docker Compose principal:

sudo mkdir -p /opt/monitoring
cd /opt/monitoring
nano docker-compose.yml

Adicione a definição do cAdvisor ao arquivo:

version: "3.8"

networks:
  monitoring:
    driver: bridge

services:
  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    restart: unless-stopped
    privileged: true
    ports:
      - "8080:8080"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    networks:
      - monitoring

Suba o cAdvisor e verifique se está respondendo:

docker compose up -d cadvisor
curl http://localhost:8080/metrics | grep container_cpu | head -5

# HELP container_cpu_usage_seconds_total Cumulative cpu time consumed
# TYPE container_cpu_usage_seconds_total counter
container_cpu_usage_seconds_total{cpu="cpu00",id="/",image="",name=""} 1234.56
...

O endpoint http://SEU_IP:8080/metrics agora expõe centenas de métricas por container, incluindo container_memory_usage_bytes, container_network_receive_bytes_total e container_fs_reads_bytes_total.

Instalando e configurando o Prometheus para scrape dos containers

Com o cAdvisor em execução, o próximo passo é configurar o Prometheus para fazer scrape das métricas em intervalos regulares. O arquivo prometheus.yml define os jobs de coleta, incluindo o daemon Docker e o cAdvisor.

Crie o arquivo de configuração do Prometheus:

mkdir -p /opt/monitoring/prometheus
nano /opt/monitoring/prometheus/prometheus.yml

Insira a configuração completa:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: "docker-daemon"
    static_configs:
      - targets: ["host.docker.internal:9323"]

  - job_name: "cadvisor"
    scrape_interval: 10s
    static_configs:
      - targets: ["cadvisor:8080"]

Adicione o serviço Prometheus ao docker-compose.yml:

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=15d"
      - "--web.enable-lifecycle"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - monitoring

volumes:
  prometheus_data:

Suba o Prometheus:

docker compose up -d prometheus

Acesse http://SEU_IP:9090/targets no navegador. Você verá os três jobs listados. Aguarde alguns segundos e atualize a página — todos devem aparecer com status UP.

Teste uma query PromQL para confirmar que os dados estão chegando:

curl 'http://localhost:9090/api/v1/query?query=container_cpu_usage_seconds_total' | python3 -m json.tool | head -30

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [...]
  }
}

Instalando o Grafana e criando dashboards para Docker

O Grafana transforma as métricas brutas do Prometheus em dashboards visuais interativos. Para ambientes de produção com múltiplos containers, os painéis pré-configurados do Grafana Labs economizam horas de configuração manual.

Adicione o Grafana ao docker-compose.yml:

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=SenhaForte123!
      - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - monitoring

volumes:
  prometheus_data:
  grafana_data:

Atenção: substitua SenhaForte123! por uma senha segura antes de subir o container em produção. Nunca use a senha padrão em ambientes expostos à internet.

Suba o Grafana:

docker compose up -d grafana

Acesse http://SEU_IP:3000 e faça login com as credenciais definidas. Em seguida:

1. Vá em Connections → Data Sources → Add data source
2. Selecione Prometheus
3. No campo URL, insira http://prometheus:9090
4. Clique em Save & Test — você verá a mensagem "Data source is working"
5. Vá em Dashboards → Import
6. Insira o ID 14282 (dashboard oficial cAdvisor para Docker) e clique em Load
7. Selecione o data source Prometheus e clique em Import

O dashboard exibirá painéis de CPU por container, uso de memória, tráfego de rede e operações de disco em tempo real, com histórico dos últimos 15 dias conforme configurado na retenção do Prometheus.

Para otimizar ainda mais o desempenho do seu servidor Linux, consulte as dicas de otimização de servidores Linux da AviraHost.

Configurando alertas básicos no Prometheus

Regras de alerta permitem que o Prometheus notifique quando um container ultrapassa limites de recursos. Esta configuração de alertas nativos funciona sem o Alertmanager, usando apenas o arquivo de regras do Prometheus.

Crie o arquivo de regras:

nano /opt/monitoring/prometheus/alert_rules.yml

Adicione regras para os cenários mais comuns em produção:

groups:
  - name: docker_alerts
    rules:
      - alert: ContainerHighCPU
        expr: rate(container_cpu_usage_seconds_total{name!=""}[5m]) * 100 > 80
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Container {{ $labels.name }} com CPU alta"
          description: "CPU acima de 80% por mais de 2 minutos. Valor atual: {{ $value }}%"

      - alert: ContainerHighMemory
        expr: (container_memory_usage_bytes{name!=""} / container_spec_memory_limit_bytes{name!=""}) * 100 > 85
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Container {{ $labels.name }} com memória crítica"
          description: "Uso de memória acima de 85% do limite. Valor: {{ $value }}%"

      - alert: ContainerDown
        expr: absent(container_last_seen{name!=""})
        for: 30s
        labels:
          severity: critical
        annotations:
          summary: "Container não encontrado"
          description: "Um container parou de reportar métricas."

Referencie o arquivo de regras no prometheus.yml:

rule_files:
  - "/etc/prometheus/alert_rules.yml"

Atualize o volume no docker-compose.yml para incluir o arquivo de regras:

    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./prometheus/alert_rules.yml:/etc/prometheus/alert_rules.yml:ro
      - prometheus_data:/prometheus

Recarregue a configuração do Prometheus sem reiniciar o container:

curl -X POST http://localhost:9090/-/reload

Verifique os alertas em http://SEU_IP:9090/alerts. Alertas ativos aparecerão em vermelho; alertas pendentes, em amarelo.

Problemas comuns e como resolver

Sintoma: cAdvisor não aparece como UP nos targets do Prometheus

Causa: O Prometheus não consegue resolver o hostname cadvisor dentro da rede Docker, geralmente porque os containers estão em redes diferentes ou o nome do serviço no Compose está incorreto.
Solução: Confirme que ambos os serviços estão na mesma rede (monitoring) no docker-compose.yml. Execute docker compose ps para verificar o status de cada container. Teste a conectividade diretamente: docker exec prometheus wget -qO- http://cadvisor:8080/metrics | head -5. Se retornar métricas, o problema está no prometheus.yml; revise o campo targets.

Sintoma: métricas do daemon Docker (porta 9323) aparecem como DOWN

Causa: O Prometheus tenta acessar host.docker.internal:9323, mas o mapeamento de gateway não foi configurado corretamente, ou o daemon Docker não foi reiniciado após a edição do daemon.json.
Solução: Verifique se o daemon.json está correto com sudo cat /etc/docker/daemon.json. Confirme que o daemon foi reiniciado: sudo systemctl status docker. Teste o endpoint: curl http://localhost:9323/metrics | head -3. No docker-compose.yml, certifique-se de que a diretiva extra_hosts: ["host.docker.internal:host-gateway"] está presente no serviço Prometheus.

Sintoma: Grafana exibe "No data" nos painéis do dashboard importado

Causa: O data source do Prometheus não está configurado corretamente, ou o dashboard importado usa variáveis de job que não correspondem aos nomes definidos no prometheus.yml.
Solução: Acesse Connections → Data Sources e clique em Test no data source Prometheus. Se falhar, verifique se a URL é http://prometheus:9090 (nome do serviço Docker, não localhost). No dashboard, verifique as variáveis em Dashboard Settings → Variables e confirme que o valor de job corresponde a cadvisor conforme definido no prometheus.yml.

Sintoma: Prometheus consumindo memória excessiva no servidor

Causa: O período de retenção padrão de 15 dias combinado com scrape_interval de 10s e muitos containers gera um volume alto de séries temporais.
Solução: Reduza o período de retenção ajustando o parâmetro no docker-compose.yml: --storage.tsdb.retention.time=7d. Aumente o scrape_interval para 30s no prometheus.yml para ambientes com menos criticidade. Monitore o uso de memória com docker stats prometheus e ajuste conforme necessário.

Perguntas frequentes sobre monitorar Docker com Prometheus

O Prometheus consegue monitorar containers Docker diretamente?

O Prometheus não coleta métricas do Docker nativamente. É necessário usar o cAdvisor (Container Advisor), que expõe métricas de CPU, memória, rede e disco de cada container em um endpoint HTTP que o Prometheus consegue fazer scrape. A integração é simples e pode ser feita via Docker Compose, como demonstrado neste tutorial.

Qual a diferença entre cAdvisor e Docker stats para monitoramento?

O comando docker stats exibe métricas em tempo real no terminal, mas não armazena histórico nem permite alertas. O cAdvisor expõe as mesmas métricas em formato compatível com Prometheus, permitindo retenção histórica, dashboards no Grafana e regras de alerta via Alertmanager. Para ambientes de produção, o cAdvisor com Prometheus é a escolha correta, pois oferece visibilidade histórica e capacidade de resposta proativa a incidentes.

Como verificar se o Prometheus está coletando métricas dos containers?

Acesse a interface web do Prometheus em http://SEU_IP:9090/targets e verifique se o job do cAdvisor aparece com status UP. Você também pode executar a query container_cpu_usage_seconds_total na aba Graph para confirmar que os dados estão chegando. Se o status for DOWN, verifique a conectividade de rede entre os containers e as configurações de scrape_interval no arquivo prometheus.yml.

É possível monitorar Docker com Prometheus sem instalar o Grafana?

Sim. O Prometheus possui uma interface web nativa em http://SEU_IP:9090 que permite executar queries PromQL e visualizar gráficos básicos. No entanto, o Grafana oferece dashboards muito mais completos, com painéis pré-configurados para Docker e cAdvisor disponíveis no Grafana Labs. Para produção, o Grafana é altamente recomendado, pois facilita a identificação visual de anomalias e a criação de alertas visuais.

Quanto de memória o Prometheus consome monitorando Docker?

O consumo de memória do Prometheus depende do número de métricas coletadas, da frequência de scrape e do período de retenção configurado. Em ambientes com poucos containers e retenção padrão de 15 dias, o consumo fica entre 200 MB e 500 MB. Para reduzir o uso de memória, ajuste o parâmetro --storage.tsdb.retention.time e aumente o scrape_interval para 30s ou 60s no arquivo de configuração do Prometheus.

Conclusão

Com esta configuração, você tem um stack completo de observabilidade para containers Docker no Ubuntu 24.04, pronto para uso em produção. Para consolidar o que foi implementado:

• Valide o stack completo: execute docker compose ps em /opt/monitoring e confirme que cAdvisor, Prometheus e Grafana estão com status running; acesse os três endpoints no navegador para garantir que respondem corretamente
• Personalize os alertas: ajuste os thresholds das regras em alert_rules.yml conforme os limites reais dos seus containers e integre o Alertmanager para receber notificações por e-mail, Slack ou PagerDuty
• Automatize o backup das configurações: versione os arquivos prometheus.yml, alert_rules.yml e docker-compose.yml em um repositório Git para facilitar a recuperação e replicação do ambiente em outros servidores

Leia também

• Otimizar Apache contra ataques DDoS e sobrecarga no Ubuntu 22.04
• Guia para configurar acesso SSH apenas para IPs específicos no Ubuntu 22.04
• Comparativo: CentOS vs. Ubuntu para Servidores Linux – Qual Escolher em 2024?

Precisa de ajuda com monitoramento Docker em VPS?

Configurar Prometheus, cAdvisor e Grafana exige um servidor com recursos adequados e acesso root completo. Os planos de VPS da AviraHost oferecem Ubuntu 24.04 pré-instalado, suporte técnico especializado e infraestrutura estável para rodar stacks de monitoramento em produção sem limitações.

Conheça os planos de VPS da AviraHost e comece a monitorar seus containers hoje