Uptime Kuma: Monitoramento de Webhooks e Portas

10 min de leitura Monitoramento
Uptime Kuma: Monitoramento de Webhooks e Portas

O que é Uptime Kuma e por que ele é essencial

No cenário atual de infraestrutura de TI, a disponibilidade não é apenas uma métrica, é um requisito crítico de negócio. O Uptime Kuma surgiu como uma alternativa moderna, leve e open-source ao Prometheus ou Datadog para cenários que demandam monitoramento simples, mas eficaz. Diferente de ferramentas pesadas de observabilidade, o Uptime Kuma foca na simplicidade: você define um serviço (web, porta TCP, ping, etc.) e ele alerta quando algo sai do ar.

Sua interface é intuitiva, baseada em Docker ou instalação nativa via Node.js, e sua verdadeira força reside no sistema de notificações. Ele suporta dezenas de provedores de alerta, incluindo Telegram, Discord, Slack, Email e até integrações com sistemas enterprise como Grafana, Zabbix e LibreNMS. Neste tutorial, vamos cobrir desde a instalação básica até a configuração avançada de monitoramento de portas TCP e integração de webhooks para automação.

Instalação via Docker (Recomendado)

A maneira mais rápida e isolada de instalar o Uptime Kuma é utilizando o Docker. Isso evita conflitos de dependências do Node.js no seu sistema operacional. Siga os passos abaixo em seu servidor Linux (Ubuntu, Debian, CentOS, etc.).

Crie um diretório para armazenar os dados persistentes do container:

mkdir -p /opt/uptime-kuma
chmod 755 /opt/uptime-kuma

Agora, inicie o container com as seguintes flags. Substitua 3001 pela porta desejada se a 3001 já estiver em uso:

docker run -d --name uptime-kuma \
  -v /opt/uptime-kuma:/app/data \
  -p 3001:3001 \
  louislam/uptime-kuma:1

Acesse http://SEU_IP:3001 em seu navegador. O assistente de instalação pedirá para criar um usuário administrador. Após configurar as credenciais, você terá acesso ao painel principal.

Configurando Monitoramento de Serviços Web (HTTP/HTTPS)

O uso mais comum do Uptime Kuma é monitorar sites e APIs REST. Vamos adicionar nosso primeiro serviço para garantir que um endpoint específico esteja respondendo corretamente.

  1. No painel, clique no botão Add New Monitor.
  2. Campo Type: Selecione HTTP(s).
  3. Campo Name: Dê um nome descritivo, ex: "API Principal" ou "Site Institucional".
  4. Campo URL: Insira o endereço completo, ex: https://api.tudasolucao.com.br/v1/status.
  5. Key Features (Avançado):
    • HTTP Method: Por padrão é GET. Se sua API exigir POST ou PUT, altere aqui.
    • Maximal Response Time: Defina o tempo máximo de resposta aceitável (ex: 2000ms). Se a API demorar mais que isso, será considerada fora do ar.
    • Expected Status Code: Por padrão, espera-se 200. Se sua API retorna 204 ou 201 para sucesso, ajuste este campo para evitar falsos positivos.
  6. Clique em Add.

O Uptime Kuma começará a pingar a URL a cada 60 segundos (padrão). Você pode alterar a frequência de monitoramento nos ajustes do monitor específico para testes mais agressivos ou economia de recursos.

Monitorando Portas TCP e Serviços de Infraestrutura

Muitos profissionais de TI negligenciam o monitoramento de portas. Um serviço pode estar "online" (HTTP 200) mas sua base de dados, Redis ou banco SSH podem estar travados. O Uptime Kuma permite testar a conectividade em nível de transporte (Layer 4).

Para monitorar uma porta TCP:

  1. Clique em Add New Monitor.
  2. No campo Type, selecione TCP.
  3. Name: Ex: "Banco de Dados MySQL" ou "Redis Cache".
  4. Host: O IP ou hostname do servidor. Use 127.0.0.1 se estiver monitorando o próprio servidor onde o Kuma roda, ou o IP interno da sua VPS.
  5. Port: A porta correspondente (ex: 3306 para MySQL, 6379 para Redis, 22 para SSH).
  6. Clique em Add.

