Aller au contenu principal

Intégration HOMER

Ce document couvre l'intégration optionnelle de HOMER pour corréler les journaux d'application avec les traces SIP.

Vue d'ensemble​

OmniTAS peut transférer des journaux d'application à un serveur HOMER en utilisant le HEP3 (Homer Encapsulation Protocol) sur UDP. Les journaux sont corrélés avec les traces SIP en utilisant le SIP Call-ID, permettant une visibilité de bout en bout du traitement des appels aux côtés de la signalisation.

Comment ça fonctionne​

  1. Métadonnées de journal : Pendant le traitement des appels, OmniTAS définit le SIP Call-ID dans les métadonnées du Logger.
  2. Capture de journal : Le module Homer s'abonne aux messages de journal via PubSub.
  3. Filtrage : Seuls les journaux contenant des métadonnées call_id sont transférés.
  4. Encodage HEP3 : Les journaux sont encodés en tant que paquets HEP3 avec le type de protocole 100 (journal).
  5. Corrélation : HOMER corrèle les journaux avec les traces SIP en utilisant le Call-ID.

Configuration​

Ajoutez la configuration homer_server à votre config/runtime.exs :

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

Paramètres​

ParamètreTypeRequisPar défautDescription
hostStringOui-Adresse IP ou nom d'hôte du serveur HOMER
portIntegerNon9060Port UDP du récepteur HEP
auth_keyStringNonnilClé d'authentification HEP optionnelle. À définir pour correspondre à authkey dans la configuration du serveur heplify si activé
capture_idIntegerNon2001Identifiant de l'agent de capture. Apparaît dans l'interface HOMER pour identifier la source des journaux

Désactivation de l'intégration HOMER​

Pour désactiver l'intégration HOMER, soit :

  • Supprimez complètement la configuration homer_server, ou
  • Commentez le bloc de configuration

Lorsque désactivé, le module Homer n'est pas démarré et aucun journal n'est transféré.

Exigences du serveur HOMER​

Le serveur HOMER doit exécuter heplify-server avec la réception HEP activée sur UDP.

Configuration de heplify-server​

Vérifiez que votre heplify-server.toml inclut :

HEPAddr = "0.0.0.0:9060"

Types de protocole pris en charge​

OmniTAS envoie des journaux avec le type de protocole HEP 100, que heplify-server achemine vers logs_capture. Assurez-vous que le schéma de votre base de données HOMER prend en charge le stockage des journaux.

Corrélation des journaux​

Injection automatique du Call-ID​

OmniTAS injecte automatiquement le Call-ID dans les métadonnées du Logger pendant :

  • Traitement des appels MO : Lors du traitement des appels d'origine mobile
  • Traitement des appels MT : Lors du traitement des appels terminés sur mobile
  • Événements d'appel : Lors de la gestion des événements de réponse et de raccrochage

Format de journal​

Les journaux envoyés à HOMER incluent :

ChampDescription
ID de corrélationSIP Call-ID pour la corrélation des traces
HorodatageHorodatage avec une précision en microsecondes
NiveauNiveau de journal (debug, info, warning, error)
MessageContenu du message de journal
IP sourceAdresse IP du serveur OmniTAS
ID de captureIdentifiant de l'agent de capture configuré

Exemple de journal dans HOMER​

Après qu'un appel a été traité, HOMER affiche les données corrélées :

[info] Traitement de l'appel MO de : 61400123456 à : 61400654321
[debug] Recherche sh pour l'appelant : 61400123456
[info] Autorisation OCS : ACCORDÉE (120 secondes)
[debug] Définition de la variable : hangup_case = none

Ces journaux apparaissent aux côtés des messages SIP INVITE, 200 OK et BYE dans la vue de détail des appels de HOMER.

Détails du protocole HEP3​

OmniTAS implémente HEP3 tel que défini par le projet HOMER, compatible avec le module siptrace de Kamailio.

Types de chunks utilisés​

ID de chunkNomDescription
0x0001Famille IPToujours 2 (IPv4)
0x0002Protocole IPToujours 17 (UDP)
0x0003Source IPv4Adresse du serveur OmniTAS
0x0004Dest IPv4Adresse du serveur HOMER
0x0007Port source0 (non applicable pour les journaux)
0x0008Port de destinationPort HEP configuré
0x0009Timestamp SecSecondes de timestamp Unix
0x000ATimestamp USecComposant en microsecondes
0x000BType de protocole100 (journal)
0x000CID de capturecapture_id configuré
0x0011ID de corrélationSIP Call-ID
0x000FCharge utileMessage de journal
0x000EClé d'authentificationAuthentification optionnelle

Dépannage​

Journaux n'apparaissant pas dans HOMER​

Symptômes : Les appels se terminent avec succès mais aucun journal n'apparaît dans HOMER.

Causes possibles :

  • Serveur HOMER inaccessible sur le port configuré
  • Pare-feu bloquant le trafic UDP vers le port 9060
  • heplify-server non configuré pour recevoir HEP
  • Journaux manquant de métadonnées call_id

Résolution :

  1. Vérifiez la connectivité réseau : nc -zvu <homer_host> 9060
  2. Vérifiez que heplify-server écoute : ss -ulnp | grep 9060
  3. Consultez les journaux de heplify-server pour les paquets entrants
  4. Vérifiez que call_id apparaît dans les journaux d'OmniTAS (recherchez call_id= dans la sortie du journal)

Échecs d'authentification​

Symptômes : Les journaux de heplify-server montrent des erreurs d'authentification.

Causes possibles :

  • Clé d'authentification non correspondante entre OmniTAS et heplify-server
  • Clé d'authentification configurée d'un côté mais pas de l'autre

Résolution :

  1. Si heplify-server n'a pas de clé d'authentification configurée, définissez auth_key: nil dans OmniTAS.
  2. Si heplify-server nécessite une authentification, configurez une clé correspondante dans les deux systèmes.

Corrélation manquante​

Symptômes : Les journaux apparaissent dans HOMER mais ne sont pas corrélés avec les traces SIP.

Causes possibles :

  • Mismatch de format de Call-ID entre SIP et journaux
  • Configuration de corrélation HOMER

Résolution :

  1. Vérifiez que le Call-ID dans les journaux correspond exactement à l'en-tête SIP Call-ID.
  2. Vérifiez les paramètres de corrélation de HOMER pour la table logs_capture.

Métriques​

Lorsque l'intégration HOMER est activée, surveillez ces indicateurs :

Journaux OmniTAS​

Surveillez les avertissements indiquant des échecs de transmission HEP :

[warning] Échec de l'envoi du paquet HEP à Homer : <reason>

Métriques de heplify-server​

Si les métriques Prometheus sont activées sur heplify-server, surveillez :

  • heplify_packets_total{type="log"} - Total des paquets de journaux reçus
  • heplify_packets_dropped_total - Paquets perdus (erreurs de tampon/analyse)

Référence d'architecture​

Interaction des composants​

Flux de données​

Voir aussi​