Metrics Reference

This document describes all Prometheus metrics exposed by OmniUPF on the /metrics endpoint.

Metric Categories

1. PFCP message metrics - Control plane protocol message counters and latency per peer
2. XDP Action metrics - Dataplane packet verdicts (drop, pass, redirect, etc.)
3. Packet metrics - Received packet counters by protocol type
4. PFCP Session and Association metrics - Session and association counts per peer
5. URR metrics - Traffic volume counters aggregated per PFCP peer
6. Packet Buffering metrics - Packet buffer state, capacity, and throughput
7. Downlink Data Report (Notification) metrics - PFCP Session Report Request notifications and FAR index tracking
8. eBPF Map Capacity metrics - eBPF map utilization and capacity

Metrics Reference

PFCP message metrics

Metrics for tracking PFCP protocol messages between the UPF and control plane nodes.

Metric Name	Type	Labels	Description
upf_pfcp_rx	Counter	message_name, peer_address	Total number of received PFCP messages per message type and peer
upf_pfcp_tx	Counter	message_name, peer_address	Total number of transmitted PFCP messages per message type and peer
upf_pfcp_rx_errors	Counter	message_name, cause_code, peer_address	Total number of PFCP messages rejected with error cause per message type and peer
upf_pfcp_rx_latency	Summary	message_type, peer_address	PFCP message processing duration in microseconds (p50, p90, p99 quantiles) per message type and peer

Note: All counters track messages per PFCP peer for granular visibility into control plane node behavior.

XDP Action metrics

Packet counters by XDP program action/verdict. These metrics track the dataplane decision for each packet.

Metric Name	Type	Labels	Description
upf_xdp_aborted	Counter	none	Total number of packets aborted (XDP_ABORTED)
upf_xdp_drop	Counter	none	Total number of packets dropped (XDP_DROP)
upf_xdp_pass	Counter	none	Total number of packets passed to kernel (XDP_PASS)
upf_xdp_tx	Counter	none	Total number of packets transmitted (XDP_TX)
upf_xdp_redirect	Counter	none	Total number of packets redirected (XDP_REDIRECT)

Packet metrics

Counters for received packets by protocol type. All metrics use packet_type label.

Metric Name	Type	Labels	Description
upf_rx	Counter	packet_type	Total number of received packets by type
upf_route	Counter	packet_type	Total number of packets routed by lookup result

upf_rx packet_type values:

• arp - ARP packets
• icmp - ICMP packets
• icmp6 - ICMPv6 packets
• ip4 - IPv4 packets
• ip6 - IPv6 packets
• tcp - TCP packets
• udp - UDP packets
• other - Other packet types
• gtp-echo - GTP echo request/response
• gtp-pdu - GTP-U PDU (encapsulated user data)
• gtp-other - Other GTP message types
• gtp-unexp - Unexpected/malformed GTP packets

upf_route packet_type values:

• ip4-cache - IPv4 route cache hits
• ip4-ok - IPv4 FIB lookup success
• ip4-error-drop - IPv4 FIB lookup failed, packet dropped
• ip4-error-pass - IPv4 FIB lookup failed, packet passed to kernel
• ip6-cache - IPv6 route cache hits
• ip6-ok - IPv6 FIB lookup success
• ip6-error-drop - IPv6 FIB lookup failed, packet dropped
• ip6-error-pass - IPv6 FIB lookup failed, packet passed to kernel

PFCP Session and Association metrics

Metrics for tracking PFCP sessions and associations between the UPF and control plane nodes.

Metric Name	Type	Labels	Description
upf_pfcp_sessions	Gauge	none	Total number of currently established PFCP sessions (all peers)
upf_pfcp_associations	Gauge	none	Total number of currently established PFCP associations (all peers)
upf_pfcp_association_status	Gauge	node_id, address	PFCP association status per peer (1=up, 0=down)
upf_pfcp_sessions_per_node	Gauge	node_id, address	Number of active PFCP sessions per control plane node

URR (Usage Reporting Rule) metrics

Traffic volume metrics aggregated per PFCP peer. Each peer's volume represents the sum of all URR counters across all sessions from that control plane node.

