Documentacao - Swarm Monitor

O que e o Swarm Monitor?

O Swarm Monitor e um sistema de monitoramento desenvolvido especificamente para ambientes Docker Swarm. Ele funciona como um "vigilante" que observa constantemente todos os seus servicos (aplicacoes) rodando no servidor.

                Em termos simples: Imagine que voce tem varias aplicacoes rodando no seu servidor (como um site, um banco de dados, uma API, etc). O Swarm Monitor fica de olho em todas elas 24 horas por dia, 7 dias por semana, e te avisa (ou tenta consertar sozinho) quando algo da errado.
            

Principais Funcionalidades

Monitoramento em Tempo Real: Ve o status de todos os servicos instantaneamente
Auto-Recuperacao: Tenta reiniciar automaticamente servicos que cairam
Alertas via Webhook: Envia notificacoes quando algo nao pode ser resolvido automaticamente
Historico de Eventos: Registra tudo que acontece para voce consultar depois
Controle Manual: Permite reiniciar ou escalar servicos diretamente pelo painel

Como Funciona?

O sistema opera em um ciclo continuo de verificacao. A cada 30 segundos (configuravel), ele executa as seguintes etapas:

1

Verifica Checa todos os servicos

→

2

Analisa Identifica problemas

→

3

Recupera Tenta auto-corrigir

→

4

Notifica Envia webhook se falhar

Detalhamento do Processo

Verificacao: O sistema consulta o Docker Swarm e obtem informacoes de todos os servicos - quantas replicas estao rodando, quantas deveriam estar rodando, etc.
Analise: Compara o estado atual com o estado desejado. Se um servico deveria ter 2 replicas mas so tem 1, isso e um problema.
Recuperacao: Se encontrar um servico critico (0 replicas rodando), tenta reinicia-lo automaticamente usando o comando de "force update" do Docker.
Notificacao: Se apos 3 tentativas o servico continuar com problema, envia um webhook para voce tomar uma acao manual.

Entendendo o Dashboard

O dashboard e dividido em varias areas, cada uma com uma funcao especifica:

Cabecalho

No topo da pagina voce encontra:

Titulo: "Swarm Monitor" - identificacao do sistema
Ultima Atualizacao: Mostra quando os dados foram atualizados pela ultima vez
Indicador de Status: Um ponto verde pulsando indica que o sistema esta funcionando normalmente

Cards de Estatisticas

Logo abaixo do cabecalho, voce ve 4 cards coloridos mostrando:

Saudaveis (verde): Quantidade de servicos funcionando perfeitamente
Alertas (amarelo): Servicos com problemas parciais (ex: 1 de 2 replicas rodando)
Criticos (vermelho): Servicos completamente fora do ar (0 replicas)
Nodes (roxo): Quantidade de servidores no cluster

Lista de Servicos

A area principal mostra todos os servicos. Cada linha contem:

Indicador colorido: Mostra visualmente o status (verde/amarelo/vermelho)
Nome do servico: O nome como aparece no Docker Swarm
Imagem: Qual imagem Docker esta sendo usada
Replicas: Formato "rodando/desejado" (ex: 1/1 significa 1 rodando de 1 desejado)

                Dica: Clique em qualquer servico para abrir um modal com mais detalhes e opcoes de acao (reiniciar, escalar).
            

Painel de Alertas

Na lateral direita, voce ve os ultimos eventos do sistema - quando um servico caiu, quando foi recuperado, erros, etc. Os alertas sao coloridos por gravidade.

Configuracao de Webhook

Tambem na lateral, ha um formulario para configurar webhooks. Mais detalhes na secao especifica.

Nodes do Cluster

Mostra informacoes sobre os servidores que fazem parte do seu Docker Swarm, incluindo hostname, status e se e o lider do cluster.

Status dos Servicos

Cada servico pode estar em um de tres estados:

Saudavel (Healthy) Todas as replicas estao rodando

Alerta (Warning) Algumas replicas estao fora

Critico (Critical) Nenhuma replica rodando

Exemplos Praticos

