Skip to content

README.md

Latest commit

 

History

History
199 lines (159 loc) · 8.05 KB

README.md

File metadata and controls

199 lines (159 loc) · 8.05 KB

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.

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

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

mkdir -p data
  1. 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.
  1. 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

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

  2. Execute:

python app.py
  1. 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).