OmniRoam

OmniRoam é a solução abrangente de gerenciamento de receita por atacado da Omnitouch para operadores de roaming. Ele gerencia todo o ciclo de vida dos CDRs de dados de roaming (Registros de Detalhes de Chamadas), desde a ingestão até a classificação, geração de arquivos TAP3 e relatórios.

Índice

• Visão Geral
• Guia de Operações
  • Executando Exportação TAP3
  • Monitoramento e Relatórios
  • Solução de Problemas
  • Suporte e Manutenção
• Arquitetura do Sistema
  • Visão Geral de Alto Nível
  • Processo de Importação de CDR
  • Motor de Classificação OmniCharge
  • Geração de Arquivo TAP3
• Guia de Configuração
  • Configuração de Parceiros
  • Configuração do Contador de Sequência
  • Configuração de Rede
  • Configuração do InfluxDB
• Decisões de Arquitetura

Visão Geral

OmniRoam processa CDRs de roaming de operadores de rede móvel, classifica-os usando o motor de classificação OmniCharge, gera arquivos TAP3 compatíveis com a GSMA para faturamento e fornece capacidades abrangentes de monitoramento e relatórios.

Processo de Importação e Classificação de CDR

Processo de Exportação TAP3

Guia de Operações

Executando Exportação TAP3

# Exportar para parceiro específico
python3 export_TAP3.py VZW_Live

# Modo interativo (solicita parceiro)
python3 export_TAP3.py

O processo de exportação:

1. Consulta CDRs dos últimos 30 dias (requisito GSMA)
2. Filtra CDRs marcados como já processados
3. Exclui CDRs com hora de término inferior a 1 hora atrás (previne sessões incompletas)
4. Agrupa CDRs por parceiro de roaming
5. Gera arquivo TAP3 por parceiro
6. Marca CDRs como processados no banco de dados
7. Incrementa contador de sequência
8. Envia métricas para InfluxDB

Monitoramento e Relatórios

OmniRoam envia métricas em tempo real para InfluxDB para monitoramento e análises.

Métricas Coletadas

Métricas de CDR Bruto Enviadas durante o processo de importação e classificação de CDR:

• operator: Identificador do parceiro de roaming
• input_file: Nome do arquivo CSV de origem
• apn: Nome do Ponto de Acesso (identificador do serviço de dados)
• cellId: Identificador da torre de celular
• imsi: Identidade do assinante
• tac: Código da Área de Rastreamento
• sGWAddress: Endereço IP do Gateway de Serviço
• pGWAddress: Endereço IP do Gateway PDN
• chargeableUnits: Total de bytes de uso
• chargedUnits: Custo calculado

Métricas de Exportação TAP Enviadas durante o processo de geração do arquivo TAP3:

• operator: Identificador do parceiro de roaming
• filename: Nome do arquivo TAP3 gerado
• totalcharge: Custo total no arquivo TAP3
• totalconsumed: Total de bytes no arquivo TAP3
• cdr_count: Número de CDRs no arquivo TAP3

Consultas de Dashboard

Exemplo de consultas InfluxDB para monitoramento:

Receita por Operador

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

Uso de Dados por TAC

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

Volume de CDR por Hora

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

Receita por APN

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

Integração com Grafana

Crie dashboards Grafana usando essas métricas para:

• Monitoramento de receita em tempo real
• Análise de padrões de tráfego
• Acompanhamento de desempenho de parceiros
• Utilização de recursos de rede
• Detecção de anomalias
• Reconciliação de faturamento

Solução de Problemas

Problemas de Importação de CDR

Verifique os logs em /tmp/import_CDR_Logger_Marben_*.log

Problemas comuns:

• Formato de IMSI inválido
• Campos obrigatórios ausentes
• Erros de conversão de fuso horário
• IDs de cobrança duplicados

Problemas de Exportação TAP3

Verifique os logs em /tmp/tap3_export_*.log

Problemas comuns:

• Sem CDRs nos últimos 30 dias
• Configuração de TAC ausente
• Número de sequência inválido
• Erros de conexão com o banco de dados

Erros de Classificação OmniCharge

Revise os logs do OmniCharge para:

• Planos de tarifas ausentes
• Conta não encontrada
• Valores de uso inválidos
• Erros de conversão de moeda

Problemas de Conexão com InfluxDB

Verifique:

• URL do InfluxDB acessível
• Token de autenticação válido
• Bucket existe
• Conectividade de rede

