4.14 Monitorando Contêineres Docker com Prometheus e Grafana

Monitorando Contêineres Docker com Prometheus e Grafana

Até agora utilizamos o Prometheus e o Grafana para visualizar métricas internas do próprio Prometheus. No entanto, em um ambiente real de produção precisamos monitorar os serviços que executam nossos sistemas de machine learning.

Em nosso ambiente atual temos diversos contêineres executando:

• APIs HTTP de classificação de produtos

• servidores WSGI e Nginx

• um broker Kafka

• um consumidor de análise de sentimentos

Caso ainda não estejam rodando, execute os seguintes comandos (note a ausência do --rm, pois queremos poder interromper os containers sem removê-los):

docker run -d -p 8080:80 --network minharede --name http-api-classificacao-produtos-container-unico-container http-api-classificacao-produtos-container-unico

docker run -d --name wsgi-app-container --network minharede wsgi-app

docker run -d -p 8081:80 --name my-custom-nginx-container --network minharede custom-nginx

docker run -d --name zookeeper --network minharede -e ZOOKEEPER_CLIENT_PORT=2181 -e ZOOKEEPER_TICK_TIME=2000 confluentinc/cp-zookeeper:7.0.1

docker run -d --name broker --network minharede -p 9092:9092 -e KAFKA_BROKER_ID=1 -e KAFKA_ZOOKEEPER_CONNECT='zookeeper:2181' -e KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,PLAINTEXT_INTERNAL:PLAINTEXT -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092,PLAINTEXT_INTERNAL://broker:29092 -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 -e KAFKA_TRANSACTION_STATE_LOG_MIN_ISR=1 -e KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR=1 confluentinc/cp-kafka:7.0.1

docker run -d --name analise-sentimentos-consumer-container --network minharede analise-sentimentos-consumer

Existem algumas formas de monitorar o consumo de recursos desses contêineres. Uma delas, bastante utilizada em produção, é o cAdvisor. O cAdvisor (Container Advisor) é uma ferramenta criada pelo Google para coletar métricas de contêineres Docker. Ele permite monitorar informações como:

• uso de CPU

• uso de memória

• tráfego de rede

• uso de disco

• estatísticas de execução de contêineres

Essas métricas podem ser acessadas diretamente por uma interface web ou coletadas por sistemas de monitoramento como o Prometheus.

O cAdvisor depende de acesso a recursos de baixo nível do sistema operacional (como cgroups), o que pode tornar seu uso mais limitado ou complexo em ambientes não Linux, como Windows ou Mac com Docker Desktop.

Para fins didáticos, portanto, adotaremos aqui outra abordagem. Criaremos um exporter, que nada mais é do que uma interface customizada entre uma fonte de dados e o Prometheus.

O que é um Exporter?

Um exporter é um pequeno serviço que:

• Coleta métricas de um sistema ou serviço que não fala Prometheus nativamente.

• Expõe essas métricas através de um endpoint HTTP /metrics que o Prometheus consegue entender.

• Atua como uma espécie de adaptador, transformando dados internos (CPU, memória, requisições, contadores, logs) em informações padronizadas.

Exporter como Sidecar

Um sidecar exporter é executado ao lado do container que você quer monitorar:

• Não é necessário modificar o container original.

• Ele consulta métricas do container ou serviço via API, logs ou outros mecanismos internos.

• Expõe essas métricas para que o Prometheus possa coletá-las.

Modelo "Pull" do Prometheus

O Prometheus adota o modelo de puxar métricas (pull) ao invés de receber (push) por algumas razões:

1. Simplicidade: não é necessário configurar autenticação ou endpoints externos para cada serviço que envia métricas. O Prometheus apenas consulta.

2. Determinismo: ele define quando e com que frequência coleta métricas (scrape interval). Isso ajuda a manter consistência na base de dados de séries temporais.

3. Redução de falhas silenciosas: se o exporter estiver offline, o Prometheus simplesmente registra que não conseguiu puxar dados. Em modelos push, você precisaria lidar com falhas e buffering.

4. Escalabilidade: Prometheus consegue monitorar centenas ou milhares de endpoints de forma centralizada, sem depender de cada serviço enviar dados corretamente.

Construindo um sidecar básico do Docker

Vamos criar um exporter que monitora os status dos containers, para saber se eles estão rodando ou não.

Crie uma pasta chamada docker-exporter. Este será o diretório onde vamos colocar o código do sidecar.

Dentro de docker-exporter, crie o arquivo exporter.py, com o seguinte código:

# exporter.py

from prometheus_client import start_http_server, Gauge
import docker
import time

# -----------------------------
# Prometheus Metric
# -----------------------------
# Gauge representa um valor que pode subir e descer (0 ou 1 nesse caso)
# Label "container" permite separar métricas por nome do container
container_up = Gauge(
    'container_up',
    'Container running (1/0)',
    ['container']
)

# -----------------------------
# Docker Client
# -----------------------------
# Cria um cliente conectado ao Docker local.
# Ele usa automaticamente o socket padrão (/var/run/docker.sock)
# ou variáveis de ambiente como DOCKER_HOST.
client = docker.from_env()


