Pular para o conteúdo principal

Guia de Monitoramento e Métricas

Referência completa para monitorar o SMPP Gateway

Visão Geral​

O SMPP Gateway expõe métricas no formato Prometheus para monitorar a saúde da conexão, a taxa de mensagens e o desempenho do sistema.

Crítico: Como o gateway é sem estado e depende do OmniMessage Core, a conectividade do OmniMessage é a métrica mais importante a ser monitorada. Monitore ambos:

  1. Métricas do SMPP Gateway - Saúde em nível de protocolo
  2. Métricas da API OmniMessage - Conectividade e saúde do backend

Endpoint de Métricas​

URL: http://your-server:4000/metrics

Formato: Formato de texto Prometheus

Acesso: Aberto para localhost por padrão (configure o firewall para acesso remoto)

Teste Rápido​

curl http://localhost:4000/metrics

Métricas Disponíveis​

Todas as métricas são prefixadas com smpp_ e incluem rótulos para identificação.

Métricas de Status da Conexão​

smpp_connection_status​

Tipo: Gauge
Descrição: Status atual da conexão do SMPP bind
Valores:

  • 1 = Conectado
  • 0 = Desconectado

Rótulos:

  • bind_name - Nome da conexão (ex: "vodafone_uk")
  • mode - Tipo de conexão ("client" ou "server")
  • host - Host remoto (apenas modo cliente)
  • port - Porta remota (apenas modo cliente)
  • bind_type - Tipo de bind SMPP (apenas modo cliente)
  • system_id - ID do sistema utilizado

Exemplo:

smpp_connection_status{bind_name="vodafone_uk",mode="client",host="smpp.vodafone.co.uk",port="2775",bind_type="transceiver",system_id="user1"} 1

Uso:

  • Alertar quando o valor for 0 (desconectado)
  • Rastrear a porcentagem de tempo de atividade da conexão
  • Monitorar a frequência de reconexões

Contadores de Mensagens​

smpp_messages_sent_total​

Tipo: Counter
Descrição: Número total de mensagens enviadas através do SMPP bind
Unidade: Mensagens

Rótulos: Mesmo que connection_status

Exemplo:

smpp_messages_sent_total{bind_name="vodafone_uk",mode="client",...} 150234

Uso:

  • Calcular a taxa de mensagens (mensagens/segundo)
  • Rastrear o volume diário/mensal
  • Comparar a taxa real com a esperada

smpp_messages_received_total​

Tipo: Counter
Descrição: Número total de mensagens recebidas através do SMPP bind
Unidade: Mensagens

Rótulos: Mesmo que connection_status

Exemplo:

smpp_messages_received_total{bind_name="partner_acme",mode="server",...} 45123

Uso:

  • Monitorar o volume de mensagens recebidas
  • Rastrear o tráfego originado em dispositivos móveis (MO)
  • Alertar sobre mudanças inesperadas no volume

Métricas de Entrega​

smpp_delivery_failures_total​

Tipo: Counter
Descrição: Número total de falhas na entrega de mensagens
Unidade: Falhas

Rótulos: Mesmo que connection_status

Exemplo:

smpp_delivery_failures_total{bind_name="vodafone_uk",mode="client",...} 234

Uso:

  • Calcular a taxa de sucesso na entrega
  • Alertar sobre altas taxas de falhas
  • Identificar conexões problemáticas

Cálculo da Taxa de Sucesso:

success_rate = (messages_sent - delivery_failures) / messages_sent * 100

Métricas de Operação de Bind​

smpp_bind_success_total​

Tipo: Counter
Descrição: Número total de operações de bind bem-sucedidas
Unidade: Tentativas de bind

Exemplo:

smpp_bind_success_total{bind_name="vodafone_uk",...} 45

Uso:

  • Rastrear a estabilidade do bind
  • Monitorar o sucesso da autenticação

smpp_bind_failures_total​

Tipo: Counter
Descrição: Número total de operações de bind falhadas
Unidade: Tentativas de bind

Exemplo:

smpp_bind_failures_total{bind_name="vodafone_uk",...} 3

Uso:

  • Alertar sobre falhas de autenticação
  • Identificar problemas de credenciais
  • Rastrear problemas de conexão com a operadora