Suporte e Manutenção

Localizações de Log

• Importação de CDR: /tmp/import_CDR_Logger_Marben_*.log
• Exportação TAP: /tmp/tap3_export_*.log

Principais Arquivos de Configuração

• config.yaml - Configuração principal (tarifas de parceiros, configurações de rede, conexão InfluxDB)
• counters.yaml - Contadores de sequência de arquivos TAP3

Tarefas Regulares de Manutenção

1. Monitorar contadores de sequência - Garantir que não excedam 99999
2. Arquivar arquivos TAP antigos - Mover arquivos mais antigos que o período de retenção
3. Monitorar uso de disco do InfluxDB - Configurar políticas de retenção
4. Revisar configurações de tarifas - Atualizar quando as tarifas dos parceiros mudarem
5. Fazer backup dos arquivos de configuração - config.yaml e counters.yaml
6. Monitorar backlog de CDR - Garantir processamento em tempo hábil

Arquitetura do Sistema

Visão Geral de Alto Nível

Processo de Importação de CDR

OmniRoam utiliza um processo de importação em duas etapas com o Cache como uma camada de agregação temporária para montar registros de CDR parciais em CDRs completos e faturáveis.

Compreendendo CDRs Parciais

Elementos de rede móvel (S-GW/P-GW) não geram um único CDR para uma sessão de dados. Em vez disso, eles produzem múltiplos registros de CDR parciais ao longo do ciclo de vida da sessão:

• Registro de Início: Gerado quando a sessão de dados começa
• Registros de Atualização: Gerados periodicamente durante a sessão (por exemplo, a cada 15 minutos ou a cada 100 MB de uso de dados)
• Registro de Parada: Gerado quando a sessão termina

Cada registro parcial contém dados de uso incrementais. Para faturamento preciso, o OmniRoam deve:

1. Identificar quais registros parciais pertencem à mesma sess��o de dados
2. Agregar os dados de uso de todos os registros parciais
3. Calcular a duração total da sessão
4. Montar um CDR completo representando toda a sessão

Por que Cache para Agregação de CDR?

O Cache serve como uma área de armazenamento temporário de alto desempenho onde os CDRs parciais se acumulam até que a sessão esteja completa. O Cache fornece:

• Pesquisas rápidas de chave-valor - Encontrar instantaneamente CDRs parciais existentes para uma sessão
• Armazenamento em memória - Operações de leitura/gravação de alta velocidade para agregação em tempo real
• Operações atômicas - Atualizações seguras e concorrentes de múltiplos processos de importação
• Persistência - CDRs sobrevivem a reinicializações do sistema durante a janela de agregação

Arquitetura de Importação em Duas Etapas

Etapa 1: Análise CSV e Agregação de CDR Parcial

A primeira etapa lê continuamente arquivos CSV de elementos de rede S-GW e agrega CDRs parciais no Cache.

Como CDRs Parciais São Identificados e Correspondidos

OmniRoam deve determinar quais registros parciais pertencem à mesma sessão de dados. Cada sessão é identificada de forma única por um ID de Sessão composto por:

• ID de Cobrança: Identificador único da sessão do elemento de rede
• IMSI: Identidade do assinante (identificador do número móvel)
• Data: Data da sessão no fuso horário da rede que atende
• Endereço IP do P-GW: Gateway que tratou a sessão
• TAC: Código da Área de Rastreamento (localização da torre de celular)
• QCI: Classe de Qualidade de Serviço

Essa combinação garante que todos os registros parciais da mesma sessão de dados sejam agrupados, mesmo quando vários arquivos chegam fora de ordem.

Como CDRs Parciais São Agregados

Quando o parser CSV processa cada CDR parcial:

1. Gerar ID da Sessão a partir dos campos do CDR
2. Verificar Cache para ver se essa sessão já existe
3. Se a sessão existir no Cache:
   • Recuperar os dados acumulados do CDR
   • Verificar se este arquivo não foi processado antes (previne duplicatas)
   • Adicionar os novos dados de uso: bytes de entrada + bytes de saída
   • Atualizar a duração da sessão usando os timestamps mais antigos e mais recentes
   • Armazenar metadados sobre este registro parcial para fins de auditoria
   • Salvar o CDR atualizado de volta no Cache
4. Se nova sess��o:
   • Criar uma nova entrada de CDR no Cache
   • Inicializar contadores de uso e metadados da sessão
   • Registrar o timestamp do primeiro registro parcial