def collect():
    try:
        # ------------------------------------------------------
        # Docker API: listar containers
        # ------------------------------------------------------
        # containers.list(all=True) chama a API do Docker Engine:
        # GET /containers/json?all=true
        #
        # Retorna TODOS os containers:
        # - rodando
        # - parados
        #
        # Se fosse all=False, viria só os rodando.
        containers = client.containers.list(all=True)

        for c in containers:
            # --------------------------------------------------
            # c.status
            # --------------------------------------------------
            # Esse atributo já vem da API do Docker.
            # Valores comuns:
            # - 'running'
            # - 'exited'
            # - 'paused'
            # - 'created'
            #
            # Aqui simplificamos para:
            # 1 = running
            # 0 = qualquer outro estado
            status = 1 if c.status == 'running' else 0

            # --------------------------------------------------
            # Exportando métrica para Prometheus
            # --------------------------------------------------
            # Isso cria/atualiza uma série como:
            # container_up{container="nome"} <valor>
            #
            # IMPORTANTE:
            # Não usamos .clear(), então métricas antigas permanecem.
            container_up.labels(container=c.name).set(status)

    except Exception as e:
        # Se a API do Docker falhar (timeout, permissão, etc)
        # apenas logamos e mantemos os últimos valores expostos
        print(f"[WARN] Failed to collect metrics: {e}")


# -----------------------------
# Main loop
# -----------------------------
if __name__ == "__main__":
    print("Starting exporter on :8000")

    start_http_server(8000)

    while True:
        collect()

        # Espera antes da próxima coleta (polling)
        time.sleep(5)

Este script faz o "trabalho pesado": conecta na API do Docker, coleta métricas e disponibiliza em /metrics.

Note como estamos utilizando o tipo Gauge. Utilizamos o tipo Gauge porque essas métricas podem aumentar e diminuir ao longo do tempo (como CPU, memória e status), diferentemente de contadores que apenas crescem.

Ainda dentro do diretório docker-exporter, crie o Dockerfile:

# Dockerfile
FROM python:3.13.5-slim

# Instala dependências
RUN pip install docker prometheus_client

# Copia o script para dentro do container
COPY exporter.py /exporter.py

# Expondo a porta do Prometheus
EXPOSE 8000

# Comando principal
CMD ["python", "/exporter.py"]

Agora vamos construir a imagem docker:

docker build -t meu-docker-exporter .

Para acessar a API do Docker dentro do container, precisamos montar o socket do Docker:

docker run -d \
  --name docker-exporter-sidecar \
  --network minharede \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p 8000:8000 \
  meu-docker-exporter

• --network minharede → conecta o sidecar à network Docker onde os outros containers estão

• -v /var/run/docker.sock:/var/run/docker.sock:ro → permite que o sidecar leia dados do Docker

• -p 8000:8000 → expõe /metrics para o Prometheus

• -d → roda em background

Montar o socket do Docker permite que o container acesse diretamente a API do Docker no host. Embora isso seja extremamente útil para monitoramento, também representa um risco de segurança, pois esse acesso equivale, na prática, a permissões elevadas sobre o ambiente Docker.

Abra o navegador ou use curl:

curl http://localhost:8000/metrics

Você deverá ver algo como:

# HELP container_up Container running (1/0)
# TYPE container_up gauge
container_up{container="docker-exporter-sidecar"} 1.0
container_up{container="analise-sentimentos-consumer-container"} 1.0
container_up{container="broker"} 1.0
container_up{container="zookeeper"} 1.0
container_up{container="my-custom-nginx-container"} 1.0
container_up{container="wsgi-app-container"} 1.0
container_up{container="http-api-classificacao-produtos-container-unico-container"} 1.0

Pronto! O sidecar está coletando a métrica container_up com base no estado dos containers.

Integrando com Prometheus

Para integrar ao Prometheus, é preciso seguir a filosofia de configuração declarativa, ou infraestrutura como código (infrastructure as code). Dessa forma, tudo fica versionado, reproduzível e fácil de automatizar. Por isso, não é possível fazer essa integração pela interface web.

Para tanto, crie uma pasta, chamada prometheus, e dentro dela, um arquivo chamado prometheus.yml:

global:
  scrape_interval: 5s  # mesma frequência do exporter

scrape_configs:
  - job_name: 'docker-exporter'
    static_configs:
      - targets: ['docker-exporter-sidecar:8000']

• docker-exporter-sidecar é o nome do container (veja no comando de execução)

• Como ambos estão na mesma network (minharede), o Prometheus consegue resolver esse nome automaticamente

Agora crie um arquivo Dockerfile:

FROM prom/prometheus

COPY prometheus.yml /etc/prometheus/prometheus.yml

A única coisa que ele faz é copiar o arquivo de configuração para dentro do Prometheus, no diretório correto, substituindo o arquivo original.

Agora construa a imagem:

docker build -t meu-prometheus .

E rode, conectado na sua network:

docker run -d \
  --name prometheus \
  --network minharede \
  -p 9090:9090 \
  meu-prometheus

Nenhuma novidade, certo? Basta então abrir no navegador:

http://localhost:9090

1. Vá em Status → Target Health

2. Procure por docker-exporter-sidecar

Se estiver tudo certo, você verá:

State: UP

Se estiver DOWN, geralmente é:

• nome do container errado

• containers não estão na mesma network

• exporter não está rodando

---

Vá na aba Graph ou Table e rode a seguinte query:

container_up

Clique em Execute e veja a lista dos containers com o valor "1".

Observabilidade com Grafana

Agora que já temos essa métrica sendo exposta pelo nosso exporter e coletada pelo Prometheus, vamos dar o próximo passo, que é visualizar tudo de forma clara, por container, usando Grafana.

Crie um diretório chamado grafana. Dentro dele, crie um arquivo chamado prometheus.yml:

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    uid: meu-prometheus-ds

