OmniRoam

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

Table des Matières

• Aperçu
• Guide des Opérations
  • Exécution de l'Export TAP3
  • Surveillance & Reporting
  • Dépannage
  • Support & Maintenance
• Architecture du Système
  • Aperçu de Haut Niveau
  • Processus d'Importation des CDR
  • Moteur de Tarification OmniCharge
  • Génération de Fichiers TAP3
• Guide de Configuration
  • Configuration des Partenaires
  • Configuration des Compteurs de Séquence
  • Configuration du Réseau
  • Configuration InfluxDB
• Décisions Architecturales

Aperçu

OmniRoam traite les CDRs de roaming des opérateurs de réseaux mobiles, les évalue à 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 d'Évaluation 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'exportation :

1. Interroge les CDRs des 30 derniers jours (exigence GSMA)
2. Filtre les CDRs marqués comme déjà traités
3. Exclut les CDRs avec un temps de fin inférieur à 1 heure (empêche les sessions incomplètes)
4. Regroupe les CDRs par partenaire de roaming
5. Génère un fichier TAP3 par partenaire
6. Marque les CDRs 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 & Reporting

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

Métriques Collectées

Métriques CDR Brutes Poussées pendant le processus d'importation et d'évaluation 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 fichier 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 CDRs dans le fichier TAP3

Requêtes de Tableau de Bord

Exemples de requêtes InfluxDB pour la surveillance :

Revenus 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)

Revenus 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 modèles de trafic
• Suivi des performances des partenaires
• Utilisation des ressources réseau
• Détection d'anomalies
• Réconciliation de facturation

Dépannage

Problèmes d'Importation des 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 :

• Aucun 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 non trouvé
• 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 & 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 l'arriéré de CDR - Assurer un traitement en temps opportun

Architecture du Système

Aperçu de Haut Niveau

Processus d'Importation des 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 CDRs complets et facturables.

Comprendre les CDRs 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 le Cache pour l'Agrégation des CDR ?

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

• Recherches clé-valeur rapides - Trouver instantanément les CDRs 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 sécurisées et concurrentes provenant de plusieurs processus d'importation
• Persistance - Les CDRs survivent aux redémarrages du système pendant la fenêtre d'agrégation

Architecture d'Importation en Deux Étapes

Étape 1 : Analyse CSV et Agrégation des CDRs Partiels

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

Comment les CDRs 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 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 de 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 CDRs Partiels Sont Agrégés

Lorsque le parseur 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
   • Stocker 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 de Vérification 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 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 de vérification 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 des partenaires contestent un coût, les opérateurs peuvent montrer exactement quels fichiers sources y ont contribué
• Réconciliation 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 suivant 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 :

• L'horodatage le plus ancien parmi tous les enregistrements partiels (début de la session)
• L'horodatage le plus récent parmi tous les enregistrements partiels (fin de la session)
• Durée = Dernier - Premier

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

Étape 2 : Assemblage et Tarification des CDRs

La deuxième étape scanne périodiquement le Cache pour les sessions complètes, assemble les CDRs finaux et les soumet à OmniCharge pour tarification.

Comment les CDRs Complets Sont Sélectionnés du Cache

Le Processus d'Assemblage des CDRs 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
   • Sauter si trop ancien (> 30 jours) : Supprimer du Cache (évite l'accumulation de données obsolètes)
   • Sauter 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 jusqu'à 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 CDRs

Avant la tarification, chaque CDR assemblé passe par la validation et l'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 CDRs invalides :

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

3. Calculer l'utilisation finale :

   • Additionner 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 évalué 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 Entrantes/Sortantes, Total des Unités Facturables
• Informations de Localisation : BID de Service (ID du Réseau), Localisation Géographique
• Informations QoS : QCI (Identifiant de Classe de QoS)

Règles de Traitement des Données

Arrondi des Utilisations

Les CDRs 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 :

• Conversion de fuseau horaire appropriée pour les horodatages
• Attribution d'un emplacement géographique
• Identification du réseau de service

Moteur de Tarification OmniCharge

OmniRoam envoie les CDRs à OmniCharge, le puissant moteur de tarification qui calcule les coûts 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 CDRs aux partenaires de roaming en utilisant l'appariement de préfixe IMSI avec la logique du plus long match en premier. Cela permet aux opérateurs de créer des configurations spécifiques pour les SIMs 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 SIMs 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  # Pas de frais 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 le 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 du 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  # Jeux en Temps Réel
  qci_4: 24  # Streaming Tamponné
  qci_5: 20  # Signalisation IMS
  qci_6: 26  # Interactif (Navigation)
  qci_7: 27  # Interactif (Jeux)
  qci_8: 28  # Arrière-plan
  qci_9: 29  # Arrière-plan (Priorité Basse)
  default: 20

Génération de Fichiers TAP3

Après que les CDRs aient été évalués par OmniCharge, OmniRoam génère des fichiers TAP3 conformes aux normes GSMA pour la facturation de 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 vers Niveau de Type d'Appel
      qci_1: 20
      qci_2: 22
      default: 20

Configuration des Compteurs 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-localisation :

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: 'your-token-here'

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 moteur de tarification puissant avec des plans tarifaires flexibles
• Des capacités de tarification en temps réel
• Dé-duplication des CDR
• Pistes d'audit complètes
• Intégration basée sur API

Pourquoi InfluxDB ?

Avantages :

• Optimisé pour les métriques CDR en série temporelle
• Haut débit d'écriture
• 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.