Metric Name	Type	Labels	Description
upf_urr_uplink_volume_bytes	Gauge	peer_address	Total uplink traffic volume in bytes for all sessions from this peer
upf_urr_downlink_volume_bytes	Gauge	peer_address	Total downlink traffic volume in bytes for all sessions from this peer
upf_urr_total_volume_bytes	Gauge	peer_address	Total traffic volume in bytes (uplink + downlink) for all sessions from this peer

Note: Volumes are aggregated per PFCP peer to avoid high cardinality issues. Individual URR statistics are available via the REST API at /api/v1/urr_map.

Packet Buffering metrics

Metrics for tracking packet buffer state and performance. The UPF can buffer downlink packets when a UE is in idle state, holding them until the UE is paged and transitions to connected state.

Metric Name	Type	Labels	Description
upf_buffer_packets_total	Counter	none	Total number of packets added to buffer (all time)
upf_buffer_packets_dropped	Counter	reason	Total number of packets dropped from buffer
upf_buffer_packets_flushed	Counter	none	Total number of packets flushed from buffer
upf_buffer_packets_current	Gauge	none	Current number of packets in buffer
upf_buffer_bytes_total	Counter	none	Total bytes added to buffer (all time)
upf_buffer_bytes_current	Gauge	none	Current bytes in buffer
upf_buffer_fars_active	Gauge	none	Current number of FARs with buffered packets
upf_buffer_listener_packets_received_total	Counter	none	Total packets received by buffer listener from eBPF dataplane
upf_buffer_listener_packets_buffered_total	Counter	none	Total packets successfully buffered by listener
upf_buffer_listener_errors_total	Counter	type	Errors in buffer listener packet processing
upf_buffer_listener_error_indications_sent_total	Counter	remote_peer	Total GTP-U Error Indication messages sent for unknown TEIDs by remote peer
upf_buffer_flush_success_total	Counter	none	Total successful buffer flush operations
upf_buffer_flush_errors_total	Counter	reason	Total failed buffer flush operations
upf_buffer_flush_packets_sent_total	Counter	none	Total packets sent during flush operations

upf_buffer_packets_dropped reason values:

• expired - Packets dropped due to TTL expiration
• global_limit - Dropped due to total buffer limit reached
• far_limit - Dropped due to per-FAR buffer limit reached
• cleared - Packets manually cleared from buffer

upf_buffer_listener_errors_total type values:

• read_error - Error reading from buffer socket
• too_small - Packet too small for GTP header
• invalid_gtp_type - Non-G-PDU GTP message type
• unknown_teid - No PDR/FAR found for TEID
• not_buffering_far - FAR does not have BUFF action
• truncated_ext - Truncated GTP extension headers
• no_payload - GTP packet has no payload
• buffer_full - Buffer capacity exceeded

upf_buffer_flush_errors_total reason values:

• far_lookup_failed - Failed to lookup FAR info from eBPF map
• no_forw_action - FAR does not have FORW action set
• connection_failed - Failed to create UDP connection for flushing

Downlink Data Report (Notification) metrics

Metrics for PFCP Session Report Request notifications sent to control plane when packets are buffered. These notifications trigger the control plane to page the UE.

Metric Name	Type	Labels	Description
upf_dldr_sent_total	Counter	none	Total number of Downlink Data Report (DLDR) notifications sent to SMF
upf_dldr_send_errors	Counter	none	Total number of errors sending Downlink Data Report notifications
upf_dldr_active_notifications	Gauge	none	Current number of FARs with active DLDR notifications (not yet cleared)
upf_far_index_size	Gauge	none	Current number of FARs registered in FarIndex for DLDR notifications
upf_far_index_registrations_total	Counter	none	Total number of FAR registrations in FarIndex
upf_far_index_unregistrations_total	Counter	none	Total number of FAR unregistrations from FarIndex
upf_buffer_notify_to_flush_duration_seconds	Histogram	pfcp_peer	Time between sending DLDR notification and flushing buffered packets

upf_buffer_notify_to_flush_duration_seconds:

• Histogram buckets: 0.01, 0.05, 0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0 seconds
• Label pfcp_peer: SMF/PGW-C address (e.g., 10.100.50.241)
• Measures the latency between UPF sending notification to SMF and SMF responding with session modification to flush packets
• Useful for monitoring control plane responsiveness during idle-to-connected transitions