O arquivo prometheus.yml dentro do diretório do Grafana existe para configurar automaticamente a conexão com o Prometheus como fonte de dados (data source). Em vez de acessar a interface do Grafana e cadastrar manualmente o Prometheus toda vez que o container sobe, esse arquivo permite que essa configuração já venha pronta. Isso faz parte do conceito de provisioning, onde você define a infraestrutura e suas integrações como código, garantindo que o ambiente seja reproduzível e consistente em qualquer máquina.

Na prática, ele diz ao Grafana onde encontrar o Prometheus e como se comunicar com ele — no caso, usando a URL http://prometheus:9090, que funciona porque ambos os containers estão na mesma rede Docker. Sem esse arquivo, o Grafana até subiria normalmente, mas não teria nenhuma fonte de dados configurada, tornando impossível criar gráficos ou consultas até que essa etapa fosse feita manualmente.

Agora crie um arquivo chamado dashboards.yml:

apiVersion: 1

providers:
  - name: 'default'
    type: file
    disableDeletion: false
    updateIntervalSeconds: 10
    options:
      path: /var/lib/grafana/dashboards

O arquivo dashboards.yml define como o Grafana deve carregar dashboards automaticamente a partir de arquivos, também sem depender de configuração manual pela interface. Ele atua como um “mapa”, dizendo ao Grafana onde estão os dashboards (geralmente em JSON) e com que frequência verificar atualizações. Na prática, isso permite que, ao subir o container, todos os painéis já estejam disponíveis, padronizados e prontos para uso — algo essencial em ambientes onde você precisa subir e derrubar infraestrutura com frequência.

Isso se conecta diretamente ao conceito de provisioning, que é tratar configuração como código. Com o dashboards.yml, seus dashboards deixam de ser algo criado manualmente (e sujeito a erros ou esquecimento) e passam a ser versionados junto com o projeto. Isso garante reprodutibilidade, facilita colaboração em equipe e permite que o ambiente de observabilidade evolua de forma controlada — da mesma forma que o código da aplicação.

Porém, note que, até agora, não temos nenhum dashboard configurado. Para isso, vamos seguir uma abordagem híbrida, combinando Infrastructure as Code com configuração pela interface. Primeiro, criaremos os dashboards diretamente na UI do Grafana, pois isso é mais visual, rápido e didático para entender consultas e visualizações. Depois, exportamos esses dashboards como JSON e os incluímos no projeto, para que passem a ser carregados automaticamente via dashboards.yml. Assim, unimos o melhor dos dois mundos: facilidade de aprendizado no início e reprodutibilidade total depois, garantindo que o ambiente possa ser recriado exatamente da mesma forma em qualquer momento.

Seguindo com o exemplo, agora crie um arquivo Dockerfile:

FROM grafana/grafana

# Copy datasource config
COPY prometheus.yml /etc/grafana/provisioning/datasources/prometheus.yml

# Copy dashboard provider config
COPY dashboards.yml /etc/grafana/provisioning/dashboards/dashboards.yml

Agora basta construir a imagem e subir o container:

docker build -t meu-grafana .

docker run -d \
  --name grafana \
  --network minharede \
  -p 3000:3000 \
  meu-grafana

Abra no navegador (login padrão é admin/admin):

http://localhost:3000

Clique em Data sources e veja como o Prometheus já está configurado corretamente.

Se tudo estiver ok, podemos seguir para a criação do primeiro dashboard:

1. Clique em Dashboards

2. Clique em New → New Dashboard

3. Clique em Add visualization

4. Escolha o Prometheus como data source

Adicione uma query:

• Query: container_up

• Legend: {{container}}

Não esqueça de clicar em Run queries.

Em seguida, escolha o tipo de gráfico Stat.

Como título do painel, escolha Container status.

Na orientação, escolha Horizontal.

Em Value mappings, defina:

• 1 → UP (verde)

• 0 → DOWN (vermelho)

Agora pode salvar o dashboard. Escolha um nome como Visão geral (antes tínhamos salvado o título do painel).

Depois de salvo, clique em Back to dashboard e veja como todos os containers estão online. No canto da tela, escolha a opção para fazer o "Auto refresh" a cada 5 segundos.

Vamos ver esse monitoramento em ação? Interrompa um ou dois containers (sem removê-los) e fique de olho no dashboard:

docker stop broker
docker stop my-custom-nginx-container
docker stop wsgi-app-container

Veja como, depois de alguns segundos, o Grafana irá marcá-los como DOWN em vermelho. Suba-os novamente:

docker start broker
docker start my-custom-nginx-container
docker start wsgi-app-container

E veja o Grafana mostrando-os online.

Agora vamos fazer diferente. Ao invés de apenas interromper um container, remova-o completamente:

docker rm -f my-custom-nginx-container

Desta vez, o Grafana NÃO VAI detectar a interrupção, mas isso não é problema do Grafana, e sim da forma como o nosso exporter coleta os dados. Volte e examine o código do exporter e veja como ele obtém uma lista de containers pela API do Docker. Ora, se um container foi removido, ele não será retornado por essa lista (pois o Docker nem sabe que ele existe). Como o exporter mantém um cache das últimas medidas feitas, é isso que o Prometheus coleta (que o container estava online da última vez) e é isso que aparece no Grafana.

Esse tipo de problema é comum em sistemas de monitoramento baseados em scraping, e reforça a importância de definir explicitamente o que deve ser monitorado, em vez de depender apenas da observação do estado atual do sistema.

Melhorando o nosso exporter

Faça a seguinte modificação no exporter:

from prometheus_client import start_http_server, Gauge
import docker
import time