1/1 = Saudavel: O servico deveria ter 1 replica e tem 1 rodando. Tudo OK!
1/2 = Alerta: O servico deveria ter 2 replicas mas so 1 esta rodando. Problema parcial.
0/1 = Critico: O servico deveria ter 1 replica mas nenhuma esta rodando. Servico fora do ar!
2/2 = Saudavel: O servico deveria ter 2 replicas e tem 2 rodando. Perfeito!

                Importante: Um servico com status "Critico" significa que sua aplicacao esta FORA DO AR e usuarios nao conseguem acessa-la. O sistema tentara recuperar automaticamente, mas se nao conseguir, voce sera notificado via webhook.
            

Sistema de Auto-Recuperacao

O sistema de auto-recuperacao e um dos recursos mais importantes do Swarm Monitor. Ele funciona assim:

Quando a Auto-Recuperacao e Acionada?

A auto-recuperacao so e acionada quando um servico esta em estado CRITICO (0 replicas rodando). Servicos em estado de "alerta" (parcialmente funcionando) nao sao reiniciados automaticamente.

Como Funciona o Processo?

Deteccao: O sistema detecta que um servico tem 0 replicas rodando
Primeira Tentativa: Envia um comando de "force update" para o Docker reiniciar o servico
Aguarda: Espera 30 segundos e verifica novamente
Segunda Tentativa: Se ainda estiver com problema, tenta novamente
Terceira Tentativa: Uma ultima tentativa e feita
Webhook: Se apos 3 tentativas o servico continuar critico, envia webhook

                Cooldown: Apos 3 tentativas falhas, o sistema aguarda 5 minutos antes de tentar novamente. Isso evita ficar tentando infinitamente um servico que tem um problema mais grave.
            

O que o "Force Update" Faz?

O comando de force update no Docker Swarm faz com que o servico seja reimplantado. Na pratica, isso:

Para os containers atuais (se houver algum travado)
Baixa novamente a imagem (se necessario)
Inicia novos containers

                Resultado: Em muitos casos, especialmente quando o problema foi um travamento temporario ou falta de memoria, o force update resolve o problema e o servico volta a funcionar normalmente.
            

Servicos Excluidos

O proprio Swarm Monitor esta excluido da auto-recuperacao para evitar loops infinitos. Se o monitor cair, ele nao tentara se reiniciar sozinho.

Sistema de Webhooks

Webhooks sao uma forma de o sistema "avisar" outros sistemas quando algo acontece. E como um mensageiro automatico.

O que e um Webhook?

Um webhook e uma requisicao HTTP (geralmente POST) que o sistema envia para uma URL quando um evento ocorre. E a forma mais comum de integrar sistemas diferentes.

                Analogia: Pense no webhook como um carteiro. Quando algo importante acontece (uma carta chega), o carteiro (webhook) leva essa informacao ate a sua casa (outro sistema, como n8n, Zapier, etc).
            

Quando um Webhook e Disparado?

O Swarm Monitor dispara um webhook em uma situacao especifica:

                Evento: recovery_failed

                Disparado quando um servico nao conseguiu ser recuperado apos 3 tentativas automaticas. Isso significa que a intervencao humana e necessaria.

Como Configurar o Webhook

No dashboard, localize a secao "Configuracao de Webhook" na lateral direita
No campo "URL do Webhook", cole a URL que ira receber as notificacoes
Certifique-se que a opcao "Webhook Habilitado" esta marcada
Clique em "Salvar"
Use o botao "Testar" para verificar se esta funcionando

Formato do Webhook Enviado

Quando um webhook e disparado, ele envia um JSON com as seguintes informacoes:

{
  "event_type": "recovery_failed",
  "timestamp": "2026-01-20T15:30:00.000000",
  "source": "swarm-monitor",
  "data": {
    "service_name": "minha_aplicacao",
    "message": "Servico nao pode ser recuperado apos 3 tentativas",
    "requires_manual_intervention": true,
    "service_info": {
      "replicas": "0/1",
      "status": "critical",
      "image": "minha-imagem:latest"
    }
  }
}
            

Exemplos de Uso com Ferramentas Populares

n8n

