Skip to main content

OmniEPDG Metrics Reference

OmniEPDG exposes Prometheus metrics for monitoring authentication flows, session lifecycle, Diameter signaling, and system health. Metrics are served via HTTP for Prometheus scraping.

Table of Contents​

Metrics Endpoint​

OmniEPDG exposes metrics at:

http://<host>:9568/metrics

The endpoint returns metrics in Prometheus exposition format, compatible with Prometheus, Grafana, and other monitoring tools.

Configuration​

Configure the metrics endpoint in config/runtime.exs:

config :omniepdg,
  prometheus: %{
    port: 9568
  }
ParameterTypeDefaultEnv VarDescription
portInteger9568PROMETHEUS_PORTHTTP port for the /metrics endpoint

Metric Categories​

IKEv2 Session Metrics​

Metrics tracking IKEv2 tunnel establishment on the SWu interface.

Metric: epdg_ikev2_session_initiated_count Type: Counter Description: Total IKE_SA_INIT exchanges started. Increments when a UE initiates tunnel establishment.

Metric: epdg_ikev2_session_established_count Type: Counter Description: Total IKE SAs successfully established. Increments after successful EAP-AKA authentication and Child SA creation.

Metric: epdg_ikev2_session_failed_count Type: Counter Description: Total IKE SA establishment failures Labels:

  • reason - Failure reason (e.g., auth_failed, timeout, invalid_proposal)

EAP Authentication Metrics​

Metrics tracking EAP-AKA authentication flows per RFC 4187. OmniEPDG also supports EAP-AKA' per RFC 5448, with the authentication type automatically selected based on the UE's NAI identity prefix.

Metric: epdg_eap_identity_count Type: Counter Description: Total EAP-Identity requests received from UEs

Metric: epdg_eap_aka_challenge_count Type: Counter Description: Total EAP-AKA challenges sent to UEs

Metric: epdg_eap_aka_success_count Type: Counter Description: Total successful EAP-AKA authentications

Metric: epdg_eap_aka_failure_count Type: Counter Description: Total failed EAP-AKA authentications Labels:

  • reason - Failure reason (e.g., res_mismatch, invalid_identity, authentication_rejected)

Metric: epdg_eap_aka_sync_failure_count Type: Counter Description: Total EAP-AKA sequence number (SQN) synchronization failures. Indicates USIM/HSS sequence number mismatch requiring resynchronization.

Authentication Security Metrics​

Metrics for the authentication security layer. See the Security Guide for configuration details.

Metric: epdg_auth_verification_failed_count Type: Counter Description: Total AUTH payload verification failures. Indicates potential man-in-the-middle attacks or implementation bugs.

Metric: epdg_auth_rate_limited_count Type: Counter Description: Total authentication attempts blocked by rate limiting Labels:

  • type - Blocking reason: ip (per-IP threshold exceeded) or imsi (per-IMSI threshold exceeded)

Example queries:

# Rate limited attempts per minute
rate(epdg_auth_rate_limited_count[1m])

# Rate limited by type
sum by (type) (rate(epdg_auth_rate_limited_count[5m]))

Metric: epdg_auth_geoip_blocked_count Type: Counter Description: Total authentication attempts blocked by GeoIP country filtering Labels:

  • country - ISO 3166-1 alpha-2 country code (e.g., CN, RU), or UNKNOWN for IPs that could not be geolocated

Example queries:

# GeoIP blocks per minute
rate(epdg_auth_geoip_blocked_count[1m])

# Top blocked countries
topk(10, sum by (country) (epdg_auth_geoip_blocked_count))

Metric: epdg_esp_replay_detected_count Type: Counter Description: Total ESP packets rejected due to replay detection (per RFC 4303). Indicates potential replay attacks or network issues causing packet reordering.

Diameter SWx Metrics​

Metrics for the SWx interface between ePDG and HSS per 3GPP TS 29.273.

Metric: epdg_diameter_swx_mar_count Type: Counter Description: Total Multimedia-Auth-Requests sent to HSS for authentication vector retrieval Labels:

  • result - Request outcome: success or failure

Metric: epdg_diameter_swx_sar_count Type: Counter Description: Total Server-Assignment-Requests sent to HSS for registration/deregistration Labels:

  • result - Request outcome: success or failure

Metric: epdg_diameter_swx_mar_latency_ms Type: Histogram Description: MAR response time in milliseconds Buckets: 50, 100, 250, 500, 1000, 2500 ms

Metric: epdg_diameter_swx_sar_latency_ms Type: Histogram Description: SAR response time in milliseconds Buckets: 50, 100, 250, 500, 1000, 2500 ms