container_up = Gauge(
    'container_up',
    'Container running (1/0)',
    ['container']
)

+container_last_seen = Gauge(
+    'container_last_seen',
+    'Last time this container was seen (unix timestamp)',
+    ['container']
+)

client = docker.from_env()


def collect():
    try:
        containers = client.containers.list(all=True)
+        now = time.time()
        for c in containers:
            status = 1 if c.status == 'running' else 0
            container_up.labels(container=c.name).set(status)
+            container_last_seen.labels(container=c.name).set(now)

    except Exception as e:
        print(f"[WARN] Failed to collect metrics: {e}")


if __name__ == "__main__":
    print("Starting exporter on :8000")
    start_http_server(8000)
    while True:
        collect()
        time.sleep(5)

Construa a imagem, interrompa o container e execute-o novamente com a nova imagem.

Agora vá ao grafana, abra o dashboard e adicione uma nova visualização do tipo Stat.

• Query: time() - container_last_seen

• Legend: {{container}}

• Título: Última atualização

• Orientação: Horizontal

• Graph mode: None

• Unit: seconds (s)

• Color scheme: From thresholds (by value)

• Threshold: 30 (vermelho)

Salve o dashboard e volte para sua exibição. Experimente subir e remover um container e veja que, ainda que ele apareça como "UP" no painel de status, no novo painel o tempo de atualização logo será destacado em vermelho.

Mas veja que ainda há um problema. Da forma que isso foi configurado, o container só é monitorado depois que ele existe ao menos uma vez. Em lugar algum há uma lista de containers esperados, seja no:

• Exporter

• Prometheus

• Grafana

E isso pode gerar um problema. O ideal é que exista alguma definição da infraestrutura esperada para que o monitoramento não dependa de nenhum cache.

Há muitas formas de se fazer isso, e vamos adotar uma abordagem declarativa, ou seja, vamos criar um arquivo onde será declarada a infraestrutura (nomes dos containers) e isso será lido pelo nosso exporter para gerar métricas sem depender de determinado momento da execução, como caching, etc.

Fazer isso no exporter tem a vantagem de facilitar a configuração do Prometheus e Grafana, que pode se tornar algo complicado. Porém, também seria válido acrescentar essas checagens e filtros diretamente no Grafana.

Vamos lá. Altere o exporter para ler os dados dos containers de um arquivo externo:

from prometheus_client import start_http_server, Gauge
import docker
import time
+import json
+import os

+EXPECTED_FILE = os.getenv("EXPECTED_CONTAINERS_FILE", "expected_containers.json")

container_up = Gauge(
    'container_up',
    'Container running (1/0)',
    ['container']
)

container_last_seen = Gauge(
    'container_last_seen',
    'Last time this container was seen (unix timestamp)',
    ['container']
)

client = docker.from_env()

+def load_expected():
+    try:
+        with open(EXPECTED_FILE, "r") as f:
+            data = json.load(f)
+            return set(data.get("containers", []))
+    except Exception as e:
+        print(f"[WARN] Failed to load expected containers: {e}")
+        return set()

def collect():
    try:
        containers = client.containers.list(all=True)
        now = time.time()
+        expected = load_expected()
+        # Containers reais (como informado pelo Docker)
+        real_containers = {}
+        for c in containers:
+            real_containers[c.name] = c

-        for c in containers:
+        for name in expected:
+            c = real_containers.get(name)

+            # Se existe, significa que o container esperado existe mesmo
+            if c:
                status = 1 if c.status == 'running' else 0
                container_up.labels(container=c.name).set(status)
                container_last_seen.labels(container=c.name).set(now)
+            else:
+                # Container esperado, mas não existe → MISSING
+                container_up.labels(container=name).set(2)
+                # Neste caso, não atualizamos a métrica container_last_seen
    except Exception as e:
        print(f"[WARN] Failed to collect metrics: {e}")


if __name__ == "__main__":
    print("Starting exporter on :8000")
    start_http_server(8000)
    while True:
        collect()
        time.sleep(5)

Agora crie um arquivo chamado expected_containers.json:

{
  "containers": [
    "analise-sentimentos-consumer-container",
    "broker",
    "zookeeper",
    "my-custom-nginx-container",
    "wsgi-app-container",
    "http-api-classificacao-produtos-container-unico-container"
  ]
}

E altere o Dockerfile para incluir o novo arquivo:

# Dockerfile
FROM python:3.13.5-slim

# Instala dependências
RUN pip install docker prometheus_client

# Copia o script para dentro do container
COPY exporter.py /exporter.py
+COPY expected_containers.json /expected_containers.json

# Expondo a porta do Prometheus
EXPOSE 8000

# Comando principal
CMD ["python", "/exporter.py"]

Construa a imagem e execute novamente o exporter.

Também vamos reiniciar o Prometheus, para eliminar o histórico que ainda mantém as leituras anteriores. Remova e suba novamente o container do Prometheus.

Retornando ao grafana, vamos editar o painel de status do container para adicionar um novo mapeamento de valor:

Em Value mappings, defina:

• 2 → MISSING (laranja)

• 1 → UP (verde)

• 0 → DOWN (vermelho)

Agora vamos testar. Interrompa um container e remova outro:

docker stop broker
docker rm -f my-custom-nginx-container

Veja como os status são atualizados. Suba-os novamente:

docker start broker

docker run -d -p 8081:80 --name my-custom-nginx-container --network minharede custom-nginx

E veja o status sendo atualizado.

Exportando o dashboard para provisionamento