Crie um novo workflow no n8n
Adicione um trigger "Webhook"
Copie a URL gerada (algo como: https://seu-n8n.com/webhook/xxx)
Cole essa URL no Swarm Monitor
No n8n, adicione acoes como: enviar email, mensagem no Telegram, SMS, etc.

Zapier

Crie um novo Zap
Escolha "Webhooks by Zapier" como trigger
Selecione "Catch Hook"
Copie a URL fornecida e cole no Swarm Monitor
Configure acoes como notificacoes por email, Slack, etc.

Make (Integromat)

Crie um novo cenario
Adicione um modulo "Webhooks" > "Custom webhook"
Copie a URL gerada
Cole no Swarm Monitor
Adicione modulos para enviar alertas

Exemplo de Automacao: Alerta no Telegram

Um uso comum e criar uma automacao que envia uma mensagem no Telegram quando um servico cai:

Configure o webhook do Swarm Monitor para apontar para o n8n
No n8n, quando receber o webhook, extraia o nome do servico
Envie uma mensagem formatada para um grupo do Telegram

// Exemplo de mensagem que pode ser enviada:

🚨 ALERTA: Servico Fora do Ar

Servico: evolution_evolution
Status: CRITICO (0/1 replicas)
Hora: 20/01/2026 15:30

O sistema tentou recuperar 3 vezes sem sucesso.
Intervencao manual necessaria!
            

API do Sistema

O Swarm Monitor possui uma API REST que permite consultar informacoes e executar acoes programaticamente.

Endpoints Disponiveis

Metodo	Endpoint	Descricao
GET	`/api/status`	Retorna status completo do sistema (servicos, nodes, alertas)
GET	`/api/services`	Lista todos os servicos com detalhes
GET	`/api/alerts`	Retorna historico de alertas
GET	`/api/webhooks`	Informacoes sobre webhooks enviados
GET	`/api/config`	Configuracoes atuais do sistema
GET	`/health`	Health check (verificar se o sistema esta online)
POST	`/api/service/{nome}/restart`	Reinicia um servico especifico
POST	`/api/service/{nome}/scale`	Altera a quantidade de replicas de um servico
POST	`/api/webhook/config`	Configura URL e status do webhook
POST	`/api/webhook/test`	Dispara um webhook de teste

Exemplos de Uso

# Verificar status do sistema
curl https://info.viajandoalem.com.br/api/status

# Reiniciar um servico
curl -X POST https://info.viajandoalem.com.br/api/service/meu_servico/restart

# Escalar um servico para 3 replicas
curl -X POST https://info.viajandoalem.com.br/api/service/meu_servico/scale \
  -H "Content-Type: application/json" \
  -d '{"replicas": 3}'

# Configurar webhook
curl -X POST https://info.viajandoalem.com.br/api/webhook/config \
  -H "Content-Type: application/json" \
  -d '{"url": "https://meu-n8n.com/webhook/xxx", "enabled": true}'
            

Configuracoes do Sistema

O sistema pode ser configurado atraves de variaveis de ambiente no arquivo de deploy. Aqui estao todas as opcoes disponiveis:

CHECK_INTERVAL

Intervalo de Verificacao
De quantos em quantos segundos o sistema verifica os servicos

Padrao: 30 segundos

AUTO_RECOVERY_ENABLED

Habilitar Auto-Recuperacao
Define se o sistema deve tentar recuperar servicos automaticamente

Padrao: true (habilitado)

MAX_RECOVERY_ATTEMPTS

Maximo de Tentativas
Quantas vezes tentar recuperar um servico antes de enviar webhook

Padrao: 3 tentativas

RECOVERY_COOLDOWN

Tempo de Espera (Cooldown)
Tempo em segundos para aguardar apos esgotar as tentativas

Padrao: 300 segundos (5 minutos)

WEBHOOK_URL

URL do Webhook
URL para onde enviar as notificacoes (tambem configuravel pelo dashboard)

Padrao: vazio (nao configurado)

WEBHOOK_ENABLED

Webhook Habilitado
Se os webhooks devem ser enviados ou nao

Padrao: true (habilitado)

EXCLUDED_SERVICES

Servicos Excluidos
Lista de servicos que nao devem ser auto-recuperados (separados por virgula)

Padrao: swarm-monitor

Perguntas Frequentes (FAQ)

O que acontece se o proprio Swarm Monitor cair?

O Swarm Monitor roda como um servico do Docker Swarm, entao o proprio Docker tentara reinicia-lo automaticamente se ele cair. Alem disso, o monitor esta excluido da sua propria auto-recuperacao para evitar loops. Se o monitor ficar offline por muito tempo, voce nao recebera alertas - por isso e importante monitorar tambem o proprio monitor atraves de servicos externos como UptimeRobot ou similares.

Por que um servico esta com status "warning" mas nao esta sendo recuperado?

O sistema de auto-recuperacao so atua em servicos com status "critical" (0 replicas rodando). Servicos em "warning" (algumas replicas rodando) ainda estao parcialmente funcionais, entao o sistema nao interfere. A logica e: se ainda ha replicas rodando, o servico esta atendendo usuarios, entao melhor nao arriscar reiniciar. Nesses casos, recomenda-se investigar manualmente o motivo de algumas replicas nao estarem subindo.

Posso desabilitar a auto-recuperacao para um servico especifico?

Sim! Adicione o nome (ou parte do nome) do servico na variavel de ambiente EXCLUDED_SERVICES. Por exemplo: EXCLUDED_SERVICES=swarm-monitor,meu-servico-especial. Qualquer servico que contenha essas palavras sera ignorado pela auto-recuperacao.

O webhook nao esta sendo enviado. O que pode ser?

Verifique os seguintes pontos:

1. URL configurada: Certifique-se que a URL do webhook esta preenchida corretamente
2. Webhook habilitado: A opcao "Webhook Habilitado" deve estar marcada
3. URL acessivel: A URL precisa ser acessivel a partir do servidor (sem firewall bloqueando)
4. Teste: Use o botao "Testar" para verificar se a conexao funciona
5. Condicoes: O webhook so e enviado apos 3 tentativas falhas de recuperacao

Como sei se um webhook foi enviado com sucesso?

Voce pode verificar de duas formas:

1. Alertas: No painel de alertas, aparece uma mensagem informando se o webhook foi enviado com sucesso ou se houve erro
2. API: Acesse /api/webhooks para ver o historico de webhooks enviados, incluindo status de sucesso/falha

O servico foi reiniciado mas continua caindo. O que fazer?

Se um servico continua caindo mesmo apos reiniciar, o problema provavelmente esta no proprio servico, nao no Docker Swarm. Verifique:

1. Logs: Use "docker service logs nome_do_servico" para ver os logs de erro
2. Recursos: O servidor pode estar sem memoria ou disco
3. Dependencias: O servico pode depender de outro que tambem esta com problema
4. Configuracao: Pode haver erro nas variaveis de ambiente ou volumes

Posso usar o Swarm Monitor em um cluster com varios nodes?

Sim! O Swarm Monitor foi projetado para funcionar em clusters Docker Swarm de qualquer tamanho. Ele roda no node manager e monitora todos os servicos do cluster, independente de em qual node estao executando. O painel de "Nodes" mostra todos os servidores do cluster e seu status.

Como atualizar o Swarm Monitor para uma nova versao?

Para atualizar, siga estes passos:

1. Acesse o servidor via SSH
2. Navegue ate a pasta do projeto: cd /root/swarm-monitor
3. Atualize os arquivos necessarios
4. Faca o rebuild da imagem: docker build -t swarm-monitor:latest .
5. Atualize o servico: docker service update --force swarm-monitor_swarm-monitor

E seguro deixar o Swarm Monitor exposto na internet?

O Swarm Monitor permite acoes administrativas como reiniciar servicos, entao e importante considerar a seguranca:

1. HTTPS: O sistema ja esta configurado para usar HTTPS via Traefik
2. Firewall: Considere restringir acesso por IP se possivel
3. Autenticacao: Para maior seguranca, adicione autenticacao basica no Traefik
4. VPN: Idealmente, acesse apenas via VPN