Rastro de Auditoria e Metadados

Cada registro parcial que contribui para um CDR é rastreado com metadados abrangentes:

• Nome do arquivo de origem: Qual arquivo CSV continha este registro parcial
• Timestamp: Quando o elemento de rede gerou este registro
• Tempo de processamento: Quando o OmniRoam o recebeu e processou
• Contribuição de uso: Quanto de dados este parcial adicionou (bytes de entrada/saída)
• Tipo de evento: Se este foi um registro de início, atualização ou parada
• Fuso horário da rede que atende: Para conversão precisa de timestamps

Por que os metadados são críticos para contabilidade:

Esse rastro de auditoria permite que o OmniRoam rastreie uma única cobrança de ponta a ponta através de cada estágio de processamento, o que é essencial para:

• Resolução de disputas: Quando parceiros contestam uma cobrança, os operadores podem mostrar exatamente quais arquivos de origem contribuíram para isso
• Reconciliação de receita: Verificar se todo o uso faturável foi capturado e nada foi perdido ou duplicado
• Conformidade regulatória: Demonstrar o manuseio adequado dos registros de faturamento para fins de auditoria
• Depuração: Identificar rapidamente problemas no processo de agregação de CDR rastreando o fluxo de dados completo
• Precisão financeira: Garantir que cada dólar cobrado possa ser rastreado até eventos de rede específicos

Cálculo da Duração da Sessão

A duração total da sessão é calculada encontrando:

• Timestamp mais antigo entre todos os registros parciais (início da sessão)
• Timestamp mais recente entre todos os registros parciais (término da sessão)
• Duração = Mais recente - Mais antigo

Para sessões onde apenas registros de atualização existem (faltando início/parada), a duração padrão é de 24 horas.

Etapa 2: Montagem de CDR e Classificação

A segunda etapa escaneia periodicamente o Cache em busca de sessões completas, monta os CDRs finais e os envia para o OmniCharge para classificação.

Como CDRs Completos São Selecionados do Cache

O Processo de Montagem de CDR é executado continuamente e examina todas as sessões armazenadas no Cache:

1. Escanear o Cache em busca de todas as sessões de CDR acumuladas
2. Processar em lotes de 1.000 sessões por vez
3. Para cada sessão:
   • Extrair a data da sessão do ID da Sessão
   • Pular se muito antiga (> 30 dias): Deletar do Cache (previne acúmulo de dados obsoletos)
   • Pular se muito recente (< 24 horas): Deixar no Cache para mais registros parciais chegarem
   • Carregar o CDR completo com todos os dados acumulados

O Período de Espera de 24 Horas

Por que o OmniRoam espera 24 horas antes de classificar um CDR?

• Registros parciais chegam fora de ordem: Congestionamento da rede pode atrasar a entrega de arquivos CSV por horas
• Sessões que atravessam a meia-noite: Uma sessão que começa às 11:50 PM gera arquivos em duas datas diferentes. O mesmo ID de cobrança pode abranger vários dias, com registros parciais datados de forma diferente
• Registros de atualização estão atrasados: Registros de atualização periódicos podem chegar muito depois que a sessão termina
• Geração de arquivos assíncrona: Diferentes elementos de rede exportam arquivos em horários diferentes
• Sessões de longa duração: Sessões de dados podem durar horas ou dias, com registros de atualização chegando ao longo do tempo

Ao esperar 24 horas, o OmniRoam garante que todos os registros parciais tenham chegado e que o CDR esteja realmente completo antes da cobrança.

Validação e Enriquecimento de CDR

Antes da classificação, cada CDR montado passa por validação e enriquecimento:

1. Validar completude:

   • Verificar se os registros de início/parada estão presentes
   • Se apenas registros de atualização existirem, definir a duração para 24 horas (padrão)

2. Descartar CDRs inválidos:

   • Sessões com uso zero são deletadas (sem atividade faturável)

3. Calcular uso final:

   • Somar todos os bytes de entrada e saída
   • Aplicar regras de arredondamento específicas do parceiro (por exemplo, arredondar para cima para o KB mais próximo)

4. Enriquecer com dados de localização:

   • Mapear TAC (Código de Área de Rastreamento) para a localização da rede que atende
   • Adicionar informações de fuso horário para timestamps precisos
   • Adicionar descrição da localização geográfica

5. Enviar para OmniCharge:

   • Enviar o CDR completo e enriquecido para classificação
   • Receber de volta o custo calculado