Agora que já configuramos dois painéis, vamos exportar nosso dashboard para garantir que o mesmo seja configurado segundo o conceito de provisioning, que é o processo de configurar dashboards, datasources e alertas de forma automática, em vez de fazer tudo manualmente pela interface web. É como "pré-programar" o Grafana para que ele já tenha tudo pronto quando iniciar.

No Grafana, acesse o dashboard que acabamos de criar. Em seguida, clique no botão Export -> Export as code. Escolha a opção V2 Resource (mais atual e feito para configuração do Grafana via código), formato JSON, e deixe a opção de compartilhar o dashboard com outra instância desabilitada.

Salve o arquivo com o nome de geral.json, na mesma pasta que estamos usando para configurar o Grafana.

Agora vamos copiá-lo para dentro da imagem usando o Dockerfile. Acrescente a seguinte linha:

FROM grafana/grafana

# Copy datasource config
COPY prometheus.yml /etc/grafana/provisioning/datasources/prometheus.yml

# Copy dashboard provider config
COPY dashboards.yml /etc/grafana/provisioning/dashboards/dashboards.yml

+# Copy dashboards
+COPY geral.json /var/lib/grafana/dashboards/geral.json

Observe que o caminho onde estamos copiando é o mesmo configurado em dashboards.yml.

Agora é só construir a imagem e executar novamente:

docker build -t meu-grafana .

docker run -d \
  --name grafana \
  --network minharede \
  -p 3000:3000 \
  meu-grafana

Veja como o dashboard agora aparece normalmente, exatamente como configurado.

Monitorando outras métricas

Vamos aprimorar um pouco nosso exporter para coletar outras métricas. No projeto docker-exporter, modifique o arquivo exporter.py para incluir novas medidas:

from prometheus_client import start_http_server, Gauge
import docker
import time
import json
import os

EXPECTED_FILE = os.getenv("EXPECTED_CONTAINERS_FILE", "expected_containers.json")

container_up = Gauge(
    'container_up',
    'Container running (1/0)',
    ['container']
)

container_last_seen = Gauge(
    'container_last_seen',
    'Last time this container was seen (unix timestamp)',
    ['container']
)

+container_cpu_percent = Gauge(
+    'container_cpu_percent',
+    'CPU usage percent',
+    ['container']
+)

+container_memory_bytes = Gauge(
+    'container_memory_bytes',
+    'Memory usage in bytes',
+    ['container']
+)

+container_network_bytes = Gauge(
+    'container_network_bytes_total',
+    'Total network traffic in bytes (rx + tx)',
+    ['container']
+)

client = docker.from_env()

def load_expected():
    try:
        with open(EXPECTED_FILE, "r") as f:
            data = json.load(f)
            return set(data.get("containers", []))
    except Exception as e:
        print(f"[WARN] Failed to load expected containers: {e}")
        return set()

def collect():
    try:
        containers = client.containers.list(all=True)
        now = time.time()
        expected = load_expected()
        # Containers reais (como informado pelo Docker)
        real_containers = {}
        for c in containers:
            real_containers[c.name] = c

        for name in expected:
            c = real_containers.get(name)

            # Se existe, significa que o container esperado existe mesmo
            if c:
                status = 1 if c.status == 'running' else 0
                container_up.labels(container=c.name).set(status)
                container_last_seen.labels(container=c.name).set(now)

+                # Stats
+                stats = c.stats(stream=False)  # stream=False para pegar uma snapshot

+                # Memory
+                mem = stats.get('memory_stats', {}).get('usage', 0)
+                container_memory_bytes.labels(container=c.name).set(mem)

+                # CPU
+                cpu_stats = stats.get('cpu_stats', {})
+                precpu_stats = stats.get('precpu_stats', {})
+                cpu_total = cpu_stats.get('cpu_usage', {}).get('total_usage', 0)
+                system_cpu = cpu_stats.get('system_cpu_usage', 0)
+                precpu_total = precpu_stats.get('cpu_usage', {}).get('total_usage', 0)
+                presystem_cpu = precpu_stats.get('system_cpu_usage', 0)
+                # fallback: se per-CPU não existir, assume 1 CPU
+                num_cpus = len(cpu_stats.get('cpu_usage', {}).get('percpu_usage', [1]))
+                cpu_percent = 0
+                cpu_delta = cpu_total - precpu_total
+                system_delta = system_cpu - presystem_cpu
+                if system_delta > 0 and cpu_delta > 0:
+                    cpu_percent = (cpu_delta / system_delta) * num_cpus * 100
+                container_cpu_percent.labels(container=c.name).set(cpu_percent)

+                # Network
+                net = stats.get('networks', {})
+                total_bytes = sum(v.get('rx_bytes', 0) + v.get('tx_bytes', 0) for v in net.values())
+                container_network_bytes.labels(container=c.name).set(total_bytes)


            else:
                # Container esperado, mas não existe → MISSING
                container_up.labels(container=name).set(2)
                # Neste caso, não atualizamos a métrica container_last_seen
    except Exception as e:
        print(f"[WARN] Failed to collect metrics: {e}")


if __name__ == "__main__":
    print("Starting exporter on :8000")
    start_http_server(8000)
    while True:
        collect()
        time.sleep(5)

Note como o cálculo de CPU no Docker não é direto, sendo necessário comparar snapshots consecutivos do uso de CPU do container e do sistema para obter um percentual.

Agora podemos reconstruir e subir a container novamente.

docker build -t meu-docker-exporter .

docker run -d \
  --name docker-exporter-sidecar \
  --network minharede \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p 8000:8000 \
  meu-docker-exporter