Metric: epdg_diameter_swx_pending_count Type: Gauge Description: Current number of pending SWx requests awaiting response. High values indicate HSS congestion or connectivity issues.

Diameter S6b Metrics​

Metrics for the S6b interface between AAA server and PGW per 3GPP TS 29.273. Only applicable in GTP mode.

Metric: epdg_diameter_s6b_aar_count Type: Counter Description: Total AA-Requests handled for session authorization Labels:

  • result - Request outcome: success or failure

Metric: epdg_diameter_s6b_str_count Type: Counter Description: Total Session-Termination-Requests processed

Metric: epdg_diameter_s6b_active_sessions_count Type: Gauge Description: Current number of active S6b sessions

Session Lifecycle Metrics​

Metrics tracking PDN session creation and termination.

Metric: epdg_session_created_count Type: Counter Description: Total sessions created Labels:

  • vpn_mode - VPN mode: simple or gtp

Metric: epdg_session_terminated_count Type: Counter Description: Total sessions terminated Labels:

  • reason - Termination reason: user_request, timeout, error, admin

Metric: epdg_sessions_active_count Type: Gauge Description: Current number of active sessions. Polled every 5 seconds.

Metric: epdg_sessions_by_state_count Type: Gauge Description: Sessions grouped by FSM state Labels:

  • state - Session state (e.g., init, eap_identity, eap_aka_challenge, authenticated, established)

Metric: epdg_auth_duration_ms Type: Histogram Description: Full authentication flow duration from IKE_SA_INIT to session established Buckets: 100, 250, 500, 1000, 2500, 5000, 10000 ms

Metric: epdg_session_duration_seconds Type: Histogram Description: Session lifetime from establishment to termination Buckets: 60, 300, 900, 1800, 3600, 7200, 14400 seconds (1 min to 4 hours)

ESP Data Plane Metrics​

Metrics for ESP packet processing per RFC 4303.

Metric: epdg_esp_packets_in_count Type: Counter Description: Total ESP packets successfully decrypted (UE → network direction)

Metric: epdg_esp_packets_out_count Type: Counter Description: Total ESP packets encrypted (network → UE direction)

Metric: epdg_esp_bytes_in_total Type: Gauge Description: Total bytes decrypted from ESP packets

Metric: epdg_esp_bytes_out_total Type: Gauge Description: Total bytes encrypted into ESP packets

IP Pool Metrics​

Metrics for IP address pool management in Simple VPN mode.

Metric: epdg_ip_allocated_count Type: Counter Description: Total IP addresses allocated Labels:

  • type - Address type: ipv4 or ipv6

Metric: epdg_ip_released_count Type: Counter Description: Total IP addresses released Labels:

  • type - Address type: ipv4 or ipv6

Metric: epdg_ip_pool_allocated_count Type: Gauge Description: Current number of allocated IP addresses

Metric: epdg_ip_pool_available_count Type: Gauge Description: Current number of available IP addresses in the pool

Metric: epdg_ip_pool_utilization_ratio Type: Gauge Description: IP pool utilization as a ratio from 0.0 to 1.0. Values approaching 1.0 indicate pool exhaustion risk.

VM Metrics​

Erlang/BEAM virtual machine metrics for system health monitoring.

Metric: vm_memory_total Type: Gauge Unit: Bytes Description: Total memory allocated by the VM

Metric: vm_memory_processes Type: Gauge Unit: Bytes Description: Memory used by Erlang processes

Metric: vm_memory_binary Type: Gauge Unit: Bytes Description: Memory used for binaries (including packet buffers)

Metric: vm_memory_ets Type: Gauge Unit: Bytes Description: Memory used by ETS tables (session state, registries)

Metric: vm_system_info_process_count Type: Gauge Description: Number of running Erlang processes

Metric: vm_system_info_port_count Type: Gauge Description: Number of open ports (sockets, file handles)

Metric: vm_statistics_run_queue Type: Gauge Description: Total length of scheduler run queues. High values indicate CPU saturation.

Prometheus Integration​

Scrape Configuration​

Add OmniEPDG to your Prometheus prometheus.yml:

scrape_configs:
  - job_name: 'omniepdg'
    scrape_interval: 15s
    static_configs:
      - targets: ['epdg-host:9568']
        labels:
          instance: 'epdg-01'
          environment: 'production'

Service Discovery​

For Kubernetes deployments, use service discovery:

scrape_configs:
  - job_name: 'omniepdg'
    kubernetes_sd_configs:
      - role: pod
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app]
        action: keep
        regex: omniepdg
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port]
        action: replace
        target_label: __address__
        regex: (.+)
        replacement: ${1}:9568

Example Queries​

Authentication Success Rate​