6. Armazenar e limpar:

   • Salvar o CDR classificado no banco de dados
   • Enviar métricas para InfluxDB para relatórios
   • Deletar o CDR processado do Cache

Estrutura de Dados do CDR

Cada CDR agregado contém:

• Informações do Assinante: IMSI, MSISDN, IMEI
• Informações da Rede: Gateway de Serviço (S-GW), Gateway PDN (P-GW), ID da Célula, TAC (Código de Área de Rastreamento)
• Detalhes da Sessão: Timestamps de Início/Fim, Duração, APN (Nome do Ponto de Acesso)
• Dados de Uso: Volume de Dados de Entrada/Saída, Total de Unidades Faturáveis
• Informações de Localização: BID de Atendimento (ID da Rede), Localização Geográfica
• Informações de QoS: QCI (Identificador da Classe de QoS)

Regras de Processamento de Dados

Arredondamento de Uso

Os CDRs são arredondados com base na configuração específica do parceiro em config.yaml:

partners:
  Example_Live:
    round_up_to: 1024  # Arredondar uso para o KB mais próximo

O sistema:

1. Calcula o uso total: dataVolumeIncoming + dataVolumeOutgoing
2. Arredonda para a unidade configurada (por exemplo, 1024 bytes)
3. Preserva os valores originais para auditoria

Localização Baseada em TAC

O sistema determina a localização da rede que atende com base no TAC (Código de Área de Rastreamento):

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

Isso permite:

• Conversão adequada de fuso horário para timestamps
• Atribuição de localização geográfica
• Identificação da rede que atende

Motor de Classificação OmniCharge

OmniRoam envia CDRs para OmniCharge, o poderoso motor de classificação que calcula cobranças com base em planos de tarifas configuráveis.

Processo de Classificação

Configuração de Tarifas

As tarifas são configuradas por parceiro de roaming no arquivo de configuração:

partners:
  Example_Live:
    imsi_prefixes:
      - 99901
    rates:
      unit_price: 0.000476800  # Preço por unidade
      unit_bytes: 1024          # Tamanho da unidade em bytes
    batch_info:
      sender: AUSIE
      recipient: AAA00
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'
        tapDecimalPlaces: 5

Correspondência de Prefixo IMSI

OmniRoam corresponde CDRs a parceiros de roaming usando correspondência de prefixo IMSI com lógica de maior correspondência primeiro. Isso permite que os operadores criem configurações específicas para SIMs de teste enquanto mantêm configurações gerais para tráfego de produção.

Como Funciona a Correspondência de Prefixo

Ao classificar um CDR, o OmniRoam:

1. Extrai o IMSI do CDR (por exemplo, 310410123456789)
2. Avalia todas as configurações de parceiros em ordem
3. Encontra o prefixo correspondente mais longo
4. Aplica as tarifas e configurações desse parceiro

Exemplo: Configuração de SIM de Teste

Esse recurso é particularmente útil para testes TADIG/IREG onde SIMs de teste precisam de tratamento diferente:

partners:
  Demo_Test:
    imsi_prefixes:
      - 0010112345123  # Faixa de SIM de teste (prefixo de 9 dígitos)
    rates:
      unit_price: 0.0  # Sem cobrança para tráfego de teste
    batch_info:
      sender: AUSIE
      recipient: AAA00TEST

  Demo_Production:
    imsi_prefixes:
      - 001011  # Faixa de produção (prefixo de 6 dígitos)
    rates:
      unit_price: 0.000476800
    batch_info:
      sender: AUSIE
      recipient: AAA00

Comportamento de correspondência:

• IMSI 00101123451234 → Corresponde a Demo_Test (prefixo de 9 dígitos é mais longo)
• IMSI 00101023456789 → Corresponde a Demo_Production (prefixo de 6 dígitos)

Isso garante que o tráfego de teste vá para arquivos TAP de teste com códigos TADIG de teste, enquanto o tráfego de produção é faturado normalmente com códigos TADIG de produção.

Cálculo de Classificação

Para cada CDR:

1. Correspondência de Parceiro: Identificar parceiro de roaming pelo prefixo IMSI
2. Calcular Unidades: totalBytes / unit_bytes
3. Aplicar Tarifa: units × unit_price = charge
4. Aplicar Arredondamento: Arredondar com base em roundingAction (Cima/Baixo/Simple)
5. Converter para Unidades TAP: Multiplicar por 1000 para formato TAP3