Vamos ao Grafana criar um novo painel para ver essas novas métricas? Vamos criar um novo dashboard chamado Métricas detalhadas, com cinco painéis:

• Painel 1: CPU %

• Query: container_cpu_percent

• Legend: {{container}}

• Type: Bar gauge

• Orientation: Horizontal

• Unit: Percent (0-100)

• Color scheme: From thresholds (by value)

• Thresholds: Base (verde), 50 (amarelo), 80 (vermelho)

---

• Painel 2: CPU %

• Query: container_cpu_percent

• Legend: {{container}}

• Type: Time series

• Unit: Percent (0-100)

---

• Painel 3: Memória

• Query: container_memory_bytes

• Legend: {{container}}

• Type: Bar gauge

• Orientation: Horizontal

• Display mode: Retro LCD

• Unit: bytes (IEC)

• Color scheme: From thresholds (by value)

• Thresholds: Base (verde), 500000000 (amarelo), 1500000000 (vermelho)

---

• Painel 4: Memória

• Query: container_memory_bytes

• Legend: {{container}}

• Type: Time series

• Unit: bytes (IEC)

---

• Painel 5: Tráfego de rede

• Query: rate(container_network_bytes_total[1m])

• Legend: {{container}}

• Type: Time series

• Unit: bytes/sec (IEC)

---

Depois de adicionar, salve o dashboard e configure o posicionamento dos painéis como preferir.

Dashboard de monitoramento detalhado dos containers

Você pode comparar as métricas obtidas abrindo o Docker Desktop e inspecionando os containers. A diferença é que aqui, no Grafana, as métricas ficam sob controle e centralizadas em um único dashboard de monitoramento.

Vamos experimentar usar os containers para ver os resultados do monitoramento?

Para começar, interrompa o container analise-sentimentos-consumer, remova-o e suba-o em seguida:

docker stop analise-sentimentos-consumer-container
docker rm analise-sentimentos-consumer-container
docker run -d --name analise-sentimentos-consumer-container --network minharede analise-sentimentos-consumer

Esse container, ao ser inicializado pela primeira vez, carrega modelos pré-treinados do BERT da rede. Note como há um aumento repentino em consumo de CPU e tráfego de rede. Uma vez carregado, o container permanece com 1,5 GB de memória RAM sendo ocupada.

Agora vá até a pasta do chatbot, ative o ambiente conda e use um pouquinho:

conda activate chatbot
python app.py

Analise as métricas dos diferentes containers envolvidos (consumer, broker) e veja se elas se alteram.

Dica: você consegue filtrar os gráficos nos painéis clicando na legenda. Para filtrar múltiplos containers, clique com o shift pressionado.

Vamos testar o servidor web configurado em container único (nginx + wsgi no mesmo container). Abra o navegador no endereço:

http://127.0.0.1:8080/cadastro.html

E use a interface. Observe as métricas do respectivo container. Faça o mesmo no endereço:

http://127.0.0.1:8081/cadastro.html

E veja como agora os containers que hospedam o nginx e wsgi respondem individualmente.

Assim que estiver satisfeito, exporte o novo dashboard em formato JSON e configure novamente no Dockerfile.

Exercitando os containers pra valer

O problema com esses testes é que eles não chegam a "judiar" do nosso processador. Claro, isso vai depender da máquina em questão, mas é difícil estimar a capacidade de processamento de nossa solução realizando testes manuais e clicando feito doido nos botões, não é mesmo?

Vamos tentar uma solução um pouco mais poderosa para isso.

Uma ferramenta bastante utilizada para testes de carga é o k6. Com ela, conseguimos simular vários usuários acessando nossa aplicação ao mesmo tempo, gerando carga de verdade — e aí sim veremos nossos containers "sofrendo" no Grafana. O k6 executa os testes de forma altamente eficiente, utilizando um modelo baseado em eventos, o que permite simular milhares de usuários com baixo consumo de recursos.

Criando um teste simples

O k6 usa scripts em JavaScript para definir o comportamento dos testes.

Crie uma pasta em um local qualquer, e um arquivo chamado load-test.js:

import http from 'k6/http';
import { sleep, check } from 'k6';

export const options = {
    vus: 10, // número de usuários virtuais
    duration: '30s', // duração do teste
};

const jsonContentType = { headers: { 'Content-Type': 'application/json' } };
const produto1 = JSON.stringify({ descricao: "Boneca de pano confecionada com botões de plástico e cabelo feito de lã coletada de ovelhas dos alpes suícos. Vem embalada em um saco reutilizável feito de tecido reciclado a partir de fibras de coco coletadas dos manguezais." });
const categoria1 = "brinquedo";
const produto2 = JSON.stringify({ descricao: "Uma coleção incrível de livros de história clássica da Grécia Antiga, contando toda a história da mitologia, desde os mitos de Gaia e Cronos até os heróis. Vale a pena ter em sua coleção." });
const categoria2 = "livro";
const produto3 = JSON.stringify({ descricao: "halo" });
const categoria3 = "game";


