Saltar al contenido principal

Integración de HOMER

Este documento cubre la integración opcional de HOMER para correlacionar registros de aplicaciones con trazas SIP.

Visión General​

OmniTAS puede enviar registros de aplicaciones a un servidor HOMER utilizando el HEP3 (Homer Encapsulation Protocol) sobre UDP. Los registros se correlacionan con trazas SIP utilizando el SIP Call-ID, lo que permite una visibilidad de extremo a extremo del procesamiento de llamadas junto con la señalización.

Cómo Funciona​

  1. Metadatos de Registro: Durante el procesamiento de llamadas, OmniTAS establece el SIP Call-ID en los metadatos del Logger.
  2. Captura de Registros: El módulo Homer se suscribe a los mensajes de registro a través de PubSub.
  3. Filtrado: Solo se envían los registros que contienen metadatos call_id.
  4. Codificación HEP3: Los registros se codifican como paquetes HEP3 con tipo de protocolo 100 (registro).
  5. Correlación: HOMER correlaciona los registros con trazas SIP utilizando el Call-ID.

Configuración​

Agregue la configuración homer_server a su config/runtime.exs:

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

Parámetros​

ParámetroTipoRequeridoPredeterminadoDescripción
hostStringSí-Dirección IP o nombre de host del servidor HOMER
portIntegerNo9060Puerto UDP del receptor HEP
auth_keyStringNonilClave de autenticación HEP opcional. Establecer para que coincida con authkey en la configuración de heplify-server si está habilitada
capture_idIntegerNo2001Identificador del agente de captura. Aparece en la interfaz de usuario de HOMER para identificar la fuente del registro

Deshabilitar la Integración de HOMER​

Para deshabilitar la integración de HOMER, ya sea:

  • Elimine la configuración homer_server por completo, o
  • Comente el bloque de configuración

Cuando está deshabilitado, el módulo Homer no se inicia y no se envían registros.

Requisitos del Servidor HOMER​

El servidor HOMER debe estar ejecutando heplify-server con la recepción de HEP habilitada en UDP.

Configuración de heplify-server​

Verifique que su heplify-server.toml incluya:

HEPAddr = "0.0.0.0:9060"

Tipos de Protocolo Soportados​

OmniTAS envía registros con el tipo de protocolo HEP 100, que heplify-server dirige a logs_capture. Asegúrese de que el esquema de base de datos de HOMER soporte el almacenamiento de registros.

Correlación de Registros​

Inyección Automática de Call-ID​

OmniTAS inyecta automáticamente el Call-ID en los metadatos del Logger durante:

  • Procesamiento de Llamadas MO: Al procesar llamadas de origen móvil
  • Procesamiento de Llamadas MT: Al procesar llamadas terminadas móviles
  • Eventos de Llamada: Al manejar eventos de respuesta y colgado

Formato de Registro​

Los registros enviados a HOMER incluyen:

CampoDescripción
Correlation IDSIP Call-ID para la correlación de trazas
TimestampMarca de tiempo con precisión de microsegundos
LevelNivel de registro (debug, info, warning, error)
MessageContenido del mensaje de registro
Source IPDirección IP del servidor OmniTAS
Capture IDIdentificador del agente de captura configurado

Ejemplo de Registro en HOMER​

Después de que se procesa una llamada, HOMER muestra datos correlacionados:

[info] Processing MO call from: 61400123456 to: 61400654321
[debug] Sh lookup for caller: 61400123456
[info] OCS authorization: GRANTED (120 seconds)
[debug] Setting variable: hangup_case = none

Estos registros aparecen junto con los mensajes SIP INVITE, 200 OK y BYE en la vista de detalles de llamada de HOMER.

Detalles del Protocolo HEP3​

OmniTAS implementa HEP3 según lo definido por el proyecto HOMER, compatible con el módulo siptrace de Kamailio.

Tipos de Chunk Usados​

Chunk IDNombreDescripción
0x0001IP FamilySiempre 2 (IPv4)
0x0002IP ProtocolSiempre 17 (UDP)
0x0003Source IPv4Dirección del servidor OmniTAS
0x0004Dest IPv4Dirección del servidor HOMER
0x0007Source Port0 (no aplicable para registros)
0x0008Dest PortPuerto HEP configurado
0x0009Timestamp SecSegundos de marca de tiempo Unix
0x000ATimestamp USecComponente de microsegundos
0x000BProtocol Type100 (registro)
0x000CCapture IDcapture_id configurado
0x0011Correlation IDSIP Call-ID
0x000FPayloadMensaje de registro
0x000EAuth KeyAutenticación opcional

Solución de Problemas​

Registros No Aparecen en HOMER​

Síntomas: Las llamadas se completan con éxito pero no aparecen registros en HOMER.

Causas posibles:

  • Servidor HOMER inalcanzable en el puerto configurado.
  • Cortafuegos bloqueando el tráfico UDP al puerto 9060.
  • heplify-server no configurado para recibir HEP.
  • Registros faltando metadatos call_id.

Resolución:

  1. Verifique la conectividad de red: nc -zvu <homer_host> 9060
  2. Verifique que heplify-server esté escuchando: ss -ulnp | grep 9060
  3. Revise los registros de heplify-server en busca de paquetes entrantes.
  4. Verifique que call_id aparezca en los registros de OmniTAS (busque call_id= en la salida del registro).

Fallos de Autenticación​

Síntomas: Los registros de heplify-server muestran errores de autenticación.

Causas posibles:

  • Clave de autenticación no coincidente entre OmniTAS y heplify-server.
  • Clave de autenticación configurada en un lado pero no en el otro.

Resolución:

  1. Si heplify-server no tiene clave de autenticación configurada, establezca auth_key: nil en OmniTAS.
  2. Si heplify-server requiere autenticación, configure una clave coincidente en ambos sistemas.

Correlación Faltante​

Síntomas: Los registros aparecen en HOMER pero no están correlacionados con las trazas SIP.

Causas posibles:

  • Desajuste en el formato del Call-ID entre SIP y registros.
  • Configuración de correlación de HOMER.

Resolución:

  1. Verifique que el Call-ID en los registros coincida exactamente con el encabezado SIP Call-ID.
  2. Revise la configuración de correlación de HOMER para la tabla logs_capture.

Métricas​

Cuando la integración de HOMER está habilitada, monitoree estos indicadores:

Registros de OmniTAS​

Esté atento a advertencias que indiquen fallos en la transmisión de HEP:

[warning] Failed to send HEP packet to Homer: <reason>

Métricas de heplify-server​

Si las métricas de Prometheus están habilitadas en heplify-server, monitoree:

  • heplify_packets_total{type="log"} - Total de paquetes de registro recibidos.
  • heplify_packets_dropped_total - Paquetes descartados (errores de búfer/análisis).

Referencia de Arquitectura​

Interacción de Componentes​

Flujo de Datos​

Ver También​