Script Python para monitorar containers Docker em tempo real

Motivação

Ferramentas ricas de monitoramento às vezes geram muitos falsos positivos em redes ou picos curtos de CPU. O objetivo aqui é simples: monitorar containers em tempo real e disparar alertas apenas quando um recurso permanece anormal por um período "sustentado" (por exemplo, 20s). Além disso, a interface foi otimizada para produção — saída em colunas no terminal, sem barras gráficas custosas.

Principais características

• Saída leve em colunas (nome do container, CPU %, memória em GB, tráfego em B/s).
• Alertas via Telegram com formato claro: cabeçalho + status (ex.: ### DOCKER-MONITOR ###).
• Detecção de anomalia baseada em sustentação: só alerta se o uso ficar acima do threshold por sustained_seconds.
• Cooldown entre alertas (evita spam): configuração via alert_cooldown_minutes.
• Ferramenta de stress-test incluída com modo --paranoid e parada com a tecla S.

Como funciona a detecção (sustained thresholds)

Para cada métrica (CPU, memória e rede) o monitor faz:

1. Verifica se o valor está acima do threshold configurado;
2. Se estiver, registra o instante em que isso começou para o dado container/metric;
3. Se o valor permanecer acima por pelo menos sustained_seconds, e não estiver em cooldown, dispara o alerta;
4. Se o valor cai abaixo do threshold, o temporizador é resetado.

Benefício: picos curtos e ruído de rede não provocam alertas desnecessários — apenas comportamentos persistentes são reportados.

Instalação rápida

python3 -m venv .venv
source .venv/bin/activate
pip install docker requests tqdm

Configuração principal

Edite o arquivo config.json ao lado do script _monitor.py. Exemplo das chaves principais:

{
  "thresholds": {
    "cpu": 50.0,
    "memory_gb": 4.0,
    "network_mbps": 5.0
  },
  "monitoring": {
    "interval_seconds": 10,
    "alert_cooldown_minutes": 5,
    "sustained_seconds": 20
  },
  "telegram": {
    "enabled": true,
    "bot_token": "SEU_BOT_TOKEN",
    "chat_id": "SEU_CHAT_ID"
  }
}

Recomendações

• Use sustained_seconds >= 2 × interval_seconds para evitar decisões baseadas em uma única amostra.
• Teste thresholds em um ambiente de staging antes de aplicar em produção.

Como executar

Rodar o monitor em uma sessão de terminal interativa:

python3 _monitor.py

Você verá uma tabela atualizada a cada iteração, por exemplo:

DOCKER MONITOR — 2025-09-21 14:30:00
CONTAINER                       CPU%   MEM(GB)     NET(B/s)
webapp                          72.50    1.23         12345
db                              15.00    2.50          5432

Formato e envio do alerta

Quando uma condição é considerada sustentada, a mensagem enviada ao Telegram tem este formato:

### DOCKER-MONITOR ###
ALERT webapp: CPU 72.5% (sustained 22s)

Stress test e modo --paranoid

O repositório inclui um utilitário _stressTest.py para gerar carga:

python3 _stressTest.py --url https://httpbin.org/get --requests 200 --concurrency 20

Modo paranoid (usa todos os núcleos CPU):

python3 _stressTest.py --paranoid --max-requests 100 --url https://httpbin.org/get

Durante a execução do stress test, pressione S (maiúsculo ou minúsculo) no terminal para interromper imediatamente o envio de novas requisições.

Executando como serviço (exemplo systemd)

[Unit]
Description=Docker Resource Monitor
After=docker.service
Requires=docker.service

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/monitor
ExecStart=/path/to/python _monitor.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Boas práticas e próximo passos

• Para redes débiles, considere usar média móvel de tráfego em N samples em vez de amostra pontual.
• Adicionar thresholds separados por métrica (ex.: sustained_seconds_cpu, sustained_seconds_net) quando quiser comportamentos diferentes por recurso.
• Enviar alertas periodicamente enquanto a condição persistir (ex.: a cada alert_cooldown_minutes).

Conclusão

Esta ferramenta é pensada para ambientes onde o ruído de monitoramento é um problema — ela reduz falsos positivos exigindo uma condição sustentada antes de alertar. Se quiser, publico em seguida um how-to com exemplos de config.json para diferentes tipos de workloads (web, banco de dados, streaming).