// Essa função simula um usuário visitando a página de cadastro e fazendo requisições para a API de predição de categoria
export default function () {


    // Página inicial de cadastro, acessando direto pelo nginx no container dedicado
    http.get('http://my-custom-nginx-container/cadastro.html');

    // API de predição de categoria, acessando por meio do nginx
    const res1 = http.post(
        'http://my-custom-nginx-container/api/predizer_categoria',
        produto1,
        jsonContentType
    );

    // Vamos ver se a resposta veio certa
    const body1 = res1.json();
    check(res1, {
        'status é 200': (r) => r.status === 200,
        'categoria certa': () => body1.categoria === categoria1,
    });

    // API de predição de categoria, acessando diretamente o container do wsgi, sem passar pelo nginx
    const res2 = http.post(
        'http://wsgi-app-container:5000/predizer_categoria',
        produto2,
        jsonContentType
    );

    // Vamos ver se a resposta veio certa
    const body2 = res2.json();
    check(res2, {
        'status é 200': (r) => r.status === 200,
        'categoria certa': () => body2.categoria === categoria2,
    });


    // Página inicial de cadastro, acessando pelo container unico com nginx e wsgi juntos
    http.get('http://http-api-classificacao-produtos-container-unico-container/cadastro.html');
    // API de predição de categoria, acessando por meio do nginx
    const res3 = http.post(
        'http://http-api-classificacao-produtos-container-unico-container/api/predizer_categoria',
        produto3,
        jsonContentType
    );
    const body3 = res3.json();

    // Vamos ver se a resposta veio certa
    check(res3, {
        'status é 200': (r) => r.status === 200,
        'categoria certa': () => body3.categoria === categoria3,
    });

    sleep(1);
}

O que isso faz?

• Simula 10 usuários simultâneos

• Cada um faz requisições por 30 segundos

• A cada requisição, espera 1 segundo antes de repetir

Executando o teste

Basta rodar:

docker run --rm -i --network minharede grafana/k6 run - < load-test.js

Você verá algo assim no terminal:

running (30.0s), 10/10 VUs, 300 complete and 0 interrupted iterations

Enquanto isso, vá até o Grafana e observe:

• CPU subindo

• Memória sendo utilizada

• Tráfego de rede aumentando

Agora sim estamos colocando o sistema à prova.

Vamos deixar a coisa mais interessante. Aumente a quantidade de vus (usuários virtuais para 50), aumente o tempo de teste para 1 minuto e diminua o tempo de espera entre cada execução:

import http from 'k6/http';
import { sleep, check } from 'k6';

export const options = {
+    vus: 50, // número de usuários virtuais
+    duration: '1m', // duração do teste
};

   ...

    sleep(0.1);
}

Vamos aumentar ainda mais a carga, simulando chamadas realmente em paralelo dentro do mesmo usuário. Para isso, podemos usar o http.batch. Vamos aproveitar e aumentar ainda mais a carga de usuários e tempo entre as execuções. E já que é pra judiar, vamos escolher um único container para sofrer com a pressão.

Faça isso em um novo arquivo, chamado load-test-batch.js:

import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
    vus: 100,
    duration: '1m',
};

const jsonContentType = { headers: { 'Content-Type': 'application/json' } };

const produto1 = JSON.stringify({
    descricao: "Boneca de pano confecionada com botões de plástico e cabelo feito de lã coletada de ovelhas dos alpes suícos. Vem embalada em um saco reutilizável feito de tecido reciclado a partir de fibras de coco coletadas dos manguezais."
});

const produto2 = JSON.stringify({
    descricao: "Uma coleção incrível de livros de história clássica da Grécia Antiga, contando toda a história da mitologia, desde os mitos de Gaia e Cronos até os heróis. Vale a pena ter em sua coleção."
});

const produto3 = JSON.stringify({
    descricao: "halo"
});

export default function () {

    http.batch([
        // Container único (nginx + wsgi)
        ['GET', 'http://http-api-classificacao-produtos-container-unico-container/cadastro.html'],
        ['POST', 'http://http-api-classificacao-produtos-container-unico-container/api/predizer_categoria', produto1, jsonContentType],
        ['POST', 'http://http-api-classificacao-produtos-container-unico-container/api/predizer_categoria', produto2, jsonContentType],
        ['POST', 'http://http-api-classificacao-produtos-container-unico-container/api/predizer_categoria', produto3, jsonContentType]
    ]);

    sleep(0.01);
}

Ao executar, não esqueça de passar o novo arquivo:

docker run --rm -i --network minharede grafana/k6 run - < load-test-batch.js

Alertas automáticos

Antes de encerrar essa seção, vamos configurar um alerta automático para sermos avisados sempre que algum container estiver consumindo muita CPU.

No contexto de monitoramento com ferramentas como o Grafana, um alerta é uma regra que observa continuamente uma métrica (como uso de CPU, memória ou tempo de resposta) e avalia se ela atende a uma determinada condição. Por exemplo, um alerta pode ser configurado para verificar se o uso de CPU ultrapassa 60%. Essa verificação não acontece apenas uma vez, mas sim em intervalos regulares, definidos pelo evaluation group, garantindo que o sistema esteja sempre sendo monitorado.

Os alertas possuem estados, que representam o momento atual da avaliação. O estado Normal (OK) indica que tudo está dentro do esperado, sem nenhuma condição de risco detectada. Quando a métrica começa a violar a regra, o alerta entra em estado Pending, que funciona como um “período de confirmação”: a condição precisa permanecer verdadeira por um certo tempo antes de ser considerada um problema real. Isso evita falsos positivos causados por picos momentâneos. Se a condição persistir, o alerta passa para o estado Firing (ativo), indicando que o problema foi confirmado e precisa de atenção.

Já o conceito de notificação é separado do alerta em si. Enquanto o alerta detecta o problema, a notificação é responsável por comunicar que algo aconteceu. Isso pode incluir o envio de e-mails, mensagens em Slack, chamadas de webhook ou integração com outros sistemas. Em outras palavras, o alerta decide se há um problema, e a notificação decide como e para quem essa informação será enviada.