GTP-U Error Indication metrics

Metrics for tracking GTP-U Error Indication messages sent and received. Error Indications are sent when a peer receives packets for unknown TEIDs, indicating tunnel state mismatches (often due to peer restarts).

Metric Name	Type	Labels	Description
upf_buffer_listener_error_indications_sent_total	Counter	node_id, peer_address	Total GTP-U Error Indications sent for unknown incoming TEIDs
upf_buffer_listener_error_indications_received_total	Counter	node_id, peer_address	Total GTP-U Error Indications received from peers
upf_buffer_listener_error_indication_sessions_deleted_total	Counter	node_id, peer_address	Total sessions deleted due to received Error Indications

Label Definitions:

• node_id: PFCP Node ID from the association (e.g., "pgw-u-1", "smf-1"). Set to "unknown" if no PFCP association exists for that peer.
• peer_address: IP address of the remote peer (e.g., "192.168.50.10")

When Error Indications Are Sent:

• UPF receives GTP-U packet for a TEID that doesn't exist (e.g., after UPF restart, session already deleted)
• Sender (eNodeB, gNodeB, upstream UPF) is forwarding to stale/deleted tunnel
• UPF sends Error Indication to inform sender to stop sending

When Error Indications Are Received:

• UPF forwards GTP-U packet to downstream peer (PGW-U, SGW-U, UPF) for unknown TEID
• Remote peer doesn't recognize the destination TEID (e.g., peer restarted and lost tunnel state)
• UPF automatically deletes affected sessions to stop forwarding to dead tunnels

Use Cases:

• Detect peer restarts (high Error Indication rate indicates state loss)
• Identify configuration mismatches (TEID allocation issues)
• Monitor tunnel synchronization health between network elements
• Alert on unexpected session deletions

Example PromQL Queries:

# Rate of Error Indications received per peer (per second)
rate(upf_buffer_listener_error_indications_received_total[5m])

# Total sessions deleted due to Error Indications from specific peer
upf_buffer_listener_error_indication_sessions_deleted_total{peer_address="192.168.50.10"}

# Peers sending unknown TEIDs to this UPF
sum by (node_id, peer_address) (upf_buffer_listener_error_indications_sent_total)

eBPF Map Capacity metrics

Metrics for tracking eBPF map utilization. These metrics help monitor resource usage and detect potential capacity issues.

Metric Name	Type	Labels	Description
upf_ebpf_map_capacity	Gauge	map_name	Maximum capacity of eBPF map
upf_ebpf_map_used	Gauge	map_name	Current number of entries in eBPF map

Common map_name values:

• pdr_map - Packet Detection Rule map
• far_map - Forwarding Action Rule map
• qer_map - QoS Enforcement Rule map
• session_map - Session lookup map
• teid_map - TEID to session mapping
• ue_ip_map - UE IP address to session mapping

Using Prometheus Metrics

Accessing Metrics

Metrics are exposed on the /metrics endpoint at the address specified by metrics_address in the configuration file (default :9090):

# View raw metrics
curl http://localhost:9090/metrics

# Example output
upf_pfcp_sessions 42
upf_pfcp_associations 2
upf_urr_total_volume_bytes{peer_address="10.100.50.241"} 1048576000

Prometheus Configuration

Add the OmniUPF target to your prometheus.yml:

scrape_configs:
  - job_name: 'omniupf'
    static_configs:
      - targets: ['localhost:9090']

Grafana Dashboards

Import metrics into Grafana for visualization:

• Session counts and trends
• Traffic volume per PFCP peer
• Packet processing rates
• Buffer utilization
• eBPF map capacity monitoring

Related Documentation

• Monitoring Guide - Statistics monitoring, capacity planning, and alerting
• Configuration Guide - Configure metrics_address and other UPF options
• Web UI Guide - View metrics in the Statistics page
• Architecture Guide - eBPF datapath and performance optimization
• Rules Management Guide - Understanding PDR, FAR, QER, URR metrics
• Troubleshooting Guide - Using metrics for diagnostics