Métricas de Eventos de Conexão​

smpp_connection_attempts_total​

Tipo: Counter
Descrição: Número total de tentativas de conexão
Unidade: Tentativas

Exemplo:

smpp_connection_attempts_total{bind_name="vodafone_uk",...} 48

Uso:

  • Rastrear a rotatividade de conexões
  • Monitorar a frequência de reconexões

smpp_disconnection_total​

Tipo: Counter
Descrição: Número total de desconexões
Unidade: Desconexões

Exemplo:

smpp_disconnection_total{bind_name="vodafone_uk",...} 3

Uso:

  • Alertar sobre desconexões frequentes
  • Identificar problemas de rede
  • Rastrear a estabilidade da conexão

Métricas de Tempo de Atividade​

smpp_uptime_seconds​

Tipo: Gauge
Descrição: Tempo de atividade atual do SMPP bind em segundos
Unidade: Segundos

Exemplo:

smpp_uptime_seconds{bind_name="vodafone_uk",...} 86400

Uso:

  • Rastrear a estabilidade da conexão
  • Calcular a porcentagem de tempo de atividade
  • Alertar sobre reinicializações recentes

Métricas de Saúde da API OmniMessage​

Enquanto o gateway em si expõe métricas relacionadas ao SMPP, a saúde da API OmniMessage é crítica. Você também deve monitorar:

Das Métricas do OmniMessage (se disponíveis)​

  • omnimessage_api_requests_total - Total de solicitações da API do gateway
  • omnimessage_api_request_duration_seconds - Tempos de resposta da API
  • omnimessage_queue_depth - Mensagens pendentes na fila do OmniMessage

Dos Logs do Gateway (se métricas não expostas)​

Procure por esses padrões para detectar problemas na API:

  • "api.*connection refused" - Não é possível alcançar o OmniMessage
  • "api.*timeout" - OmniMessage não está respondendo
  • "api.*http 503" - OmniMessage temporariamente fora do ar
  • "api.*parse error" - Problema no formato da resposta

Configuração do Prometheus​

Configuração Básica de Scrape​

Adicione em /etc/prometheus/prometheus.yml:

scrape_configs:
  - job_name: 'omnimessage-smpp'
    scrape_interval: 15s
    static_configs:
      - targets: ['your-server:4000']
        labels:
          environment: 'production'
          service: 'omnimessage-smpp'

Múltiplos Gateways​

scrape_configs:
  - job_name: 'omnimessage-smpp-instances'
    scrape_interval: 15s
    static_configs:
      - targets:
        - 'smpp-gw-1:4000'
        - 'smpp-gw-2:4000'
        - 'smpp-gw-3:4000'
        labels:
          environment: 'production'

Descoberta de Serviço​

Usando descoberta baseada em arquivo:

scrape_configs:
  - job_name: 'omnimessage-smpp-instances'
    file_sd_configs:
      - files:
        - '/etc/prometheus/targets/smpp-*.json'

Arquivo /etc/prometheus/targets/smpp-production.json:

[
  {
    "targets": ["smpp-gw-1:4000", "smpp-gw-2:4000"],
    "labels": {
      "environment": "production",
      "datacenter": "us-east"
    }
  }
]

Painéis de Dashboard do Grafana​

Painéis de Dashboard de Exemplo​

Painel de Status da Conexão​

Consulta:

smpp_connection_status{job="omnimessage-smpp"}

Visualização: Stat
Limites:

  • Vermelho: valor < 1 (desconectado)
  • Verde: valor == 1 (conectado)

Painel de Taxa de Mensagens​

Consulta:

rate(smpp_messages_sent_total{job="omnimessage-smpp"}[5m])

Visualização: Gráfico
Unidade: mensagens/segundo
Legenda: {{bind_name}}

Painel de Taxa de Sucesso na Entrega​

Consulta:

100 * (1 - (
  rate(smpp_delivery_failures_total{job="omnimessage-smpp"}[5m])
  /
  rate(smpp_messages_sent_total{job="omnimessage-smpp"}[5m])
))

