Pular para o conteúdo principal

Referência de Métricas

Este documento descreve todas as métricas do Prometheus expostas pelo OmniUPF no endpoint /api/metrics (a API HTTP roda na api_port, padrão 8080). Note o prefixo /api - cada rota da API é servida sob ele.

Todas as métricas são declaradas em lib/upf_ex/prometheus_metrics.ex. Os nomes, tipos e rótulos das métricas abaixo são retirados diretamente dessa fonte; se o código mudar, atualize este arquivo para corresponder.

Categorias de Métricas​

  1. Métricas PFCP - contadores de mensagens de controle, associações, sessões e erros
  2. Métricas do ciclo de vida da sessão - contadores de criação/exclusão/modificação de sessões e latência de estabelecimento
  3. Métricas de buffer de pacotes - estado do buffer e throughput para buffering de downlink de UE ocioso
  4. Métricas de Relatório de Dados de Downlink (DLDR) - notificações de Solicitação de Relatório de Sessão PFCP e rastreamento de índice FAR
  5. Métricas GTP-U - respostas de eco e contadores de Indicação de Erro
  6. Métricas URR - contadores de relatórios de uso e temporizadores URR ativos
  7. Métricas de mapa eBPF - medidores de entradas de mapa do plano de dados
  8. Throughput do plano de dados - contadores por direção (N3/N6), sob demanda via /api/v1/xdp_stats apenas (não é uma métrica de raspagem — veja #57)
  9. Métricas de recursos / roteamento - medidores de pool TEID/FAR-ID e rotas de UE
  10. Métricas de Jardim Murado - intercepção de portal cativo, encaminhamento e contadores de spoofing de DNS

Métricas PFCP​

Contadores de protocolo de plano de controle entre o UPF e seus pares PFCP (SMF / PGW-C / SGW-C).

Nome da MétricaTipoRótulosDescrição
upf_pfcp_associationsGaugenoneAssociações PFCP atualmente ativas (todos os pares)
upf_pfcp_sessionsGaugenoneSessões PFCP atualmente ativas (todos os pares)
upf_pfcp_peer_restarts_totalCounterpeerDetecções de reinício de pares (mudança de Timestamp de Recuperação)
upf_pfcp_duplicate_requests_totalCounternoneSolicitações PFCP duplicadas detectadas e suprimidas
upf_orphaned_sessions_deleted_totalCounternoneSessões excluídas como resultado de um reinício de par
upf_pfcp_messages_rx_totalCountertype, peerMensagens PFCP recebidas por tipo de mensagem e par
upf_pfcp_messages_tx_totalCountertype, peerMensagens PFCP enviadas por tipo de mensagem e par
upf_pfcp_errors_totalCountertypeRejeições de solicitações PFCP, rotuladas pela causa da rejeição (por exemplo, session_context_not_found, mandatory_ie_missing)

Métricas do ciclo de vida da sessão​

Nome da MétricaTipoRótulosDescrição
upf_sessions_created_totalCounternoneSessões PFCP estabelecidas
upf_sessions_deleted_totalCounternoneSessões PFCP excluídas
upf_sessions_modified_totalCounternoneSessões PFCP modificadas
upf_session_establishment_duration_microsecondsHistogramnoneTempo de processamento para estabelecimento de sessão (microsegundos). Baldes: 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000

Métricas de buffer de pacotes​

O UPF armazena pacotes de downlink quando um UE está ocioso, segurando-os até que o UE seja chamado e transite para conectado. Os pacotes chegam do plano de dados eBPF na porta UDP do buffer (padrão 22152).

Nome da MétricaTipoRótulosDescrição
upf_buffer_packets_received_totalCounternonePacotes recebidos na porta do buffer do plano de dados
upf_buffer_packets_buffered_totalCounternonePacotes adicionados com sucesso ao buffer
upf_buffer_packets_flushed_totalCounternonePacotes esvaziados do buffer
upf_buffer_packets_dropped_totalCounterreasonPacotes descartados de / não admitidos no buffer
upf_buffer_packets_currentGaugenonePacotes atualmente mantidos no buffer
upf_buffer_flush_operations_totalCounternoneOperações de esvaziamento de buffer bem-sucedidas (por esvaziamento de FAR)
upf_buffer_flush_packets_sent_totalCounternonePacotes enviados durante operações de esvaziamento
upf_buffer_flush_errors_totalCounterreasonOperações de esvaziamento de buffer com falha

Valores de reason para upf_buffer_packets_dropped_total (de descartes de adição ao buffer e erros do ouvinte do buffer):

  • global_limit - capacidade total do buffer (buffer_max_total) alcançada
  • far_limit - limite de buffer por-FAR (buffer_max_per_far) alcançado
  • expired - TTL (buffer_ttl_ms) excedido antes do esvaziamento
  • read_error - erro ao ler do socket do buffer
  • too_small - pacote muito pequeno para um cabeçalho GTP
  • invalid_gtp_type - tipo de mensagem GTP não-G-PDU
  • unknown_teid - nenhum PDR/FAR encontrado para o TEID
  • not_buffering_far - FAR não possui uma ação BUFF

Valores de reason para upf_buffer_flush_errors_total:

  • far_lookup_failed - não foi possível procurar informações do FAR no mapa eBPF
  • no_forw_action - FAR não possui uma ação FORW definida
  • connection_failed - falha ao abrir um socket UDP para esvaziamento

Métricas para notificações de Solicitação de Relatório de Sessão PFCP enviadas ao plano de controle quando pacotes de downlink são armazenados. Essas notificações acionam o SMF/PGW-C para chamar o UE.

Nome da MétricaTipoRótulosDescrição
upf_dldr_sent_totalCounterpeerRelatórios de Dados de Downlink enviados, rotulados pelo endereço SMF/PGW-C
upf_dldr_errors_totalCounternoneErros de codificação / envio de DLDR
upf_dldr_skipped_totalCounternoneDLDRs ignorados porque o FAR já foi notificado
upf_far_index_sizeGaugenoneFARs registrados no FarIndex para notificação DLDR

Métricas GTP-U​

Contadores de gerenciamento de caminho GTP-U e Indicação de Erro. Indicações de Erro são trocadas quando um par recebe pacotes para um TEID desconhecido (tipicamente após um reinício).

Nome da MétricaTipoRótulosDescrição
upf_gtpu_echo_responses_tx_totalCounternoneRespostas de Eco GTP-U enviadas
upf_gtpu_error_indications_sent_totalCounternoneIndicações de Erro GTP-U enviadas (para TEIDs de entrada desconhecidos)
upf_gtpu_error_indications_rx_totalCounternoneIndicações de Erro GTP-U recebidas de pares
upf_error_indication_sessions_deleted_totalCounternoneSessões excluídas como resultado de uma Indicação de Erro

Quando Indicações de Erro são enviadas: o UPF recebe um pacote GTP-U para um TEID que não existe (por exemplo, após um reinício, ou a sessão já foi excluída), e informa o remetente para parar.

Quando Indicações de Erro são recebidas: um par a montante não reconhece um TEID que o UPF encaminhou; o UPF exclui a sessão afetada para parar de encaminhar para um túnel morto.

Métricas URR (Regra de Relatório de Uso)​

Nome da MétricaTipoRótulosDescrição
upf_urr_reports_sent_totalCountertriggerRelatórios de uso URR enviados, rotulados pelo gatilho de relatório
upf_urr_report_errors_totalCounternoneErros de codificação / envio de relatórios URR
upf_urr_active_timersGaugenoneTemporizadores URR ativos (periódicos / limite de tempo / validade de cota)

trigger reflete o gatilho de relatório URR que foi acionado - por exemplo, periodic (PERIO), volume_threshold (VOLTH), time_threshold (TIMTH), quota_validity (QUVTI).

Contadores de bytes por URR não são exportados como métricas do Prometheus (para evitar alta cardinalidade). Leia estatísticas individuais de URR via a API REST em /api/v1/urr_map.

Métricas de mapa eBPF​

Medidores para utilização do mapa do plano de dados, atualizados em cada raspagem.

Nome da MétricaTipoRótulosDescrição
upf_ebpf_far_entriesGaugenoneEntradas FAR no mapa eBPF
upf_ebpf_pdr_uplink_entriesGaugenoneEntradas PDR de uplink no mapa eBPF (PDRs com um TEID)
upf_ebpf_pdr_downlink_entriesGaugenoneEntradas PDR de downlink no mapa eBPF (PDRs indexados por IP de UE)

upf_ebpf_far_entries espelha o pool de id-FAR alocado (upf_far_ids_allocated), uma vez que o far_map mantém uma entrada por id-FAR alocado. Os medidores de PDR são agregados a partir do estado da sessão ativa em cada raspagem (custo é O(total de sessões)).

Throughput do plano de dados (apenas sob demanda — não é uma métrica de raspagem do Prometheus)​

Contadores de pacotes e bytes por direção para tráfego do plano de usuário (N3 = lado GTP-U em direção ao gNB/eNB; N6 = lado SGi em direção à rede de dados) vêm do mapa percpu upf_ext_stat do eBPF.

Removido da raspagem do Prometheus (issue #57). Esses foram anteriormente exportados como medidores upf_n3_* / upf_n6_*, populados em cada raspagem de /api/metrics por um bpf_map_lookup_elem no mapa upf_ext_stat — o mesmo mapa por CPU que o caminho XDP escreve em cada pacote. Essa leitura por raspagem provou acionar um wedge de TX-ring genérico-XDP virtio_net (com a raspagem bloqueada, a carga exata que quebrou rodou 30/30 ciclos com zero NETDEV WATCHDOG). Para manter o caminho das métricas longe do plano de dados, esses medidores não são mais coletados ou exportados.

Como ler contadores N3/N6 ao vivo agora: GET /api/v1/xdp_stats retorna os mesmos campos como JSON, e toca no eBPF apenas quando você o chama explicitamente (não em um timer, não em uma raspagem do Prometheus). Campos: rx_n3 / tx_n3 / rx_n6 / tx_n6 (pacotes) e rx_n3_bytes / tx_n3_bytes / rx_n6_bytes / tx_n6_bytes.

Throughput durável por direção no Prometheus deve vir em vez disso da correção de substrato que permite que o plano de dados seja observado com segurança (veja #57), ou de um contador externo (por exemplo, os contadores de bytes do host/tap).

Métricas de recursos / roteamento​

Nome da MétricaTipoRótulosDescrição
upf_routes_totalGaugenoneRotas IP de UE atualmente rastreadas pelo gerenciador de rotas
upf_teid_allocatedGaugenoneTEIDs atualmente alocados do pool
upf_far_ids_allocatedGaugenoneIDs FAR atualmente alocados do pool

Métricas de Jardim Murado​

Contadores para o jardim murado de crédito esgotado / portal cativo. Veja o Guia do Jardim Murado para comportamento.

Nome da MétricaTipoRótulosDescrição
upf_walled_garden_active_redirectsGaugenoneSessões de redirecionamento ativas do jardim murado
upf_walled_garden_packets_intercepted_totalCounternonePacotes interceptados pelo jardim murado
upf_walled_garden_packets_dropped_totalCounternonePacotes descartados pelo jardim murado
upf_walled_garden_packets_forwarded_totalCounterdst_ipPacotes na lista de permissões encaminhados, por IP de destino
upf_walled_garden_bytes_forwarded_totalCounterdst_ipBytes na lista de permissões encaminhados, por IP de destino
upf_walled_garden_dns_spoofed_totalCounterdomainConsultas DNS falsificadas para o portal, por domínio
upf_walled_garden_dns_forwarded_totalCounterdomainConsultas DNS encaminhadas (domínios na lista de permissões), por domínio

Nota de cardinalidade. Os rótulos dst_ip e domain são ilimitados. Mantenha a lista de permissões restrita e agregue esses rótulos em regras de gravação se você raspagem um jardim murado movimentado.

Usando Métricas do Prometheus​

Acessando Métricas​

As métricas são expostas no endpoint /api/metrics do servidor da API HTTP, que escuta na api_port (padrão 8080). Note o prefixo /api - cada rota da API é servida sob ele:

# Visualizar métricas brutas
curl http://localhost:8080/api/metrics

# Exemplo de saída
upf_pfcp_sessions 42
upf_pfcp_associations 2
upf_dldr_sent_total{peer="10.100.50.241"} 17

Configuração do Prometheus​

Adicione o alvo OmniUPF ao seu prometheus.yml:

scrape_configs:
  - job_name: 'omniupf'
    metrics_path: /api/metrics
    static_configs:
      - targets: ['localhost:8080']

Painéis do Grafana​

Painéis úteis para construir a partir dessas métricas:

  • Contagens de sessões e associações (upf_pfcp_sessions, upf_pfcp_associations)
  • Throughput N3/N6 por direção está disponível sob demanda via /api/v1/xdp_stats (removido da raspagem — veja #57)
  • Pressão do buffer (upf_buffer_packets_current, taxa de descarte por reason)
  • Atividade DLDR / chamada (rate(upf_dldr_sent_total[5m]))
  • Taxas de Indicação de Erro e reinício de pares para alerta de saúde do túnel

Documentação Relacionada​

Última atualização em