Exemplo:

Uso: 52.428.800 bytes (50 MB)
Tamanho da Unidade: 1024 bytes
Unidades: 51.200
Tarifa: $0.000476800 por 1KB
Custo: 51.200 × $0.000476800 = $24.41
Unidades TAP: 24.410 (24.41 × 1000)

Atribuição de Tipo de Chamada Baseada em QCI

Classes de Qualidade de Serviço (QCI) são mapeadas para Níveis de Tipo de Chamada TAP3:

call_type_level:
  qci_1: 20  # Conversacional (Voz)
  qci_2: 22  # Conversacional (Vídeo)
  qci_3: 23  # Jogos em tempo real
  qci_4: 24  # Streaming com buffer
  qci_5: 20  # Sinalização IMS
  qci_6: 26  # Interativo (Navegação)
  qci_7: 27  # Interativo (Jogos)
  qci_8: 28  # Em segundo plano
  qci_9: 29  # Em segundo plano (Baixa Prioridade)
  default: 20

Geração de Arquivo TAP3

Após os CDRs serem classificados pelo OmniCharge, o OmniRoam gera arquivos TAP3 padrão da GSMA para faturamento por atacado.

Fluxo de Exportação TAP3

Estrutura do Arquivo TAP3

Convenção de Nomenclatura de Arquivos

Os arquivos TAP3 seguem os padrões de nomenclatura da GSMA:

<TipoDeArquivo><Remetente><Recebedor><NúmeroDeSequência>

Exemplos:
CDAUSIEAAA0000001  - Arquivo de Dados Comercial de AUSIE para AAA00, sequência 1
TDAUSIEAAA0000001  - Arquivo de Dados de Teste de AUSIE para AAA00, sequência 1

Onde:

• TipoDeArquivo: CD (Comercial) ou TD (Teste)
• Remetente: código TADIG de 5 caracteres
• Recebedor: código TADIG de 5 caracteres
• NúmeroDeSequência: sequência de 5 dígitos (do counters.yaml)

Guia de Configuração

Configuração de Parceiros

Adicione parceiros de roaming em config.yaml:

partners:
  ONS_Live:
    imsi_prefixes:              # Lista de prefixos IMSI para este parceiro
      - 505057
    accessPointNameOI: mnc057.mcc505.gprs
    rates:
      unit_price: 0.000476800   # Preço por unidade em dólares
      unit_bytes: 1024          # Número de bytes por unidade
    batch_info:
      sender: AUSIE             # Seu código TADIG
      recipient: AAA00          # Código TADIG do parceiro
      specificationVersionNumber: 3
      releaseVersionNumber: 12
      accountingInfo:
        localCurrency: 'USD'
        tapCurrency: 'USD'
        roundingAction: 'Simple'  # Cima/Baixo/Simple
        tapDecimalPlaces: 5
    round_up_to: 1024           # Arredondar uso para o N bytes mais próximo
    call_type_level:            # Mapeamento de QCI para Nível de Tipo de Chamada
      qci_1: 20
      qci_2: 22
      default: 20

Configuração do Contador de Sequência

Inicialize contadores de sequência em counters.yaml:

AAA00:
  CD: 1     # Sequência de Dados Comerciais
  TD: 1     # Sequência de Dados de Teste
AAA01:
  CD: 1
  TD: 1

As sequências são incrementadas automaticamente a cada arquivo TAP gerado.

Configuração de Rede

Configure mapeamentos TAC-para-localização:

config:
  tac_config:
    LocationName:
      tac_list: ['1101', '10000']
      servingBid: 72473
      servingLocationDescription: 'Localização da Rede'
      timezone: 'America/New_York'

Configuração do InfluxDB

Configure a conexão do InfluxDB em config.yaml:

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

Caminhos de Saída

Configure locais de saída de arquivos:

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

Decisões de Arquitetura

Por que OmniCharge?

OmniCharge fornece:

• Motor de classificação poderoso com planos de tarifas flexíveis
• Capacidades de classificação em tempo real
• Deduplicação de CDR
• Trilhas de auditoria abrangentes
• Integração baseada em API

Por que InfluxDB?

Vantagens:

• Otimizado para métricas de CDR
• Alta taxa de escrita
• Armazenamento eficiente com compressão
• Downsampling embutido
• Integração nativa com Grafana

Resumo do Fluxo de Trabalho

---

OmniRoam - Gestão profissional de receita de roaming pela Omnitouch.