OmniRoam

OmniRoam est la solution complète de gestion des revenus en gros pour les opérateurs de roaming d'Omnitouch. Elle gère l'ensemble du cycle de vie des CDR de données de roaming (Call Detail Records), de l'ingestion à la tarification, en passant par la génération de fichiers TAP3 et les rapports.

Table des matières

• Aperçu
• Guide des opérations
  • Exécution de l'export TAP3
  • Surveillance et reporting
  • Dépannage
  • Support et maintenance
• Architecture système
  • Aperçu général
  • Processus d'importation CDR
  • Moteur de tarification OmniCharge
  • Génération de fichiers TAP3
• Guide de configuration
  • Configuration des partenaires
  • Configuration du compteur de séquence
  • Configuration du réseau
  • Configuration InfluxDB
• Décisions architecturales

Aperçu

OmniRoam traite les CDR de roaming des opérateurs de réseaux mobiles, les tarifie à l'aide du moteur de tarification OmniCharge, génère des fichiers TAP3 conformes aux normes GSMA pour la facturation, et fournit des capacités de surveillance et de reporting complètes.

Processus d'importation et de tarification des CDR

Processus d'export TAP3

Guide des opérations

Exécution de l'export TAP3

# Export pour un partenaire spécifique
python3 export_TAP3.py VZW_Live

# Mode interactif (demande pour le partenaire)
python3 export_TAP3.py

Le processus d'export :

1. Interroge les CDR des 30 derniers jours (exigence GSMA)
2. Filtre les CDR marqués comme déjà traités
3. Exclut les CDR avec un temps de fin inférieur à 1 heure (évite les sessions incomplètes)
4. Regroupe les CDR par partenaire de roaming
5. Génère un fichier TAP3 par partenaire
6. Marque les CDR comme traités dans la base de données
7. Incrémente le compteur de séquence
8. Pousse les métriques vers InfluxDB

Surveillance et reporting

OmniRoam pousse des métriques en temps réel vers InfluxDB pour la surveillance et l'analyse.

Métriques collectées

Métriques CDR brutes Poussées pendant le processus d'importation et de tarification des CDR :

• operator : Identifiant du partenaire de roaming
• input_file : Nom du fichier CSV source
• apn : Nom du point d'accès (identifiant du service de données)
• cellId : Identifiant de la tour cellulaire
• imsi : Identité de l'abonné
• tac : Code de zone de suivi
• sGWAddress : Adresse IP de la passerelle de service
• pGWAddress : Adresse IP de la passerelle PDN
• chargeableUnits : Total des octets utilisés
• chargedUnits : Coût calculé

Métriques d'export TAP Poussées pendant le processus de génération de fichiers TAP3 :

• operator : Identifiant du partenaire de roaming
• filename : Nom du fichier TAP3 généré
• totalcharge : Charge totale dans le fichier TAP3
• totalconsumed : Total des octets dans le fichier TAP3
• cdr_count : Nombre de CDR dans le fichier TAP3

Requêtes de tableau de bord

Exemples de requêtes InfluxDB pour la surveillance :

Revenu par opérateur

SELECT sum("totalcharge")
FROM "tap_cdr"
WHERE time > now() - 30d
GROUP BY "operator"

Utilisation des données par TAC

SELECT sum("chargeableUnits")
FROM "raw_cdr"
WHERE time > now() - 7d
GROUP BY "tac"

Volume de CDR par heure

SELECT count("chargeableUnits")
FROM "raw_cdr"
WHERE time > now() - 24h
GROUP BY time(1h)

Revenu par APN

SELECT sum("chargedUnits")
FROM "raw_cdr"
WHERE time > now() - 7d
GROUP BY "apn"

Intégration Grafana

Créez des tableaux de bord Grafana en utilisant ces métriques pour :

• Surveillance des revenus en temps réel
• Analyse des schémas de trafic
• Suivi des performances des partenaires
• Utilisation des ressources réseau
• Détection d'anomalies
• Rapprochement de facturation