O Uptime Kuma tentará estabelecer uma conexão TCP. Se o handshake falhar ou tiver timeout, o serviço é marcado como down. Isso é crucial para detectar problemas de firewall, serviços crashados ou exaustão de conexões no servidor.

Integração com Grafana: Visualização Unificada

O Uptime Kuma possui um recurso nativo de exportação de métricas compatível com o formato do Prometheus. Isso permite que você envie os dados de uptime para um Grafana rodando na sua infraestrutura, criando dashboards personalizados.

Passo 1: Habilitar a API no Uptime Kuma

No menu lateral esquerdo do Uptime Kuma, clique em API Token. Clique em Add New Token, dê um nome e copie o token gerado. Mantenha esta página aberta ou salve o token em um local seguro.

Passo 2: Configurar o Data Source no Grafana

  1. Acesse seu painel do Grafana.
  2. Vá em Configuration > Data Sources.
  3. Clique em Add data source e selecione Prometheus.
  4. No campo URL, insira: http://SEU_IP_KUMA:3001/api/prometheus/metrics
  5. Importante: Role até o final da configuração e ative a opção Basic Auth.
  6. Em Password, cole o Token que você gerou no Passo 1.
  7. Clique em Save & Test. A mensagem "Data source is working" deve aparecer.

Agora, ao criar um painel no Grafana, você pode usar queries Prometheus como uptime_status{monitor_id="1"} para visualizar o histórico de indisponibilidades lado a lado com seus gráficos de CPU e memória.

Alertas via Telegram: Notificações em Tempo Real

Receber alertas por e-mail pode ser lento. Para sysadmins e devs, mensagens instantâneas são vitais. O Uptime Kuma oferece suporte nativo ao Bot API do Telegram.

Passo 1: Criar o Bot no Telegram

  1. Abra o Telegram e busque pelo @BotFather.
  2. Envie o comando /newbot.
  3. Dê um nome ao bot (ex: "Alertas Infra") e um username (deve terminar em _bot, ex: "TodaSolucao_Alerts_bot").
  4. O BotFather fornecerá uma API Token. Copie-a.

Passo 2: Criar o Chat de Destino

Crie um grupo ou canal no Telegram chamado "Alertas". Adicione o bot que você criou como administrador (necessário para enviar mensagens). Depois, envie uma mensagem qualquer no grupo. Precisamos do ID deste chat.