# Success rate over 5 minutes
sum(rate(epdg_eap_aka_success_count[5m]))
/
(sum(rate(epdg_eap_aka_success_count[5m])) + sum(rate(epdg_eap_aka_failure_count[5m])))

Session Establishment Rate​

# Sessions established per second
rate(epdg_ikev2_session_established_count[5m])

Authentication Latency (p95)​

histogram_quantile(0.95, sum(rate(epdg_auth_duration_ms_bucket[5m])) by (le))

HSS Latency (p99)​

histogram_quantile(0.99, sum(rate(epdg_diameter_swx_mar_latency_ms_bucket[5m])) by (le))

Active Sessions​

epdg_sessions_active_count

IP Pool Utilization​

epdg_ip_pool_utilization_ratio * 100

ESP Throughput​

# Bytes per second (inbound)
rate(epdg_esp_bytes_in_total[5m])

# Packets per second (both directions)
rate(epdg_esp_packets_in_count[5m]) + rate(epdg_esp_packets_out_count[5m])

Failure Breakdown by Reason​

# EAP failures by reason
sum by (reason) (rate(epdg_eap_aka_failure_count[5m]))

# Session terminations by reason
sum by (reason) (rate(epdg_session_terminated_count[5m]))

Alerting Rules​

Example Prometheus alerting rules for OmniEPDG:

groups:
  - name: omniepdg
    rules:
      # High authentication failure rate
      - alert: OmniEPDGHighAuthFailureRate
        expr: |
          sum(rate(epdg_eap_aka_failure_count[5m]))
          /
          (sum(rate(epdg_eap_aka_success_count[5m])) + sum(rate(epdg_eap_aka_failure_count[5m])))
          > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High EAP-AKA authentication failure rate"
          description: "Authentication failure rate is {{ $value | humanizePercentage }} over the last 5 minutes"

      # IP pool near exhaustion
      - alert: OmniEPDGIPPoolLow
        expr: epdg_ip_pool_utilization_ratio > 0.9
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "IP pool utilization above 90%"
          description: "IP pool is {{ $value | humanizePercentage }} utilized"

      # IP pool exhausted
      - alert: OmniEPDGIPPoolExhausted
        expr: epdg_ip_pool_available_count == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "IP pool exhausted"
          description: "No IP addresses available for new sessions"

      # HSS latency high
      - alert: OmniEPDGHSSLatencyHigh
        expr: |
          histogram_quantile(0.95, sum(rate(epdg_diameter_swx_mar_latency_ms_bucket[5m])) by (le))
          > 1000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High HSS (SWx) latency"
          description: "95th percentile MAR latency is {{ $value }}ms"

      # Pending SWx requests backlog
      - alert: OmniEPDGSWxBacklog
        expr: epdg_diameter_swx_pending_count > 100
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "SWx request backlog building"
          description: "{{ $value }} pending SWx requests"

      # VM memory high
      - alert: OmniEPDGMemoryHigh
        expr: vm_memory_total > 2147483648
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "OmniEPDG memory usage high"
          description: "VM memory usage is {{ $value | humanize1024 }}"

      # Scheduler overload
      - alert: OmniEPDGSchedulerOverload
        expr: vm_statistics_run_queue > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Erlang scheduler run queue high"
          description: "Run queue length is {{ $value }}, indicating CPU saturation"

      # No sessions (potential service issue)
      - alert: OmniEPDGNoSessions
        expr: epdg_sessions_active_count == 0 and epdg_ikev2_session_initiated_count > 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "No active sessions despite connection attempts"
          description: "Sessions are being initiated but none are active"

      # High rate limiting activity (potential attack)
      - alert: OmniEPDGHighRateLimiting
        expr: rate(epdg_auth_rate_limited_count[5m]) > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High rate of blocked authentication attempts"
          description: "{{ $value | printf \"%.1f\" }} auth attempts blocked per second"

      # GeoIP blocking spike (potential attack from specific region)
      - alert: OmniEPDGGeoIPBlockingSpike
        expr: |
          rate(epdg_auth_geoip_blocked_count[5m]) > 5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Elevated GeoIP blocking activity"
          description: "{{ $value | printf \"%.1f\" }} connections blocked per second by GeoIP"

      # ESP replay attacks detected
      - alert: OmniEPDGReplayAttack
        expr: rate(epdg_esp_replay_detected_count[5m]) > 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "ESP replay attacks detected"
          description: "{{ $value | printf \"%.1f\" }} replay attempts per second"

      # AUTH verification failures (potential MITM)
      - alert: OmniEPDGAuthVerificationFailures
        expr: rate(epdg_auth_verification_failed_count[5m]) > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "AUTH payload verification failures detected"
          description: "Potential man-in-the-middle attack or implementation bug"
Last updated on