Dépannage

Problèmes d'importation CDR

Vérifiez les journaux à /tmp/import_CDR_Logger_Marben_*.log

Problèmes courants :

• Format IMSI invalide
• Champs requis manquants
• Erreurs de conversion de fuseau horaire
• Identifiants de facturation en double

Problèmes d'export TAP3

Vérifiez les journaux à /tmp/tap3_export_*.log

Problèmes courants :

• Pas de CDR dans les 30 derniers jours
• Configuration TAC manquante
• Numéro de séquence invalide
• Erreurs de connexion à la base de données

Erreurs de tarification OmniCharge

Examinez les journaux OmniCharge pour :

• Plans tarifaires manquants
• Compte introuvable
• Valeurs d'utilisation invalides
• Erreurs de conversion de devise

Problèmes de connexion InfluxDB

Vérifiez :

• URL InfluxDB accessible
• Jeton d'authentification valide
• Le bucket existe
• Connectivité réseau

Support et maintenance

Emplacements des journaux

• Importation CDR : /tmp/import_CDR_Logger_Marben_*.log
• Export TAP : /tmp/tap3_export_*.log

Fichiers de configuration clés

• config.yaml - Configuration principale (tarifs des partenaires, paramètres réseau, connexion InfluxDB)
• counters.yaml - Compteurs de séquence des fichiers TAP3

Tâches de maintenance régulières

1. Surveiller les compteurs de séquence - Assurez-vous qu'ils ne dépassent pas 99999
2. Archiver les anciens fichiers TAP - Déplacer les fichiers plus anciens que la période de conservation
3. Surveiller l'utilisation du disque InfluxDB - Configurer des politiques de conservation
4. Examiner les configurations tarifaires - Mettre à jour lorsque les tarifs des partenaires changent
5. Sauvegarder les fichiers de configuration - config.yaml et counters.yaml
6. Surveiller le retard des CDR - Assurer un traitement rapide

Architecture système

Architecture de haut niveau

Processus d'importation CDR

OmniRoam utilise un processus d'importation en deux étapes avec le cache comme couche d'agrégation temporaire pour assembler des enregistrements CDR partiels en CDR complets et facturables.

Comprendre les CDR partiels

Les éléments de réseau mobile (S-GW/P-GW) ne génèrent pas un seul CDR pour une session de données. Au lieu de cela, ils produisent plusieurs enregistrements CDR partiels tout au long du cycle de vie de la session :