Para encontrar o ID do chat:

  • Crie um bot temporário chamado @GetMyID_bot.
  • Mande uma mensagem no seu grupo de alertas para este bot.
  • Ele responderá com informações sobre a mensagem, incluindo o número após "chat":{"id":-1234567890". Esse é o seu Chat ID (geralmente negativo).

Passo 3: Configurar no Uptime Kuma

  1. No Uptime Kuma, vá em Settings > Notifications.
  2. Clique em Add New Notification.
  3. Type: Selecione Telegram.
  4. Bot Token: Cole a token gerada pelo BotFather.
  5. Chat ID: Cole o ID do grupo/chanal (ex: -1002134567890).
  6. Clique em Test para enviar uma mensagem de teste. Verifique seu Telegram.
  7. Clique em Add.

Agora, ao editar qualquer Monitor, na aba Notification IDs, selecione o Telegram que você acabou de criar. Sempre que o serviço cair, você receberá uma notificação instantânea no celular.

Integração com Discord: Webhooks Simples

Se sua equipe trabalha no Slack ou usa servidores do Discord para comunicação interna, a integração via Webhook é extremamente simples e não requer criação de bots complexos.

  1. No servidor do Discord, clique com o botão direito no canal onde quer receber os alertas (ex: #infra-alerts).
  2. Vá em Edit Channel > Integrations > Create Webhook.
  3. Dê um nome ao webhook e copie a Webhook URL. Ela se parece com: https://discord.com/api/webhooks/1234567890/abcdef...
  4. No Uptime Kuma, vá em Settings > Notifications.
  5. Clique em Add New Notification.
  6. Type: Selecione Discord.
  7. Webhook URL: Cole a URL copiada.
  8. Clique em Test e depois em Add.

O Uptime Kuma enviará embeds formatados com cores (vermelho para down, verde para up), facilitando a identificação visual rápida do problema.

Webhooks Genéricos: Conectando com Zabbix e LibreNMS

Para ambientes enterprise ou setups híbridos, você pode não querer usar os alertas nativos, mas sim integrar o Uptime Kuma a um sistema maior de gestão como Zabbix, LibreNMS ou um script customizado via webhook genérico.

O Uptime Kuma suporta Webhooks. Isso permite que, ao detectar uma falha, ele dispare uma requisição HTTP para o seu sistema de monitoramento principal.

Configurando Webhook Genérico

  1. Vá em Settings > Notifications.
  2. Clique em Add New Notification.
  3. Type: Selecione Webhook.
  4. URL: Insira o endpoint do seu sistema. Exemplo para Zabbix API: http://zabbix.tudasolucao.com.br/zabbix/api_jsonrpc.php.
  5. Method: Geralmente POST.
  6. Headers: Se necessário, adicione headers de autenticação (ex: Content-Type: application/json).
  7. Payload: Você pode usar templates JSON. O Uptime Kuma injeta variáveis como {{monitor.name}}, {{monitor.url}}, {{status}}. Um payload típico para triggerar um item no Zabbix via API seria:
{
    "jsonrpc": "2.0",
    "method": "trigger.create",
    "params": {
        "expression": "{{monitor.name}} is down"
    },
    "auth": "SEU_TOKEN_ZABBIX",
    "id": 1
}

Dica Técnica: Se estiver integrando com o Zabbix, muitas vezes é mais eficiente usar o protocolo SNMP ou Zabbix Sender direto no servidor monitorado. No entanto, se você precisa que o Uptime Kuma aja como um "proxy" de verificação externa e reporte ao Zabbix, o Webhook é a via correta.

LibreNMS via API

O LibreNMS possui uma API REST robusta. Você pode configurar o Webhook no Uptime Kuma para enviar uma requisição POST para /api/v0/devices/{device_id}/services ou criar um alerta customizado.

Exemplo de payload JSON para criar um serviço no LibreNMS via webhook:

{
    "service_type": "ping",
    "service_port": null,
    "service_disable": 0,
    "device_id": 1
}

Lembre-se de substituir device_id pelo ID real do seu dispositivo no LibreNMS e configurar o header X-Auth-Token com sua chave API.

Melhores Práticas e Conclusão

Ao implementar o Uptime Kuma em sua infraestrutura, adote as seguintes práticas para garantir a confiabilidade do monitoramento:

  • Evite Monitores Falsos-Positivos: Configure timeouts adequados. Não deixe um timeout de 1 segundo para serviços que podem sofrer latência de rede pontual.
  • Use Múltiplas Notificações: Ative Telegram, Email e Discord simultaneamente para garantir que a informação chegue ao responsável mesmo se um canal falhar.
  • Monitore o Próprio Kuma: Crie um monitor externo (de outra VPS ou de casa) apontando para a URL pública do seu Uptime Kuma. Se o painel dele cair, você não saberá que outros serviços caíram.
  • Documente os Webhooks: Se estiver integrando com Zabbix ou LibreNMS, mantenha um registro dos payloads e endpoints usados para facilitar o debugging futuro.

O Uptime Kuma é uma ferramenta poderosa que democratiza a observabilidade. Desde startups até grandes corporações, sua leveza permite ser implantada em segundos, enquanto suas capacidades de integração com Grafana, Zabbix e webhooks genéricos garantem que ele não seja apenas um "brinquedo", mas uma peça central no pipeline de alertas da Toda Solução.

Comece hoje mesmo configurando seus primeiros monitores HTTP e TCP. A visibilidade é o primeiro passo para a estabilidade.

Compartilhar: Link copiado!
Tags:
Esse tutorial foi útil?

Comentários (0)

Seja o primeiro a comentar.

Deixe seu comentário

Seu comentário será analisado antes de ser publicado.

0/2000
Voltar para Tutoriais