Essa separação traz flexibilidade: um mesmo alerta pode gerar notificações diferentes dependendo do contexto, e múltiplos alertas podem compartilhar o mesmo canal de notificação. Assim, o sistema de monitoramento se torna mais organizado, escalável e fácil de manter.

A primeira coisa que precisaremos fazer é configurar um ponto de contato que envia notificações pelo Discord. Existem muitas outras opções, como E-mail, Google, Teams, Slack, ou mesmo a possibilidade de criar seu próprio webhook customizado.

No menu Alerting, acesse Contact points e crie um novo.

Escolha o nome MLP Discord Server, e a opção Discord.

Para que as notificações sejam enviadas, é preciso informar o webhook do Discord. Isso pode ser configurado acessando as configurações de um canal no Discord e acessando o menu Integrations -> Webhooks.

Copie a URL do webhook e cole no Grafana, no campo correspondente.

Vamos deixar as outras opções inalteradas. Se quiser, teste o contato com o botão Test antes de salvar e veja se a mensagem chegou no Discord.

Agora vamos criar nossa regra de alerta. Dá pra fazer isso pelo menu Alerting -> Alert rules, mas um jeito mais fácil de fazer isso é reaproveitando uma consulta já existente em algum painel. Como já temos um painel que monitora CPU, vamos fazer desse jeito.

Vá até o painel CPU % (qualquer um dos dois), clique nos três pontinhos no canto dele, e escolha New alert rule. O Grafana já irá inicializar uma nova regra com nome e query preenchidos a partir do que está no painel.

Agora configure os seguintes parâmetros para o alerta:

• WHEN QUERY: IS ABOVE: 60 (o alerta será gerado se o container estiver usando mais do que 60% de CPU)

• Folder: Infraestrutura / Métricas básicas (uma espécie de "namespace" de alertas)

• Evaluation group: fast-check (um agrupamento que define quando e com que frequência os alertas são avaliados)

• Pending period: 30s

• Keep firing for: 0s

• Contact point: MLP Discord Server

Os campos "Folder" e "Evaluation group" são importantes para organização e gerenciamento. Com muitos alertas, a tendência é a configuração ficar bastante complexa.

Pronto, já pode salvar, as demais configurações não iremos mexer.

Antes de testar, vamos fazer um último ajuste. Acesse Notification policies e edite a política padrão para que as notificações cheguem mais rapidamente. O normal é o Grafana ser mais conservador e evitar notificações repetidas em intervalos muito curtos. Deixe assim:

Em Timing options:

• Group wait: 5s

• Group interval: 30s

• Repeat interval: 1m

Isso não é muito recomendado, pois irá fazer com que o Grafana fique gerando notificações o tempo todo. Mas para fins didáticos, queremos ver as notificações, portanto é necessário.

Depois de salvar, é hora de testar. Execute mais uma vez o k6 com as últimas configurações que fizemos e você deve visualizar os alertas chegando no Discord, no canal configurado. Assim que os testes terminarem, você deve receber um alerta de que a situação foi normalizada.

Agora vamos exportar tudo para provisionar no Dockerfile

Crie um arquivo, na pasta grafana, chamado alerting.yml.

Acesse Alerting -> Notification policies -> clique em More -> Export

Copie o conteúdo YAML e cole em alerting.yml

Acesse Alerting -> Contact points -> -> clique em Export all

Copie o conteúdo YAML e cole em alerting.yml (cuidado para não repetir a primeira linha)

Acesse Alerting -> Alert rules -> -> clique em Export rules

Copie o conteúdo YAML e cole em alerting.yml (cuidado para não repetir a primeira linha)

No final, você deverá ter um arquivo alerting.yml parecido com este:

apiVersion: 1

contactPoints:

(... detalhes dos contact points ...)

groups:

(... detalhes das regras de alerta ...)

policies:

(... detalhes da política de notificação ...)

Agora edite o Dockerfile:

FROM grafana/grafana

# Copy datasource config
COPY prometheus.yml /etc/grafana/provisioning/datasources/prometheus.yml

# Copy dashboard provider config
COPY dashboards.yml /etc/grafana/provisioning/dashboards/dashboards.yml

# Copy dashboards
COPY geral.json /var/lib/grafana/dashboards/geral.json
COPY detalhes.json /var/lib/grafana/dashboards/detalhes.json

+# Copy alerting rules
+COPY alerting.yml /etc/grafana/provisioning/alerting/alerting.yml

Interrompa o container, reconstrua a imagem e suba novamente, e veja como o Grafana já terá os alertas configurados corretamente.

Considerações finais

Nesta seção vimos em detalhes como utilizar Prometheus e Grafana, em conjunto com um exporter, para monitorar uma infraestrutura baseada em containers. Coletamos métricas básicas, além do status de cada container. Também fizemos alguns testes para exercitar cada container e ver como o Grafana pode nos ajudar a monitorar tudo de perto, inclusive com notificações em tempo real.

Como exercício, tente fazer novos alertas, para detectar quando os containers deixam de rodar (usando a métrica container_up, por exemplo). Tente também criar novas métricas e alertas que coletam e monitoram coisas como:

• acesso a disco (leitura + escrita)

• percentual de memória do container livre

• espaço em disco disponível

Nota sobre o desenvolvimento do material

O conteúdo desta seção contou com o apoio do ChatGPT como ferramenta auxiliar na estruturação de explicações, revisão de conceitos e refinamento técnico. Todas as decisões de conteúdo, exemplos e direcionamento didático foram conduzidas pelo autor.