• Enregistrement de début : Généré lorsque la session de données commence
• Enregistrements de mise à jour : Générés périodiquement pendant la session (par exemple, toutes les 15 minutes ou tous les 100 Mo d'utilisation de données)
• Enregistrement d'arrêt : Généré lorsque la session se termine

Chaque enregistrement partiel contient des données d'utilisation incrémentales. Pour une facturation précise, OmniRoam doit :

1. Identifier quels enregistrements partiels appartiennent à la même session de données
2. Agrégater les données d'utilisation de tous les enregistrements partiels
3. Calculer la durée totale de la session
4. Assembler un CDR complet représentant l'ensemble de la session

Pourquoi utiliser le cache pour l'agrégation des CDR ?

Le cache sert de zone de stockage temporaire à haute performance où les CDR partiels s'accumulent jusqu'à ce que la session soit complète. Le cache fournit :

• Recherches clé-valeur rapides - Trouver instantanément les CDR partiels existants pour une session
• Stockage en mémoire - Opérations de lecture/écriture à grande vitesse pour une agrégation en temps réel
• Opérations atomiques - Mises à jour concurrentes sûres provenant de plusieurs processus d'importation
• Persistance - Les CDR survivent aux redémarrages système pendant la fenêtre d'agrégation

Architecture d'importation en deux étapes

Étape 1 : Analyse CSV et agrégation des CDR partiels

La première étape lit en continu les fichiers CSV des éléments de réseau S-GW et agrège les CDR partiels dans le cache.

Comment les CDR partiels sont identifiés et appariés

OmniRoam doit déterminer quels enregistrements partiels appartiennent à la même session de données. Chaque session est identifiée de manière unique par un ID de session composite composé de :

• ID de facturation : Identifiant de session unique provenant de l'élément de réseau
• IMSI : Identité de l'abonné (identifiant du numéro de mobile)
• Date : Date de la session dans le fuseau horaire du réseau de service
• Adresse IP P-GW : Passerelle qui a géré la session
• TAC : Code de zone de suivi (emplacement de la tour cellulaire)
• QCI : Classe de qualité de service

Cette combinaison garantit que tous les enregistrements partiels de la même session de données sont regroupés, même lorsque plusieurs fichiers arrivent dans le désordre.

Comment les CDR partiels sont agrégés

Lorsque l'analyseur CSV traite chaque CDR partiel :

1. Générer l'ID de session à partir des champs CDR
2. Vérifier le cache pour voir si cette session existe déjà
3. Si la session existe dans le cache :
   • Récupérer les données CDR accumulées
   • Vérifier que ce fichier n'a pas été traité auparavant (évite les doublons)
   • Ajouter les nouvelles données d'utilisation : octets entrants + octets sortants
   • Mettre à jour la durée de la session en utilisant les horodatages les plus anciens et les plus récents
   • Sauvegarder les métadonnées concernant cet enregistrement partiel à des fins d'audit
   • Enregistrer le CDR mis à jour dans le cache
4. Si nouvelle session :
   • Créer une nouvelle entrée CDR dans le cache
   • Initialiser les compteurs d'utilisation et les métadonnées de session
   • Enregistrer l'horodatage du premier enregistrement partiel

Piste d'audit et métadonnées

Chaque enregistrement partiel qui contribue à un CDR est suivi avec des métadonnées complètes :

• Nom de fichier source : Quel fichier CSV contenait cet enregistrement partiel
• Horodatage : Quand l'élément de réseau a généré cet enregistrement
• Temps de traitement : Quand OmniRoam l'a reçu et traité
• Contribution d'utilisation : Combien de données cet enregistrement partiel a ajouté (octets entrants/sortants)
• Type d'événement : S'il s'agissait d'un enregistrement de début, de mise à jour ou d'arrêt
• Fuseau horaire du réseau de service : Pour une conversion d'horodatage précise

Pourquoi les métadonnées sont critiques pour la comptabilité :

Cette piste d'audit permet à OmniRoam de tracer un seul coût de bout en bout à travers chaque étape de traitement, ce qui est essentiel pour :

• Résolution de litiges : Lorsque les partenaires contestent une charge, les opérateurs peuvent montrer exactement quels fichiers sources y ont contribué
• Rapprochement des revenus : Vérifier que toute l'utilisation facturable a été capturée et que rien n'a été manqué ou dupliqué
• Conformité réglementaire : Démontrer le traitement approprié des enregistrements de facturation à des fins d'audit
• Débogage : Identifier rapidement les problèmes dans le processus d'agrégation des CDR en traçant le flux de données complet
• Précision financière : S'assurer que chaque dollar facturé peut être retracé à des événements réseau spécifiques

Calcul de la durée de session

La durée totale de la session est calculée en trouvant :

• Horodatage le plus ancien parmi tous les enregistrements partiels (début de la session)
• Horodatage le plus récent parmi tous les enregistrements partiels (fin de la session)
• Durée = Plus récent - Plus ancien

Pour les sessions où seuls des enregistrements de mise à jour existent (début/arrêt manquants), la durée par défaut est de 24 heures.

Étape 2 : Assemblage et tarification des CDR

La deuxième étape scanne périodiquement le cache à la recherche de sessions complètes, assemble les CDR finaux et les soumet à OmniCharge pour tarification.

Comment les CDR complets sont sélectionnés dans le cache

Le processus d'assemblage des CDR fonctionne en continu et examine toutes les sessions stockées dans le cache :

1. Scanner le cache pour toutes les sessions CDR accumulées
2. Traiter par lots de 1 000 sessions à la fois
3. Pour chaque session :
   • Extraire la date de session de l'ID de session
   • Passer si trop ancien (> 30 jours) : Supprimer du cache (évite l'accumulation de données obsolètes)
   • Passer si trop récent (< 24 heures) : Laisser dans le cache pour que d'autres enregistrements partiels arrivent
   • Charger le CDR complet avec toutes les données accumulées

La période d'attente de 24 heures

Pourquoi OmniRoam attend-il 24 heures avant de tarifer un CDR ?

• Les enregistrements partiels arrivent dans le désordre : La congestion du réseau peut retarder la livraison des fichiers CSV de plusieurs heures
• Les sessions s'étendent à minuit : Une session commençant à 23h50 génère des fichiers sur deux dates différentes. Le même ID de facturation peut s'étendre sur plusieurs jours, avec des enregistrements partiels datés différemment
• Les enregistrements de mise à jour sont retardés : Les enregistrements de mise à jour périodiques peuvent arriver bien après la fin de la session
• Génération de fichiers asynchrone : Différents éléments de réseau exportent des fichiers à des horaires différents
• Sessions longues : Les sessions de données peuvent durer des heures ou des jours, avec des enregistrements de mise à jour arrivant tout au long

En attendant 24 heures, OmniRoam s'assure que tous les enregistrements partiels sont arrivés et que le CDR est vraiment complet avant la facturation.

Validation et enrichissement des CDR

Avant la tarification, chaque CDR assemblé passe par une validation et un enrichissement :

1. Valider la complétude :

   • Vérifier si les enregistrements de début/arrêt sont présents
   • Si seuls des enregistrements de mise à jour existent, définir la durée à 24 heures (par défaut)

2. Éliminer les CDR invalides :

   • Les sessions à utilisation nulle sont supprimées (aucune activité facturable)

3. Calculer l'utilisation finale :

   • Somme de tous les octets entrants et sortants
   • Appliquer les règles d'arrondi spécifiques au partenaire (par exemple, arrondir au kilo-octet le plus proche)

4. Enrichir avec des données de localisation :

   • Mapper le TAC (Code de zone de suivi) à l'emplacement du réseau de service
   • Ajouter des informations de fuseau horaire pour des horodatages précis
   • Ajouter une description de l'emplacement géographique

5. Soumettre à OmniCharge :

   • Envoyer le CDR complet et enrichi pour tarification
   • Recevoir le coût calculé en retour

6. Stocker et nettoyer :

   • Enregistrer le CDR tarifé dans la base de données
   • Pousser les métriques vers InfluxDB pour le reporting
   • Supprimer le CDR traité du cache

Structure des données CDR

Chaque CDR agrégé contient :

• Informations sur l'abonné : IMSI, MSISDN, IMEI
• Informations sur le réseau : Passerelle de service (S-GW), Passerelle PDN (P-GW), ID de cellule, TAC (Code de zone de suivi)
• Détails de la session : Horodatages de début/fin, Durée, APN (Nom du point d'accès)
• Données d'utilisation : Volume de données entrants/sortants, Total des unités facturables
• Informations de localisation : BID de service (ID du réseau), Emplacement géographique
• Informations QoS : QCI (Identifiant de classe de qualité de service)

Règles de traitement des données

Arrondi des utilisations

Les CDR sont arrondis en fonction de la configuration spécifique au partenaire dans config.yaml :

partners:
  Example_Live:
    round_up_to: 1024  # Arrondir l'utilisation au kilo-octet le plus proche

Le système :

1. Calcule l'utilisation totale : dataVolumeIncoming + dataVolumeOutgoing
2. Arrondit au multiple configuré (par exemple, 1024 octets)
3. Préserve les valeurs originales pour l'audit

Localisation basée sur le TAC

Le système détermine l'emplacement du réseau de service en fonction du TAC (Code de zone de suivi) :

config:
  tac_config:
    Global:
      tac_list: ['1101', '10000', '10100']
      servingBid: 72473
      servingLocationDescription: 'Smallville USA'
      timezone: 'America/Smallville'

Cela permet :

• Une conversion de fuseau horaire appropriée pour les horodatages
• L'attribution d'un emplacement géographique
• L'identification du réseau de service

Moteur de tarification OmniCharge

OmniRoam envoie les CDR à OmniCharge, le puissant moteur de tarification qui calcule les frais en fonction des plans tarifaires configurables.

Processus de tarification

Configuration des tarifs

Les tarifs sont configurés par partenaire de roaming dans le fichier de configuration :

partners:
  Example_Live:
    imsi_prefixes:
      - 99901
    rates:
      unit_price: 0.000476800  # Prix par unité
      unit_bytes: 1024          # Taille de l'unité en octets
    batch_info:
      sender: AUSIE
      recipient: AAA00
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'
        tapDecimalPlaces: 5

Appariement de préfixe IMSI

OmniRoam apparie les CDR aux partenaires de roaming en utilisant l'appariement de préfixe IMSI avec une logique de plus long match en premier. Cela permet aux opérateurs de créer des configurations spécifiques pour les SIM de test tout en maintenant des configurations générales pour le trafic de production.

Comment fonctionne l'appariement de préfixe

Lors de la tarification d'un CDR, OmniRoam :

1. Extrait l'IMSI du CDR (par exemple, 310410123456789)
2. Évalue toutes les configurations de partenaires dans l'ordre
3. Trouve le préfixe correspondant le plus long
4. Applique les tarifs et la configuration de ce partenaire

Exemple : Configuration de SIM de test

Cette fonctionnalité est particulièrement utile pour les tests TADIG/IREG où les SIM de test nécessitent un traitement différent :

partners:
  Demo_Test:
    imsi_prefixes:
      - 0010112345123  # Plage de SIM de test (préfixe de 9 chiffres)
    rates:
      unit_price: 0.0  # Aucune charge pour le trafic de test
    batch_info:
      sender: AUSIE
      recipient: AAA00TEST

  Demo_Production:
    imsi_prefixes:
      - 001011  # Plage de production (préfixe de 6 chiffres)
    rates:
      unit_price: 0.000476800
    batch_info:
      sender: AUSIE
      recipient: AAA00

Comportement d'appariement :

• IMSI 00101123451234 → Correspond à Demo_Test (le préfixe de 9 chiffres est plus long)
• IMSI 00101023456789 → Correspond à Demo_Production (le préfixe de 6 chiffres)

Cela garantit que le trafic de test va vers des fichiers TAP de test avec des codes TADIG de test, tandis que le trafic de production est facturé normalement avec des codes TADIG de production.

Calcul de la tarification

Pour chaque CDR :

1. Apparier le partenaire : Identifier le partenaire de roaming par préfixe IMSI
2. Calculer les unités : totalBytes / unit_bytes
3. Appliquer le tarif : units × unit_price = charge
4. Appliquer l'arrondi : Arrondir en fonction de roundingAction (Haut/Bas/Simple)
5. Convertir en unités TAP : Multiplier par 1000 pour le format TAP3

Exemple :

Utilisation : 52 428 800 octets (50 Mo)
Taille de l'unité : 1024 octets
Unités : 51 200
Tarif : 0,000476800 $ par 1 Ko
Charge : 51 200 × 0,000476800 $ = 24,41 $
Unités TAP : 24 410 (24,41 × 1000)

Attribution de type d'appel basée sur le QCI

Les classes de qualité de service (QCI) sont mappées aux niveaux de type d'appel TAP3 :

call_type_level:
  qci_1: 20  # Conversationnel (Voix)
  qci_2: 22  # Conversationnel (Vidéo)
  qci_3: 23  # Jeu en temps réel
  qci_4: 24  # Streaming mis en mémoire tampon
  qci_5: 20  # Signalisation IMS
  qci_6: 26  # Interactif (Navigation)
  qci_7: 27  # Interactif (Jeu)
  qci_8: 28  # Arrière-plan
  qci_9: 29  # Arrière-plan (Priorité faible)
  default: 20

Génération de fichiers TAP3

Après que les CDR aient été tarifés par OmniCharge, OmniRoam génère des fichiers TAP3 conformes aux normes GSMA pour la facturation en gros.

Flux d'export TAP3

Structure du fichier TAP3

Convention de nommage des fichiers

Les fichiers TAP3 suivent les normes de nommage GSMA :

<TypeDeFichier><Expéditeur><Destinataire><NuméroDeSéquence>

Exemples :
CDAUSIEAAA0000001  - Fichier de données commerciales de AUSIE à AAA00, séquence 1
TDAUSIEAAA0000001  - Fichier de données de test de AUSIE à AAA00, séquence 1

Où :

• TypeDeFichier : CD (Commercial) ou TD (Test)
• Expéditeur : code TADIG de 5 caractères
• Destinataire : code TADIG de 5 caractères
• NuméroDeSéquence : séquence de 5 chiffres (provenant de counters.yaml)

Guide de configuration

Configuration des partenaires

Ajoutez des partenaires de roaming dans config.yaml :

partners:
  ONS_Live:
    imsi_prefixes:              # Liste des préfixes IMSI pour ce partenaire
      - 505057
    accessPointNameOI: mnc057.mcc505.gprs
    rates:
      unit_price: 0.000476800   # Prix par unité en dollars
      unit_bytes: 1024          # Nombre d'octets par unité
    batch_info:
      sender: AUSIE             # Votre code TADIG
      recipient: AAA00          # Code TADIG du partenaire
      specificationVersionNumber: 3
      releaseVersionNumber: 12
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'  # Haut/Bas/ simple
        tapDecimalPlaces: 5
    round_up_to: 1024           # Arrondir l'utilisation au kilo-octet le plus proche
    call_type_level:            # Mappage QCI à niveau de type d'appel
      qci_1: 20
      qci_2: 22
      default: 20

Configuration du compteur de séquence

Initialisez les compteurs de séquence dans counters.yaml :

AAA00:
  CD: 1     # Séquence de données commerciales
  TD: 1     # Séquence de données de test
AAA01:
  CD: 1
  TD: 1

Les séquences s'incrémentent automatiquement avec chaque fichier TAP généré.

Configuration du réseau

Configurez les mappages TAC-vers-emplacement :

config:
  tac_config:
    LocationName:
      tac_list: ['1101', '10000']
      servingBid: 72473
      servingLocationDescription: 'Emplacement du réseau'
      timezone: 'America/New_York'

Configuration InfluxDB

Configurez la connexion InfluxDB dans config.yaml :

config:
  influx_db:
    influxDbUrl: 'http://10.3.0.135:8086'
    influxDbOrg: 'omnitouch'
    influxDbBucket: 'Omnicharge_TAP3'
    influxDbToken: 'votre-token-ici'

Chemins de sortie

Configurez les emplacements de sortie des fichiers :

config:
  tap_output_path: '/etc/pytap3/OutputFiles'
  tap_human_readable_output_path: '/etc/pytap3/OutputFiles_Human'
  tap_in_path: '/home/user/TAP_In/'

Décisions architecturales

Pourquoi OmniCharge ?

OmniCharge fournit :

• Un puissant moteur de tarification avec des plans tarifaires flexibles
• Des capacités de tarification en temps réel
• Dé-duplication des CDR
• Des pistes d'audit complètes
• Intégration basée sur API

Pourquoi InfluxDB ?

Avantages :

• Optimisé pour les métriques CDR en série temporelle
• Débit d'écriture élevé
• Stockage efficace avec compression
• Échantillonnage intégré
• Intégration native avec Grafana

Résumé du flux de travail

---

OmniRoam - Gestion professionnelle des revenus de roaming par Omnitouch.