Visualização: Gauge
Unidade: Porcentagem (0-100)
Limites:

  • Vermelho: < 95%
  • Amarelo: 95-98%
  • Verde: > 98%

Painel de Tempo de Atividade da Conexão​

Consulta:

smpp_uptime_seconds{job="omnimessage-smpp"} / 3600

Visualização: Stat
Unidade: Horas

Regras de Alerta​

Regras de Alerta do Prometheus​

Salve em /etc/prometheus/rules/smpp-alerts.yml:

groups:
  - name: smpp_gateway
    interval: 30s
    rules:
      # Conexão fora do ar
      - alert: SMPPConnectionDown
        expr: smpp_connection_status == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "A conexão SMPP {{ $labels.bind_name }} está fora do ar"
          description: "A conexão {{ $labels.bind_name }} foi desconectada por mais de 2 minutos."

      # Alta taxa de falhas
      - alert: SMPPHighFailureRate
        expr: |
          (
            rate(smpp_delivery_failures_total[5m])
            /
            rate(smpp_messages_sent_total[5m])
          ) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Alta taxa de falhas de entrega em {{ $labels.bind_name }}"
          description: "A taxa de falhas de entrega é {{ $value | humanizePercentage }} em {{ $labels.bind_name }}."

      # Falhas de bind
      - alert: SMPPBindFailures
        expr: increase(smpp_bind_failures_total[10m]) > 3
        labels:
          severity: warning
        annotations:
          summary: "Múltiplas falhas de bind em {{ $labels.bind_name }}"
          description: "{{ $labels.bind_name }} falhou ao bindar {{ $value }} vezes nos últimos 10 minutos."

      # Nenhuma mensagem enviada (quando esperado)
      - alert: SMPPNoTraffic
        expr: rate(smpp_messages_sent_total[10m]) == 0
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "Nenhuma mensagem enviada em {{ $labels.bind_name }}"
          description: "{{ $labels.bind_name }} não enviou nenhuma mensagem por 30 minutos."

      # Desconexões frequentes
      - alert: SMPPFrequentDisconnections
        expr: increase(smpp_disconnection_total[1h]) > 5
        labels:
          severity: warning
        annotations:
          summary: "Desconexões frequentes em {{ $labels.bind_name }}"
          description: "{{ $labels.bind_name }} desconectou {{ $value }} vezes na última hora."

      # API OmniMessage inacessível
      - alert: OmniMessageAPIUnreachable
        expr: |
          count(count_over_time({job="omnimessage-smpp"} |= "api.*connection refused"[5m])) > 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "API OmniMessage está inacessível"
          description: "O SMPP Gateway não consegue alcançar a API OmniMessage. Verifique a configuração de API_BASE_URL e a conectividade de rede."

      # Timeouts da API OmniMessage
      - alert: OmniMessageAPITimeout
        expr: |
          count(count_over_time({job="omnimessage-smpp"} |= "api.*timeout"[5m])) > 5
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "API OmniMessage está com timeout"
          description: "Múltiplos timeouts da API detectados. O OmniMessage pode estar lento ou sobrecarregado."

      # Nenhum fluxo de mensagem (problema na API)
      - alert: NoMessageFlow
        expr: rate(smpp_messages_sent_total[10m]) == 0 and rate(smpp_messages_received_total[10m]) == 0
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "Nenhum fluxo de mensagem detectado - verifique a conectividade do OmniMessage"
          description: "Nenhuma mensagem enviada ou recebida por 30 minutos. Verifique a conectividade da API OmniMessage e o status da fila."

Carregue as regras em prometheus.yml:

rule_files:
  - '/etc/prometheus/rules/smpp-alerts.yml'

Monitoramento do Dashboard Web​

A interface web integrada fornece monitoramento em tempo real sem o Prometheus.

Acesso​

URL: https://your-server:8087

Página de Status Ao Vivo​

Navegação: SMPP → Status Ao Vivo

Recursos:

  • Status de conexão em tempo real
  • Contadores de mensagens
  • Tempo de atividade da conexão
  • Controles manuais de reconexão/desconexão
  • Atualização automática a cada 5 segundos

Uso:

  • Verificação rápida de status
  • Intervenção manual
  • Solução de problemas em tempo real

