APIs Monitor

Monitor leve e extensível para checar serviços HTTP e filas do RabbitMQ em intervalos definidos (cron) e enviar alertas via WhatsApp (Evolution API). Projetado para rodar em contêiner, com persistência simples de estado para evitar alertas repetidos.

Visão Geral

• Checagens: http (status/latência/conteúdo) e rabbitmq_queue (ready/unacked/consumidores).
• Agendamento: cron por checagem (ex.: */1 * * * *).
• Notificações: WhatsApp via Evolution API (com apikey e/ou Bearer).
• Persistência: arquivo JSON com últimos estados em data/monitor_state.json.
• TZ: América/São Paulo, com supressão opcional de alertas em horário de silêncio.

Requisitos

• Docker e Docker Compose (recomendado), ou
• Python 3.11+ e pip (execução local).

Subindo com Docker Compose (recomendado)

1. Copie o exemplo de variáveis e ajuste:

cp .env-example .env

Edite .env e preencha:

• EVOLUTION_BASE, EVOLUTION_INSTANCE, EVOLUTION_NUMBER, EVOLUTION_API_KEY (ou use bearer_token, ver seção Notificações).
• RABBIT_* conforme seu RabbitMQ (URL do management, usuário/senha, vhost).
• Adicione também no .env a URL de health da sua API principal: MAIN_APP_API_URL=https://sua-api/health.

2. Ajuste config.yaml se necessário (ver exemplos abaixo).

3. Crie a pasta de dados local (persistência do estado):

mkdir -p data

4. Suba os serviços:

docker compose up -d

• O serviço monitor monta ./config.yaml em /app/config.yaml e persiste estado em ./data.
• O Compose inclui, opcionalmente, um Postgres e um container evolution_api para testes locais. Se você já possui Evolution API externo, pode removê-los/comentá-los.

5. Logs do monitor:

docker compose logs -f monitor

Execução Local (sem Docker)

1. Python 3.11+ e venv:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Variáveis de ambiente: crie um .env (padrão é lido automaticamente) a partir do exemplo e ajuste conforme necessário. Alternativamente, exporte no shell.

3. Execute:

python app.py

4. Estado: por padrão salva em STATE_FILE=/app/data/monitor_state.json. Localmente, você pode definir, por exemplo:

export STATE_FILE=./data/monitor_state.json
mkdir -p ./data

Variáveis de Ambiente

As variáveis são interpoladas dentro do config.yaml usando a sintaxe ${VAR} ou ${VAR:-default}. Se uma variável faltar, o programa encerra com erro informando <MISSING:VAR>.

Principais variáveis (ver .env-example):

• EVOLUTION_BASE: base da Evolution API, ex.: http://localhost:8080.
• EVOLUTION_INSTANCE: chave/instance key usada na rota do Evolution.
• EVOLUTION_NUMBER: número WhatsApp de destino no formato internacional (ex.: 5531999999999).
• EVOLUTION_API_KEY: apikey para Evolution API (alternativa/adição ao bearer_token).
• RABBIT_MGMT_URL, RABBIT_USER, RABBIT_PASS, RABBIT_VHOST: acesso ao Management API do RabbitMQ.
• MAIN_APP_API_URL: URL de health da sua aplicação (usada no exemplo de check HTTP).
• STATE_FILE (opcional): caminho do JSON de estado; padrão: /app/data/monitor_state.json.

Arquivo de Configuração (config.yaml)

Trecho real do projeto (com variáveis interpoladas do .env):

notifier:
  evolution_api_base: "${EVOLUTION_BASE}"
  instance_key: "${EVOLUTION_INSTANCE}"
  to_number: "${EVOLUTION_NUMBER}"
  api_key: "${EVOLUTION_API_KEY}"
  # bearer_token: "${EVOLUTION_BEARER_TOKEN}"        # opcional
  # quiet_hours: { start: "22:00", end: "07:00" }    # opcional

