Pular para o conteúdo principal

Integração HOMER

Este documento cobre a integração opcional do HOMER para correlacionar logs de aplicativos com rastros SIP.

Visão Geral​

OmniTAS pode encaminhar logs de aplicativos para um servidor HOMER usando o HEP3 (Homer Encapsulation Protocol) sobre UDP. Os logs são correlacionados com rastros SIP usando o SIP Call-ID, permitindo visibilidade de ponta a ponta do processamento de chamadas junto com a sinalização.

Como Funciona​

  1. Metadados de Log: Durante o processamento da chamada, o OmniTAS define o SIP Call-ID nos metadados do Logger.
  2. Captura de Log: O módulo Homer se inscreve em mensagens de log via PubSub.
  3. Filtragem: Apenas logs contendo metadados call_id são encaminhados.
  4. Codificação HEP3: Os logs são codificados como pacotes HEP3 com tipo de protocolo 100 (log).
  5. Correlação: O HOMER correlaciona logs com rastros SIP usando o Call-ID.

Configuração​

Adicione a configuração homer_server ao seu config/runtime.exs:

config :tas,
  homer_server: %{
    host: "10.179.2.136",
    port: 9060,
    auth_key: nil,
    capture_id: 2001
  }

Parâmetros​

ParâmetroTipoNecessárioPadrãoDescrição
hostStringSim-Endereço IP ou nome do servidor HOMER
portInteiroNão9060Porta UDP do receptor HEP
auth_keyStringNãonilChave de autenticação HEP opcional. Defina para corresponder ao authkey na configuração do heplify-server se habilitado
capture_idInteiroNão2001Identificador do agente de captura. Aparece na interface do HOMER para identificar a fonte do log

Desabilitando a Integração HOMER​

Para desabilitar a integração HOMER, você pode:

  • Remover completamente a configuração homer_server, ou
  • Comentar o bloco de configuração

Quando desabilitado, o módulo Homer não é iniciado e nenhum log é encaminhado.

Requisitos do Servidor HOMER​

O servidor HOMER deve estar executando o heplify-server com a recepção HEP habilitada no UDP.

Configuração do heplify-server​

Verifique se o seu heplify-server.toml inclui:

HEPAddr = "0.0.0.0:9060"

Tipos de Protocólos Suportados​

OmniTAS envia logs com tipo de protocolo HEP 100, que o heplify-server roteia para logs_capture. Certifique-se de que o esquema do banco de dados HOMER suporte o armazenamento de logs.

Correlação de Logs​

Injeção Automática de Call-ID​

OmniTAS injeta automaticamente o Call-ID nos metadados do Logger durante:

  • Processamento de Chamada MO: Ao processar chamadas originadas de dispositivos móveis
  • Processamento de Chamada MT: Ao processar chamadas terminadas em dispositivos móveis
  • Eventos de Chamada: Ao lidar com eventos de resposta e desligamento

Formato de Log​

Os logs enviados para o HOMER incluem:

CampoDescrição
ID de CorrelaçãoSIP Call-ID para correlação de rastros
TimestampTimestamp com precisão de microssegundos
NívelNível de log (debug, info, warning, error)
MensagemConteúdo da mensagem de log
IP de OrigemEndereço IP do servidor OmniTAS
ID de CapturaIdentificador do agente de captura configurado

Exemplo de Log no HOMER​

Após uma chamada ser processada, o HOMER exibe dados correlacionados:

[info] Processando chamada MO de: 61400123456 para: 61400654321
[debug] Busca sh para chamador: 61400123456
[info] Autorização OCS: CONCEDIDA (120 segundos)
[debug] Definindo variável: hangup_case = none

Esses logs aparecem ao lado das mensagens SIP INVITE, 200 OK e BYE na visualização de detalhes da chamada do HOMER.

Detalhes do Protocolo HEP3​

OmniTAS implementa HEP3 conforme definido pelo projeto HOMER, compatível com o módulo siptrace do Kamailio.

Tipos de Chunk Usados​

ID do ChunkNomeDescrição
0x0001Família IPSempre 2 (IPv4)
0x0002Protocolo IPSempre 17 (UDP)
0x0003IPv4 de OrigemEndereço do servidor OmniTAS
0x0004IPv4 de DestinoEndereço do servidor HOMER
0x0007Porta de Origem0 (não aplicável para logs)
0x0008Porta de DestinoPorta HEP configurada
0x0009Timestamp SecSegundos do timestamp Unix
0x000ATimestamp USecComponente de microssegundos
0x000BTipo de Protocolo100 (log)
0x000CID de Capturacapture_id configurado
0x0011ID de CorrelaçãoSIP Call-ID
0x000FPayloadMensagem de log
0x000EChave de AutenticaçãoAutenticação opcional

Solução de Problemas​

Logs Não Aparecendo no HOMER​

Sintomas: Chamadas completam com sucesso, mas nenhum log aparece no HOMER.

Possíveis causas:

  • Servidor HOMER inacessível na porta configurada
  • Firewall bloqueando tráfego UDP para a porta 9060
  • heplify-server não configurado para receber HEP
  • Logs sem metadados call_id

Resolução:

  1. Verifique a conectividade da rede: nc -zvu <homer_host> 9060
  2. Verifique se o heplify-server está ouvindo: ss -ulnp | grep 9060
  3. Revise os logs do heplify-server para pacotes recebidos
  4. Verifique se o call_id aparece nos logs do OmniTAS (verifique por call_id= na saída do log)

Falhas de Autenticação​

Sintomas: Logs do heplify-server mostram erros de autenticação.

Possíveis causas:

  • Chave de autenticação não correspondente entre OmniTAS e heplify-server
  • Chave de autenticação configurada de um lado, mas não do outro

Resolução:

  1. Se o heplify-server não tiver chave de autenticação configurada, defina auth_key: nil no OmniTAS.
  2. Se o heplify-server exigir autenticação, configure a chave correspondente em ambos os sistemas.

Correlação Ausente​

Sintomas: Logs aparecem no HOMER, mas não estão correlacionados com rastros SIP.

Possíveis causas:

  • Desconformidade no formato do Call-ID entre SIP e logs
  • Configuração de correlação do HOMER

Resolução:

  1. Verifique se o Call-ID nos logs corresponde exatamente ao cabeçalho SIP Call-ID.
  2. Verifique as configurações de correlação do HOMER para a tabela logs_capture.

Métricas​

Quando a integração HOMER está habilitada, monitore esses indicadores:

Logs do OmniTAS​

Fique atento a avisos indicando falhas na transmissão HEP:

[warning] Falha ao enviar pacote HEP para Homer: <reason>

Métricas do heplify-server​

Se as métricas do Prometheus estiverem habilitadas no heplify-server, monitore:

  • heplify_packets_total{type="log"} - Total de pacotes de log recebidos
  • heplify_packets_dropped_total - Pacotes descartados (erros de buffer/análise)

Referência de Arquitetura​

Interação de Componentes​

Fluxo de Dados​

Veja Também​