O dashboard exibe:

  • Total de Binds: Contagem combinada de todas as conexões de cliente e servidor
  • Binds de Cliente: Conexões de saída para operadoras (mostrando contagem de conectado/desconectado)
  • Binds de Servidor: Conexões de entrada de parceiros (mostrando contagem de ativo/aguardando)
  • Servidor Escutando: Configuração do socket de servidor de entrada (host, porta, conexões máximas)

Monitoramento de Logs​

Logs do Sistema​

Visualizar logs:

# Acompanhar logs em tempo real
sudo journalctl -u omnimessage-smpp -f

# Últimas 100 linhas
sudo journalctl -u omnimessage-smpp -n 100

# Desde um horário específico
sudo journalctl -u omnimessage-smpp --since "1 hour ago"

# Filtrar por nível
sudo journalctl -u omnimessage-smpp -p err

Logs da Interface Web​

Navegação: Aba de logs na interface web

Recursos:

  • Streaming de logs em tempo real
  • Filtrar por nível (debug, info, warning, error)
  • Buscar logs
  • Pausar/retomar
  • Limpar logs

A visualização de logs permite que você:

  • Filtrar por Nível: Selecionar nível de log (Todos, Debug, Info, Warning, Error)
  • Buscar: Encontrar entradas de log específicas por conteúdo de texto
  • Auto-rolar: Habilitar/desabilitar rolagem automática à medida que novos logs chegam
  • Pausar/Retomar: Pausar atualizações de log para revisar entradas específicas
  • Limpar: Limpar todos os logs exibidos

Indicadores-Chave de Desempenho (KPIs)​

Saúde da Conexão​

Métrica: Porcentagem de tempo de atividade da conexão

avg_over_time(smpp_connection_status[24h]) * 100

Meta: > 99.9%

Taxa de Entrega de Mensagens​

Métrica: Mensagens entregues por segundo

rate(smpp_messages_sent_total[5m])

Meta: Corresponde ao volume esperado

Taxa de Sucesso na Entrega​

Métrica: Porcentagem de entregas bem-sucedidas

100 * (1 - rate(smpp_delivery_failures_total[5m]) / rate(smpp_messages_sent_total[5m]))

Meta: > 98%

Estabilidade do Bind​

Métrica: Tentativas de bind por hora

rate(smpp_bind_success_total[1h]) * 3600

Meta: < 10 por hora (indica conexão estável)

Melhores Práticas de Monitoramento​

1. Configurar Alertas​

  • Configure alertas do Prometheus para métricas críticas
  • Use PagerDuty/OpsGenie para alertas 24/7
  • Teste alertas regularmente

2. Criar Dashboards​

  • Construa dashboards do Grafana para cada gateway
  • Inclua todas as conexões em um dashboard
  • Adicione painéis de planejamento de capacidade

3. Revisões Regulares​

  • Revise métricas semanalmente
  • Identifique tendências e padrões
  • Planeje ajustes de capacidade

4. Documentar Linhas de Base​

  • Registre volumes normais de mensagens
  • Documente taxas de TPS esperadas
  • Anote horários/dias de pico

5. Correlacionar com o Backend​

  • Monitore métricas da API do backend
  • Rastreie o fluxo de mensagens de ponta a ponta
  • Identifique gargalos

Solução de Problemas com Métricas​

Problemas de Conexão​

Verifique: smpp_connection_status

  • Valor 0 = Revise logs, verifique a rede, verifique credenciais
  • Mudanças frequentes = Instabilidade na rede

Baixas Taxas de Entrega​

Verifique: smpp_delivery_failures_total

  • Alta taxa = Verifique o status da operadora, revise o formato da mensagem
  • Compare entre conexões = Identifique a operadora problemática

Baixa Taxa de Transferência​

Verifique: taxa de smpp_messages_sent_total

  • Abaixo do esperado = Verifique limites de TPS, disponibilidade da fila
  • Verifique métricas da API do backend

Problemas de Bind​

Verifique: smpp_bind_failures_total

  • Aumentando = Problemas de autenticação, problemas de credenciais
  • Verifique system_id e senha na configuração

Documentação Relacionada​

Copyright © 2025 Omnitouch Network Services