checks:
  - name: fila-meli-sync
    type: rabbitmq_queue
    schedule: "*/1 * * * *"
    rabbit:
      mgmt_url: "${RABBIT_MGMT_URL}"
      user: "${RABBIT_USER}"
      pass: "${RABBIT_PASS}"
      vhost: "${RABBIT_VHOST}"
      queue: "meli-sync-publication-queue"
    thresholds:
      max_ready: 1000
      max_unacked: 200
      min_consumers: 1
    severity: high

  - name: fila-integrated-publication-picture-queue
    type: rabbitmq_queue
    schedule: "*/1 * * * *"
    rabbit:
      mgmt_url: "${RABBIT_MGMT_URL}"
      user: "${RABBIT_USER}"
      pass: "${RABBIT_PASS}"
      vhost: "${RABBIT_VHOST}"
      queue: "integrated-publication-picture-queue"
    thresholds:
      max_ready: 1000
      max_unacked: 200
      min_consumers: 1
    severity: high

  - name: health-api
    type: http
    schedule: "*/1 * * * *"
    request:
      url: "${MAIN_APP_API_URL}"
      method: GET
      timeout_ms: 2000
      verify_tls: true
    expect:
      status: 200
      max_latency_ms: 1000
      contains: "OK"
    severity: high

Dicas:

• Use ${VAR:-valor_padrao} para defaults (ex.: url: "${HEALTH_URL:-https://exemplo/health}").
• bootstrap_silent: true (padrão) evita alerta na primeira leitura; defina false para alertar desde o primeiro ciclo.

Agendamento e Comportamento

• Cron: cada checagem define schedule no formato crontab; o timezone é America/Sao_Paulo.
• Estados: a transição de estado (UP/WARN/DOWN) dispara notificação; estados iguais apenas logam.
• Severidade: por padrão mapeia UP=info, WARN=medium, DOWN=high. Pode sobrescrever por checagem via severity.
• Quiet Hours: se definido em notifier.quiet_hours, suprime mensagens não críticas fora do horário; DOWN (ou severity: high) ainda notifica.

Notificações (Evolution API / WhatsApp)

• Endpoint usado: POST {evolution_api_base}/message/sendText/{instance_key}.
• Autenticação suportada:
  • Header apikey: ${EVOLUTION_API_KEY} e/ou
  • Header Authorization: Bearer ${EVOLUTION_BEARER_TOKEN} (chave bearer_token em notifier).
• Payloads tentados: { number, text } e { to, text } (compatibilidade entre versões da Evolution API).
• Texto: título em negrito + detalhes (ex.: "[DOWN] health-api" e métricas/erros).
• Para usar o container evolution_api local do Compose, consulte a documentação da imagem para criar/parear a instância e obter instance_key e chave de acesso. Ajuste EVOLUTION_BASE e credenciais conforme necessário.

Checks Disponíveis

• type: http

  • request.url: URL alvo; method (GET/POST/...), headers, timeout_ms, verify_tls.
  • Corpo: um dentre json, data ou body; files é suportado.
  • expect.status: código HTTP esperado.
  • expect.max_latency_ms: tempo máximo (ms); acima disso marca DOWN; acima de 80% já marca WARN.
  • expect.contains: string obrigatória na resposta; se expect.regex: true, avalia como regex.

• type: rabbitmq_queue

  • rabbit.mgmt_url: URL do Management API (ex.: http(s)://host:15672).
  • rabbit.user / rabbit.pass / rabbit.vhost / rabbit.queue.
  • rabbit.verify_tls: opcional; true por padrão.
  • thresholds.max_ready / max_unacked / min_consumers.
  • Severidade DOWN se consumidores abaixo do mínimo; senão WARN quando thresholds excedidos.

Logs, Estado e Saída

• Logs em stdout com nível INFO por padrão (ajuste via orquestrador ou redirecionamento).
• Estado persistido em JSON atômico em STATE_FILE (padrão: /app/data/monitor_state.json).
• Para resetar histórico (forçar novo bootstrap), apague o arquivo de estado com o serviço parado.

Troubleshooting

• Erro "Config contém variáveis ausentes": faltam variáveis usadas em config.yaml (aparecem como <MISSING:VAR>). Revise seu .env.
• Notificação não chega: verifique reachability do EVOLUTION_BASE, apikey/bearer_token, e se o instance_key está válido/pareado.
• Erros de TLS: defina verify_tls: false no check (não recomendado em produção) ou ajuste certificados.
• RabbitMQ 401/404: confirme mgmt_url, permissões do usuário, vhost e nome da fila.

Extensão (novos checks)

• Adicione uma função check_* em app.py que retorne (status, detail).
• Registre a função em CHECK_HANDLERS (ex.: "meu_tipo": check_meu_tipo).
• Crie um item em checks no config.yaml com type: meu_tipo e os campos necessários.

Licença

• Este projeto está licenciado sob Apache License 2.0 (veja LICENSE).