Pular para o conteúdo principal

Referência de Métricas

Este documento descreve todas as métricas 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.

Os nomes, tipos e rótulos das métricas abaixo refletem as métricas que o OmniUPF expõe.

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ão e latência de estabelecimento
  3. Métricas de caminho lento e buffer do espaço do usuário - contadores de punt para buffer de downlink, jardim murado e indicações de erro de TEID desconhecido
  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ções de Erro
  6. Métricas URR - contadores de relat��rios de uso e temporizadores URR ativos
  7. Métricas de mapa eBPF - medidores de entrada de mapa do plano de dados
  8. Throughput do plano de dados - contadores _total por direção (N3/N6), controlados por expose_xdp_metrics (#57); também sob demanda via /api/v1/xdp_stats
  9. Métricas de recursos / roteamento - medidores de pool de TEID/FAR-ID e rotas de UE
  10. Métricas de Jardim Murado - contadores de interceptação de portal cativo, encaminhamento e spoofing de DNS

Métricas PFCP​

Contadores de protocolo 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 de estabelecimento da sessão (microsegundos). Baldes: 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000

Métricas de caminho lento e buffer do espaço do usuário​

O plano de dados eBPF envia pacotes para o caminho lento do espaço do usuário (porta UDP 22152, padrão) para três trabalhos distintos: buffer de downlink quando um UE está ocioso (mantido até que o UE seja chamado), redirecionamento de jardim murado, e respondendo uplink de TEID desconhecido G-PDUs com uma Indicação de Erro GTP-U. Apenas as métricas buffered/flushed/current abaixo descrevem o buffer propriamente dito; o jardim murado tem suas próprias métricas upf_walled_garden_* e TEID desconhecido é contado como upf_gtpu_error_indications_sent_total.

Nome da MétricaTipoRótulosDescrição
upf_userspace_punt_received_totalCounternoneTodos os pacotes enviados para o caminho lento do espaço do usuário (buffering + jardim murado + TEID desconhecido)
upf_gtpu_oversize_punted_totalCounternonePacotes GTP-U de downlink excessivos (tamanho encapsulado acima do MTU de saída) enviados para o espaço do usuário para que o kernel fragmenta o pacote externo. Crescimento sustentado significa que um assinante está enviando tráfego de tamanho total através do caminho lento; veja gtpu_oversize_punt_enabled
upf_buffer_packets_buffered_totalCounternonePacotes adicionados com sucesso ao buffer
upf_buffer_packets_flushed_totalCounternonePacotes descartados 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 descarte de buffer bem-sucedidas (por descarte de FAR)
upf_buffer_flush_packets_sent_totalCounternonePacotes enviados durante operações de descarte
upf_buffer_flush_errors_totalCounterreasonOperações de descarte de buffer falhadas

Valores de reason de upf_buffer_packets_dropped_total (de descartes de buffer-add e erros de listener de 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 descarte
  • 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
  • not_buffering_far - FAR não tem uma ação BUFF
  • error_indication_failed - não foi possível enviar a Indicação de Erro GTP-U para um uplink de TEID desconhecido

O uplink de TEID desconhecido não é um descarte de buffer: é respondido com uma Indicação de Erro GTP-U e contado por upf_gtpu_error_indications_sent_total (uma resposta correta do caminho lento, não perda de pacote).

Valores de reason de 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 tem uma ação FORW definida
  • connection_failed - falha ao abrir um socket UDP para descarte

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 em buffer. 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 do 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ções 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 recebida

Quando as 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 as 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ório 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 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 coleta.

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 alocados (upf_far_ids_allocated), uma vez que o far_map mantém uma entrada por id-FAR alocado. Os medidores PDR são agregados do estado da sessão ativa em cada coleta (custo é O(total de sessões)).

Throughput do plano de dados (N3/N6)​

Contadores de pacotes e bytes por direção para tráfego do plano do 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 eBPF.

Nome da MétricaTipoRótulosDescrição
upf_n3_rx_packets_total / upf_n3_tx_packets_totalCounternonePacotes N3 (GTP-U) dentro / fora do caminho de dados XDP
upf_n6_rx_packets_total / upf_n6_tx_packets_totalCounternonePacotes N6 (SGi) dentro / fora do caminho de dados XDP
upf_n3_rx_bytes_total / upf_n3_tx_bytes_totalCounternoneBytes N3 (GTP-U) dentro / fora
upf_n6_rx_bytes_total / upf_n6_tx_bytes_totalCounternoneBytes N6 (SGi) dentro / fora

Controlado por expose_xdp_metrics (issue #57). Ler upf_ext_stat no caminho de solicitação (por coleta Prometheus) provou acionar um TX-ring wedge genérico-XDP virtio_net. Duas mitig ações se aplicam: a leitura é feita fora do caminho de solicitação pelo Sampler em segundo plano (em um intervalo fixo, nunca em uma coleta), e está controlada por config :upf_ex, expose_xdp_metrics: true. Quando desativado, esses contadores não são declarados ou exportados.

Estes são _total Contadores cumulativos. O mapa upf_ext_stat subjacente é fixado, então sobrevive a um reinício do omniupf, mas é zerado em uma nova implantação eBPF .o; o coletor traduz seu valor absoluto em incrementos de contadores monótonos para que rate() permaneça correto em ambos. Não leia isso como medidores. Use rate().

JSON sob demanda: GET /api/v1/xdp_stats retorna os mesmos campos e só toca eBPF quando você o chama explicitamente. Campos: rx_n3 / tx_n3 / rx_n6 / tx_n6 (pacotes) e rx_n3_bytes / tx_n3_bytes / rx_n6_bytes / tx_n6_bytes.

Métricas de recursos / roteamento​

Nome da MétricaTipoRótulosDescrição
upf_routes_totalGaugenoneRotas de IP de UE atualmente rastreadas pelo gerenciador de rotas
upf_teid_allocatedGaugenoneTEIDs atualmente alocados do pool
upf_far_ids_allocatedGaugenoneIDs de 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 branca encaminhados, por IP de destino
upf_walled_garden_bytes_forwarded_totalCounterdst_ipBytes na lista branca 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 branca), por domínio

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

Usando Métricas 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:

# Ver 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ão e associação (upf_pfcp_sessions, upf_pfcp_associations)
  • Throughput N3/N6 por direção está disponível sob demanda via /api/v1/xdp_stats (removido da coleta, veja #57)
  • Pressão de 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