Guía de Métricas y Monitoreo de Prometheus

Resumen

OmniTAS exporta métricas operativas completas en formato Prometheus para monitoreo, alertas y observabilidad. Esta guía cubre todas las métricas disponibles, su uso, solución de problemas y mejores prácticas de monitoreo.

Endpoint de Métricas

Todas las métricas se exponen en: http://<tas-ip>:8080/metrics

Importante: Configuración de Unidad de Tiempo de Métricas

Todas las métricas de duración en este sistema utilizan duration_unit: false en sus declaraciones de Histograma. Esto es crítico porque:

La biblioteca Elixir de Prometheus detecta automáticamente los nombres de las métricas que terminan en _milliseconds
Por defecto, convierte automáticamente las unidades de tiempo nativas de Erlang a milisegundos
Nuestro código ya convierte el tiempo a milisegundos usando System.convert_time_unit/3
Sin duration_unit: false, la biblioteca convertiría milisegundos a nanosegundos (dividiendo por ~1,000,000)

Ejemplo:

# Configuración correcta
Histogram.declare(
  name: :http_dialplan_request_duration_milliseconds,
  help: "Duración de las solicitudes HTTP del plan de marcado en milisegundos",
  labels: [:call_type],
  buckets: [100, 250, 500, 750, 1000, 1500, 2000, 3000, 5000],
  duration_unit: false  # REQUERIDO para prevenir doble conversión
)

# Midiendo el tiempo correctamente
start_time = System.monotonic_time()
# ... hacer trabajo ...
end_time = System.monotonic_time()
duration_ms = System.convert_time_unit(end_time - start_time, :native, :millisecond)
Histogram.observe([name: :http_dialplan_request_duration_milliseconds], duration_ms)

Referencia Completa de Métricas

Métricas de Diámetro

`diameter_response_duration_milliseconds`

Tipo: Histograma
Etiquetas: application (ro, sh), command (ccr, cca, etc), result (success, error, timeout)
Buckets: 10, 50, 100, 250, 500, 1000, 2500, 5000, 10000 ms
Descripción: Duración de las solicitudes de Diámetro en milisegundos

Uso:

# Tiempo promedio de respuesta de Diámetro
rate(diameter_response_duration_milliseconds_sum[5m]) /
rate(diameter_response_duration_milliseconds_count[5m])

# Latencia P95 de Diámetro
histogram_quantile(0.95, rate(diameter_response_duration_milliseconds_bucket[5m]))

Alerta Cuando:

P95 > 1000ms - Respuestas de Diámetro lentas

`diameter_requests_total`

Tipo: Contador
Etiquetas: application (ro, sh), command (ccr, udr, etc)
Descripción: Número total de solicitudes de Diámetro enviadas

Uso:

# Tasa de solicitudes
rate(diameter_requests_total[5m])

`diameter_responses_total`

Tipo: Contador
Etiquetas: application (ro, sh), command (ccr, udr, etc), result_code (2001, 3002, 5xxx, etc)
Descripción: Número total de respuestas de Diámetro recibidas

Uso:

# Tasa de éxito
rate(diameter_responses_total{result_code="2001"}[5m]) /
rate(diameter_responses_total[5m]) * 100

`diameter_peer_state`

Tipo: Gauge
Etiquetas: peer_host, peer_realm, application (ro, sh)
Descripción: Estado de los pares de Diámetro (1=arriba, 0=abajo)
Intervalo de actualización: Cada 10 segundos

Uso:

# Comprobar pares caídos
diameter_peer_state == 0

Alerta Cuando:

Cualquier par caído por > 1 minuto

Métricas de Generación de Plan de Marcado

1. Métricas de Solicitudes HTTP

`http_dialplan_request_duration_milliseconds`

Tipo: Histograma
Etiquetas: call_type (mt, mo, emergency, unknown)
Descripción: Duración de la solicitud HTTP de extremo a extremo desde que se recibe la solicitud HTTP del plan de marcado hasta que se envía la respuesta. Esto incluye todo el procesamiento: análisis de parámetros, autorización, búsquedas de Diámetro (Sh/Ro), búsquedas de HLR (SS7 MAP) y generación de XML.

Uso:

# Tiempo promedio de solicitud HTTP de extremo a extremo
rate(http_dialplan_request_duration_milliseconds_sum[5m]) /
rate(http_dialplan_request_duration_milliseconds_count[5m])

# P95 por tipo de llamada
histogram_quantile(0.95,
  rate(http_dialplan_request_duration_milliseconds_bucket[5m])
) by (call_type)

# Comparar rendimiento de MT vs MO
histogram_quantile(0.95,
  rate(http_dialplan_request_duration_milliseconds_bucket{call_type="mt"}[5m])
)
vs
histogram_quantile(0.95,
  rate(http_dialplan_request_duration_milliseconds_bucket{call_type="mo"}[5m])
)

Alerta Cuando:

P95 > 2000ms - Tiempos de respuesta HTTP lentos
P95 > 3000ms - Problema crítico de rendimiento
P99 > 5000ms - Degradación severa del rendimiento
Cualquier solicitud mostrando call_type="unknown" - Fallo en la detección del tipo de llamada

Perspectivas:

Esta es la métrica más importante para entender la latencia desde la perspectiva del usuario
Valores típicos: P50: 100-500ms, P95: 500-2000ms, P99: 1000-3000ms
Incluye todos los tiempos de los componentes (Sh + HLR + OCS + procesamiento)
Si esto es lento, profundizar en las métricas de los componentes (subscriber_data, hlr_data, ocs_authorization)
Rango esperado: 100ms (llamadas locales rápidas) a 5000ms (lentas con reintentos/tiempos de espera)

Notas Importantes:

Reemplaza la métrica anterior dialplan_generation_duration_milliseconds que solo medía la generación de XML
Refleja con precisión lo que experimenta FreeSWITCH/SBC
Utilice esto para monitoreo de SLA y planificación de capacidad

2. Métricas de Datos de Suscriptores

`subscriber_data_duration_milliseconds`

Tipo: Histograma
Etiquetas: result (success, error)
Descripción: Tiempo tomado para recuperar datos de suscriptores de la interfaz Sh (HSS)

Uso:

# Tiempo promedio de búsqueda en Sh
rate(subscriber_data_duration_milliseconds_sum[5m]) /
rate(subscriber_data_duration_milliseconds_count[5m])

# Tiempo de búsqueda en Sh percentil 95
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m])
)

Alerta Cuando:

P95 > 100ms - Respuestas lentas de HSS
P95 > 500ms - Problema crítico de rendimiento de HSS

`subscriber_data_lookups_total`

Tipo: Contador
Etiquetas: result (success, error)
Descripción: Número total de búsquedas de datos de suscriptores

Uso:

# Tasa de búsqueda en Sh
rate(subscriber_data_lookups_total[5m])

# Tasa de error en Sh
rate(subscriber_data_lookups_total{result="error"}[5m])

# Porcentaje de tasa de éxito en Sh
(rate(subscriber_data_lookups_total{result="success"}[5m]) /
 rate(subscriber_data_lookups_total[5m])) * 100

Alerta Cuando:

Tasa de error > 5% - Problemas de conectividad con HSS
Tasa de error > 20% - Fallo crítico de HSS

2. Métricas de Datos de HLR

`hlr_data_duration_milliseconds`

Tipo: Histograma
Etiquetas: result (success, error)
Descripción: Tiempo tomado para recuperar datos de HLR a través de SS7 MAP

Uso:

# Tiempo promedio de búsqueda en HLR
rate(hlr_data_duration_milliseconds_sum[5m]) /
rate(hlr_data_duration_milliseconds_count[5m])

# Tiempo de búsqueda en HLR percentil 95
histogram_quantile(0.95,
  rate(hlr_data_duration_milliseconds_bucket[5m])
)

Alerta Cuando:

P95 > 500ms - Respuestas lentas de SS7 MAP
P95 > 2000ms - Problema crítico de SS7 MAP

`hlr_lookups_total`

Tipo: Contador
Etiquetas: result_type (msrn, forwarding, error, unknown)
Descripción: Total de búsquedas de HLR por tipo de resultado

Uso:

# Tasa de búsqueda de HLR por tipo
rate(hlr_lookups_total[5m])

# Tasa de descubrimiento de MSRN (suscriptores en roaming)
rate(hlr_lookups_total{result_type="msrn"}[5m])

# Tasa de descubrimiento de reenvío de llamadas
rate(hlr_lookups_total{result_type="forwarding"}[5m])

# Tasa de error de HLR
rate(hlr_lookups_total{result_type="error"}[5m])

Alerta Cuando:

Tasa de error > 10% - Problemas de SS7 MAP
Caída repentina en la tasa de MSRN - Posible problema de roaming

Perspectivas:

Alta tasa de MSRN indica muchos suscriptores en roaming
Alta tasa de reenvío indica muchas llamadas reenviadas
Comparar con el volumen de llamadas para el porcentaje de roaming

3. Métricas de Autorización de OCS

`ocs_authorization_duration_milliseconds`

Tipo: Histograma
Etiquetas: result (success, error)
Descripción: Tiempo tomado para la autorización de OCS

Uso:

# Tiempo promedio de autorización de OCS
rate(ocs_authorization_duration_milliseconds_sum[5m]) /
rate(ocs_authorization_duration_milliseconds_count[5m])

# Tiempo de autorización de OCS percentil 95
histogram_quantile(0.95,
  rate(ocs_authorization_duration_milliseconds_bucket[5m])
)

Alerta Cuando:

P95 > 1000ms - Respuestas lentas de OCS
P95 > 5000ms - Problema crítico de rendimiento de OCS

`ocs_authorization_attempts_total`

Tipo: Contador
Etiquetas: result (success, error), skipped (yes, no)
Descripción: Total de intentos de autorización de OCS

Uso:

# Tasa de autorización de OCS
rate(ocs_authorization_attempts_total{skipped="no"}[5m])

# Tasa de error de OCS
rate(ocs_authorization_attempts_total{result="error",skipped="no"}[5m])

# Tasa de omisiones de OCS (emergencia, buzón de voz, etc.)
rate(ocs_authorization_attempts_total{skipped="yes"}[5m])

# Porcentaje de tasa de éxito de OCS
(rate(ocs_authorization_attempts_total{result="success",skipped="no"}[5m]) /
 rate(ocs_authorization_attempts_total{skipped="no"}[5m])) * 100

Alerta Cuando:

Tasa de error > 5% - Problemas de conectividad de OCS
Tasa de éxito < 95% - OCS rechazando demasiadas llamadas

Perspectivas:

Alta tasa de omisiones indica muchas llamadas de emergencia/gratuitas
Picos en la tasa de error indican fallos en OCS
Comparar la tasa de éxito con las expectativas comerciales

4. Métricas de Procesamiento de Llamadas

`call_param_errors_total`

Tipo: Contador
Etiquetas: error_type (parse_failed, missing_required_params)
Descripción: Errores de análisis de parámetros de llamada

Uso:

# Tasa de errores de parámetros
rate(call_param_errors_total[5m])

# Errores por tipo
rate(call_param_errors_total[5m]) by (error_type)

Alerta Cuando:

Cualquier error > 0 - Indica solicitudes de parámetros de llamada mal formadas
Errores > 1% del volumen de llamadas - Problema crítico

`authorization_decisions_total`

Tipo: Contador
Etiquetas: disposition (mt, mo, emergency, unauthorized), result (success, error)
Descripción: Decisiones de autorización por tipo de llamada

Uso:

# Tasa de autorización por disposición
rate(authorization_decisions_total[5m]) by (disposition)

# Tasa de llamadas MT
rate(authorization_decisions_total{disposition="mt"}[5m])

# Tasa de llamadas MO
rate(authorization_decisions_total{disposition="mo"}[5m])

# Tasa de llamadas de emergencia
rate(authorization_decisions_total{disposition="emergency"}[5m])

# Tasa de llamadas no autorizadas
rate(authorization_decisions_total{disposition="unauthorized"}[5m])

Alerta Cuando:

Tasa no autorizada > 1% - Posible ataque o mala configuración
Aumento repentino en llamadas de emergencia - Posible evento de emergencia
Cambio inesperado en la relación MT/MO - Posible problema

Perspectivas:

La relación MT/MO indica patrones de tráfico
La tasa de llamadas de emergencia indica uso del servicio
La tasa no autorizada indica postura de seguridad

`freeswitch_variable_set_duration_milliseconds`

Tipo: Histograma
Etiquetas: batch_size (1, 5, 10, 25, 50, 100)
Descripción: Tiempo para establecer Variables de Plan de Marcado

Uso:

# Tiempo promedio de establecimiento de variable
rate(freeswitch_variable_set_duration_milliseconds_sum[5m]) /
rate(freeswitch_variable_set_duration_milliseconds_count[5m])

# Tiempo de establecimiento de variable por tamaño de lote
histogram_quantile(0.95,
  rate(freeswitch_variable_set_duration_milliseconds_bucket[5m])
) by (batch_size)

Alerta Cuando:

P95 > 100ms - Rendimiento lento de establecimiento de variables
Tendencia creciente - Posible problema de rendimiento del sistema

5. Métricas de Procesamiento de Módulos

`dialplan_module_duration_milliseconds`

Tipo: Histograma
Etiquetas: module (MT, MO, Emergency, CallParams, etc.), call_type
Descripción: Tiempo de procesamiento para cada módulo de plan de marcado

Uso:

# Tiempo de procesamiento por módulo
histogram_quantile(0.95,
  rate(dialplan_module_duration_milliseconds_bucket[5m])
) by (module)

# Tiempo de procesamiento del módulo MT
histogram_quantile(0.95,
  rate(dialplan_module_duration_milliseconds_bucket{module="MT"}[5m])
)

Alerta Cuando:

Cualquier módulo P95 > 500ms - Problema de rendimiento
Tendencia creciente en cualquier módulo - Fuga o problema potencial

Perspectivas:

Identificar cuál módulo es el más lento
Optimizar primero los módulos más lentos
Comparar los tiempos de los módulos entre tipos de llamada

6. Métricas de Volumen de Llamadas

`call_attempts_total`

Tipo: Contador
Etiquetas: call_type (mt, mo, emergency, unauthorized), result (success, rejected)
Descripción: Total de intentos de llamada

Uso:

# Tasa de intentos de llamada
rate(call_attempts_total[5m])

# Tasa de éxito por tipo de llamada
(rate(call_attempts_total{result="success"}[5m]) /
 rate(call_attempts_total[5m])) * 100 by (call_type)

# Tasa de llamadas rechazadas
rate(call_attempts_total{result="rejected"}[5m])

Alerta Cuando:

Tasa de rechazados > 5% - Posible problema
Caída repentina en el volumen de llamadas - Interrupción del servicio
Aumento repentino en el volumen de llamadas - Posible ataque

`active_calls`

Tipo: Gauge
Etiquetas: call_type (mt, mo, emergency)
Descripción: Llamadas actualmente activas

Uso:

# Llamadas activas actuales
active_calls

# Llamadas activas por tipo
active_calls by (call_type)

# Llamadas activas máximas (última hora)
max_over_time(active_calls[1h])

Alerta Cuando:

Llamadas activas > capacidad - Sobrecarga
Llamadas activas = 0 durante un tiempo prolongado - Servicio caído

7. Métricas de Simulación

`call_simulations_total`

Tipo: Contador
Etiquetas: call_type (mt, mo, emergency, unauthorized), source (web, api)
Descripción: Simulaciones de llamadas realizadas

Uso:

# Tasa de simulación
rate(call_simulations_total[5m])

# Simulaciones por tipo
rate(call_simulations_total[5m]) by (call_type)

Perspectivas:

Rastrear el uso de herramientas de diagnóstico
Identificar usuarios frecuentes
Correlacionar con actividad de solución de problemas

8. Métricas de SS7 MAP

`ss7_map_http_duration_milliseconds`

Tipo: Histograma
Etiquetas: operation (sri, prn), result (success, error, timeout)
Buckets: 10, 50, 100, 250, 500, 1000, 2500, 5000, 10000 ms
Descripción: Duración de las solicitudes HTTP de SS7 MAP en milisegundos

Uso:

# Tasa de error de SS7 MAP
rate(ss7_map_operations_total{result="error"}[5m]) /
rate(ss7_map_operations_total[5m]) * 100

Alerta Cuando:

P95 > 500ms - Respuestas lentas de SS7 MAP
Tasa de error > 50% - Problema crítico de SS7 MAP

`ss7_map_operations_total`

Tipo: Contador
Etiquetas: operation (sri, prn), result (success, error)
Descripción: Número total de operaciones de SS7 MAP

9. Métricas de Carga en Línea

`online_charging_events_total`

Tipo: Contador
Etiquetas: event_type (authorize, answer, reauth, hangup), result (success, nocredit, error, timeout)
Descripción: Número total de eventos de carga en línea

Uso:

# Fallos de crédito de OCS
rate(online_charging_events_total{result="nocredit"}[5m])

Alerta Cuando:

Alta tasa de fallos de crédito

10. Métricas de Estado del Sistema

`tracked_registrations`

Tipo: Gauge
Descripción: Número de registros SIP actualmente activos (desde la base de datos de registros de FreeSWITCH Sofia)
Intervalo de actualización: Cada 10 segundos

Notas:

Se decrementa automáticamente cuando los registros expiran (FreeSWITCH gestiona la expiración)

`tracked_call_sessions`

Tipo: Gauge
Descripción: Número de sesiones de llamada actualmente rastreadas en ETS
Intervalo de actualización: Cada 10 segundos

11. Métricas de Solicitudes HTTP

`http_requests_total`

Tipo: Contador
Etiquetas: endpoint (dialplan, call_event, directory, voicemail, sms_ccr, metrics), status_code (200, 400, 500, etc)
Descripción: Número total de solicitudes HTTP por endpoint

Uso:

# Tasa de error HTTP
rate(http_requests_total{status_code=~"5.."}[5m]) /
rate(http_requests_total[5m]) * 100

Alerta Cuando:

Tasa de error HTTP 5xx > 10%

12. Métricas de Rechazo de Llamadas

`call_rejections_total`

Tipo: Contador
Etiquetas: call_type (mo, mt, emergency, unknown), reason (nocredit, unauthorized, parse_failed, missing_params, hlr_error, etc)
Descripción: Número total de rechazos de llamadas por razón

Uso:

# Tasa de rechazo de llamadas por razón
sum by (reason) (rate(call_rejections_total[5m]))

Alerta Cuando:

Tasa de rechazo > 1/segundo - Se necesita investigación

13. Métricas de Conexión de Socket de Eventos

`event_socket_connected`

Tipo: Gauge
Etiquetas: connection_type (main, log_listener)
Descripción: Estado de conexión del Socket de Eventos (1=conectado, 0=desconectado)
Intervalo de actualización: En tiempo real en cambios de estado de conexión

Uso:

# Estado de conexión del Socket de Eventos
event_socket_connected

Alerta Cuando:

Conexión caída por > 30 segundos

`event_socket_reconnections_total`

Tipo: Contador
Etiquetas: connection_type (main, log_listener), result (attempting, success, failed)
Descripción: Número total de intentos de reconexión del Socket de Eventos

Integración del Panel de Grafana

Las métricas se pueden visualizar en Grafana utilizando la fuente de datos de Prometheus. Paneles recomendados:

Panel 1: Volumen de Llamadas

Gauge de llamadas activas
Tasa de intentos de llamadas por tipo (MO/MT/Emergencia)
Tasa de rechazo de llamadas

Panel 2: Rendimiento de Diámetro

Mapa de calor del tiempo de respuesta
Tasas de solicitud/respuesta
Tabla de estado de pares
Tasa de error por código de resultado

Panel 3: Salud de Carga en Línea

Tasa de éxito de autorización de crédito
Tasa de eventos "Sin crédito"
Tasa de tiempo de espera de OCS

Panel 4: Rendimiento del Sistema

Latencia de generación de plan de marcado (P50/P95/P99)
Tiempos de respuesta de SS7 MAP
Disponibilidad general del sistema

Diseño Recomendado del Panel de Grafana

Fila 1: Volumen de Llamadas

Tasa de intentos de llamadas (por tipo)
Gauge de llamadas activas
Porcentaje de tasa de éxito

Fila 2: Rendimiento

Tiempo de solicitud HTTP del plan de marcado P95 (por tipo de llamada) - MÉTRICA PRINCIPAL
Tiempo de búsqueda en Sh P95
Tiempo de búsqueda en HLR P95
Tiempo de autorización de OCS P95
Tiempo de procesamiento del módulo de plan de marcado P95 (por módulo)

Fila 3: Tasas de Éxito

Tasa de éxito de búsqueda en Sh
Tasa de éxito de búsqueda en HLR
Tasa de éxito de autorización de OCS
Tasa de éxito de intentos de llamadas

Fila 4: Rendimiento de Módulos

Tiempo de procesamiento P95 por módulo
Conteos de llamadas por módulo

Fila 5: Errores

Errores de parámetros
Intentos no autorizados
Errores de Sh
Errores de HLR
Errores de OCS

Alertas Críticas

Prioridad 1 (Página inmediatamente):

# Plan de marcado completamente caído
rate(call_attempts_total[5m]) == 0

# HSS completamente caído
rate(subscriber_data_lookups_total{result="error"}[5m]) /
rate(subscriber_data_lookups_total[5m]) > 0.9

# OCS completamente caído
rate(ocs_authorization_attempts_total{result="error"}[5m]) /
rate(ocs_authorization_attempts_total[5m]) > 0.9

Prioridad 2 (Alerta):

# Generación de plan de marcado lenta
histogram_quantile(0.95,
  rate(dialplan_generation_duration_milliseconds_bucket[5m])
) > 1000

# Alta tasa de error de HSS
rate(subscriber_data_lookups_total{result="error"}[5m]) /
rate(subscriber_data_lookups_total[5m]) > 0.2

# Alta tasa de error de OCS
rate(ocs_authorization_attempts_total{result="error"}[5m]) /
rate(ocs_authorization_attempts_total[5m]) > 0.1

Prioridad 3 (Advertencia):

# Latencia elevada de HSS
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m])
) > 100

# Latencia elevada de OCS
histogram_quantile(0.95,
  rate(ocs_authorization_duration_milliseconds_bucket[5m])
) > 1000

# Tasa de error moderada
rate(call_attempts_total{result="rejected"}[5m]) /
rate(call_attempts_total[5m]) > 0.05

Ejemplos de Alertas

Par de Diámetro Caído

alert: DiameterPeerDown
expr: diameter_peer_state == 0
for: 1m
annotations:
  summary: "El par de Diámetro {{ $labels.peer_host }} está caído"

Alta Latencia de Diámetro

alert: HighDiameterLatency
expr: histogram_quantile(0.95, rate(diameter_response_duration_milliseconds_bucket[5m])) > 1000
for: 5m
annotations:
  summary: "Latencia P95 de Diámetro por encima de 1s"

Fallos de Crédito de OCS

alert: HighOCSCreditFailures
expr: rate(online_charging_events_total{result="nocredit"}[5m]) > 0.1
for: 2m
annotations:
  summary: "Alta tasa de fallos de crédito de OCS"

Errores de Gateway de SS7 MAP

alert: SS7MapErrors
expr: rate(ss7_map_operations_total{result="error"}[5m]) / rate(ss7_map_operations_total[5m]) > 0.5
for: 3m
annotations:
  summary: "Tasa de error de SS7 MAP por encima del 50%"

Socket de Eventos Desconectado

alert: EventSocketDown
expr: event_socket_connected == 0
for: 30s
annotations:
  summary: "Socket de Eventos {{ $labels.connection_type }} desconectado"

Alta Tasa de Rechazo de Llamadas

alert: HighCallRejectionRate
expr: rate(call_rejections_total[5m]) > 1
for: 2m
annotations:
  summary: "Alta tasa de rechazo de llamadas: {{ $value }} rechazos/segundo"

Alta Tasa de Error HTTP

alert: HighHTTPErrorRate
expr: rate(http_requests_total{status_code=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.1
for: 3m
annotations:
  summary: "Tasa de error HTTP 5xx por encima del 10%"

Solución de Problemas con Métricas

Problema: Métricas que muestran valores irreales (nanosegundos en lugar de milisegundos)

Síntomas:

Los valores de _sum del histograma son extremadamente pequeños (por ejemplo, 0.000315 en lugar de 315)
Todas las solicitudes mostrando en el bucket más bajo (< 5ms) cuando deberían ser más lentas
Los valores parecen ser 1,000,000x más pequeños de lo esperado

Causa Raíz: La biblioteca Elixir de Prometheus convierte automáticamente las unidades de tiempo cuando los nombres de las métricas terminan en _milliseconds, _seconds, etc. Si duration_unit: false no está configurado, la biblioteca convertirá sus milisegundos ya convertidos en nanosegundos.

Investigación:

Verifique la declaración de la métrica en lib/metrics.ex

Verifique que duration_unit: false esté presente:

Histogram.declare(
  name: :some_duration_milliseconds,
  help: "...",
  buckets: [...],
  duration_unit: false  # ¡Debe estar presente!
)

Verifique que el código de medición utilice la conversión de tiempo adecuada:

start = System.monotonic_time()
# ... trabajo ...
duration_ms = System.convert_time_unit(
  System.monotonic_time() - start,
  :native,
  :millisecond
)
Histogram.observe([name: :some_duration_milliseconds], duration_ms)

Resolución:

Agregue duration_unit: false a la declaración del histograma
Reinicie la aplicación (requerido para que las declaraciones de métricas se recarguen)
Verifique que las métricas muestren valores realistas después de la corrección

Ejemplo de Corrección:

# Antes (MALO - mostrará nanosegundos)
Histogram.declare(
  name: :http_dialplan_request_duration_milliseconds,
  buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500]
)

# Después (CORRECTO - mostrará milisegundos)
Histogram.declare(
  name: :http_dialplan_request_duration_milliseconds,
  buckets: [100, 250, 500, 750, 1000, 1500, 2000, 3000, 5000],
  duration_unit: false
)

Problema: El tipo de llamada aparece como "desconocido"

Síntomas:

Todas las métricas muestran call_type="unknown" en lugar de mt, mo o emergency
No se puede diferenciar el rendimiento entre tipos de llamada

Causa Raíz: La extracción del tipo de llamada está fallando o no se está pasando correctamente a través de la tubería de procesamiento.

Investigación:

Verifique los registros para mensajes de "solicitud HTTP del plan de marcado" - deberían mostrar el tipo de llamada correcto
Verifique que process_call/1 devuelva una tupla {xml, call_type}, no solo xml
Verifique que fsapi_conn/1 extraiga el tipo de llamada de la tupla: {xml, call_type} = process_call(body)

Resolución: Asegúrese de que la tubería de procesamiento del plan de marcado pase correctamente el tipo de llamada a través de todas las funciones.

Problema: Las llamadas son lentas

Investigación:

Verifique http_dialplan_request_duration_milliseconds P95 - COMIENCE AQUÍ
Si es alto, verifique los tiempos de los componentes:
- Verifique subscriber_data_duration_milliseconds para retrasos de Sh
- Verifique hlr_data_duration_milliseconds para retrasos de HLR
- Verifique ocs_authorization_duration_milliseconds para retrasos de OCS
- Verifique dialplan_module_duration_milliseconds para retrasos específicos de módulos
Verifique si call_type="unknown" - indica un fallo en la detección del tipo de llamada
Compare los tiempos de procesamiento de MT vs MO vs Emergency
Correlacione con los registros del sistema para mensajes de error detallados

Resolución: Optimice el componente más lento

Problema: Las llamadas están fallando

Investigación:

Verifique la tasa de call_attempts_total{result="rejected"}
Verifique subscriber_data_lookups_total{result="error"} para problemas de Sh
Verifique hlr_lookups_total{result_type="error"} para problemas de HLR
Verifique ocs_authorization_attempts_total{result="error"} para problemas de OCS
Verifique authorization_decisions_total{disposition="unauthorized"} para problemas de autorización

Resolución: Corrija el componente que está fallando

Problema: Alta carga

Investigación:

Verifique el valor actual de active_calls
Verifique la tasa de call_attempts_total
Verifique si la tasa coincide con el tráfico esperado
Compare la relación MT vs MO
Verifique patrones inusuales (picos, crecimiento constante)

Resolución: Escale o investigue tráfico inusual

Problema: Problemas de roaming

Investigación:

Verifique la tasa de hlr_lookups_total{result_type="msrn"}
Verifique hlr_data_duration_milliseconds para retrasos
Utilice la herramienta de búsqueda de HLR para suscriptores específicos
Verifique si se está recuperando correctamente el MSRN

Resolución: Corrija la conectividad o configuración de HLR

Líneas Base de Rendimiento

Valores Típicos (Sistema Bien Ajustado)

Solicitud HTTP del plan de marcado (de extremo a extremo): P50: 100-500ms, P95: 500-2000ms, P99: 1000-3000ms
Tiempo de búsqueda en Sh: P50: 15ms, P95: 50ms, P99: 100ms
Tiempo de búsqueda en HLR: P50: 100ms, P95: 300ms, P99: 800ms
Tiempo de autorización de OCS: P50: 150ms, P95: 500ms, P99: 1500ms
Procesamiento del módulo de plan de marcado: P50: 1-5ms, P95: 10-25ms, P99: 50ms
Tasa de éxito en Sh: > 99%
Tasa de éxito en HLR: > 95% (menor es normal debido a suscriptores fuera de línea)
Tasa de éxito en OCS: > 98%
Tasa de éxito en llamadas: > 99%

Nota: El tiempo de solicitud HTTP del plan de marcado es la suma de todos los tiempos de los componentes más la sobrecarga. Debería ser aproximadamente igual a: búsqueda en Sh + búsqueda en HLR + autorización de OCS + procesamiento del módulo de plan de marcado + sobrecarga de red/análisis. El tiempo mínimo esperado es ~100ms (cuando solo se necesita la búsqueda en Sh), el tiempo máximo típico es ~2000ms (con todas las búsquedas y reintentos).

Planificación de Capacidad

Monitoree estas tendencias:

Crecimiento en la tasa de call_attempts_total
Crecimiento en el pico de active_calls
Latencias P95 estables o mejorando
Tasas de éxito estables o mejorando

Planifique el escalado cuando:

Las llamadas activas se acerquen al 80% de la capacidad
Las latencias P95 crezcan a pesar de una carga estable
Las tasas de éxito disminuyan a pesar de sistemas externos estables

Integración con Registro

Correlacione métricas con registros:

Alta tasa de error en métricas → Busque mensajes de ERROR en los registros
Tiempos de respuesta lentos → Busque mensajes de WARNING en los registros sobre tiempos de espera
Problemas de llamadas específicas → Busque registros por ID de llamada o número de teléfono
Utilice la herramienta de simulación para reproducir y depurar

Mejores Prácticas

Configure paneles antes de que ocurran problemas
Defina umbrales de alerta basados en su línea base
Pruebe alertas utilizando el Simulador de Llamadas
Revise métricas semanalmente para identificar tendencias
Correlacione métricas con eventos comerciales (campañas, interrupciones, etc.)
Utilice métricas para justificar inversiones en infraestructura
Comparta paneles con el equipo de operaciones
Documente sus procedimientos de respuesta a alertas

Configuración

La recopilación de métricas se habilita automáticamente cuando se inicia la aplicación. El endpoint de métricas se expone en el mismo puerto que la API (por defecto: 8080).

Para configurar Prometheus para raspar métricas, agregue este trabajo a su prometheus.yml:

scrape_configs:
  - job_name: 'omnitas'
    static_configs:
      - targets: ['<tas-ip>:8080']
    metrics_path: '/metrics'
    scrape_interval: 10s

Cardinalidad de Métricas

Las métricas están diseñadas con cardinalidad controlada para evitar abrumar a Prometheus:

Etiquetas de pares: Limitadas solo a pares configurados
Tipos de llamada: Conjunto fijo (mo, mt, emergency, unauthorized)
Códigos de resultado: Limitados a los códigos de resultado de Diámetro/OCS reales recibidos
Operaciones: Conjunto fijo por interfaz (sri/prn para MAP, ccr/cca para Diámetro)

Total estimado de series de tiempo: ~200-500 dependiendo del número de pares configurados y códigos de resultado activos.

Retención de Métricas

Períodos de retención recomendados:

Métricas en bruto: 30 días (alta resolución)
Agregados de 5 minutos: 90 días
Agregados de 1 hora: 1 año
Agregados diarios: 5 años

Esto soporta:

Solución de problemas en tiempo real (métricas en bruto)
Análisis semanal/mensual (agregados de 5 min/1 hora)
Planificación de capacidad (agregados diarios)
Comparación histórica (agregados anuales)

Resumen​

Endpoint de Métricas​

Importante: Configuración de Unidad de Tiempo de Métricas​

Referencia Completa de Métricas​

Métricas de Diámetro​

diameter_response_duration_milliseconds​

diameter_requests_total​

diameter_responses_total​

diameter_peer_state​

Métricas de Generación de Plan de Marcado​

1. Métricas de Solicitudes HTTP​

http_dialplan_request_duration_milliseconds​

2. Métricas de Datos de Suscriptores​

subscriber_data_duration_milliseconds​

subscriber_data_lookups_total​

2. Métricas de Datos de HLR​

hlr_data_duration_milliseconds​

hlr_lookups_total​

3. Métricas de Autorización de OCS​

ocs_authorization_duration_milliseconds​

ocs_authorization_attempts_total​

4. Métricas de Procesamiento de Llamadas​

call_param_errors_total​

authorization_decisions_total​

freeswitch_variable_set_duration_milliseconds​

5. Métricas de Procesamiento de Módulos​

dialplan_module_duration_milliseconds​

6. Métricas de Volumen de Llamadas​

call_attempts_total​

active_calls​

7. Métricas de Simulación​

call_simulations_total​

8. Métricas de SS7 MAP​

ss7_map_http_duration_milliseconds​

ss7_map_operations_total​

9. Métricas de Carga en Línea​

online_charging_events_total​

10. Métricas de Estado del Sistema​

tracked_registrations​

tracked_call_sessions​

11. Métricas de Solicitudes HTTP​

http_requests_total​

12. Métricas de Rechazo de Llamadas​

call_rejections_total​

13. Métricas de Conexión de Socket de Eventos​

event_socket_connected​

event_socket_reconnections_total​

Integración del Panel de Grafana​

Panel 1: Volumen de Llamadas​

Panel 2: Rendimiento de Diámetro​

Panel 3: Salud de Carga en Línea​

Panel 4: Rendimiento del Sistema​

Diseño Recomendado del Panel de Grafana​

Alertas Críticas​

Ejemplos de Alertas​

Par de Diámetro Caído​

Alta Latencia de Diámetro​

Fallos de Crédito de OCS​

Errores de Gateway de SS7 MAP​

Socket de Eventos Desconectado​

Alta Tasa de Rechazo de Llamadas​

Alta Tasa de Error HTTP​

Solución de Problemas con Métricas​

Problema: Métricas que muestran valores irreales (nanosegundos en lugar de milisegundos)​

Problema: El tipo de llamada aparece como "desconocido"​

Problema: Las llamadas son lentas​

Problema: Las llamadas están fallando​

Problema: Alta carga​

Problema: Problemas de roaming​

Líneas Base de Rendimiento​

Valores Típicos (Sistema Bien Ajustado)​

Planificación de Capacidad​

Integración con Registro​

Mejores Prácticas​

Configuración​

Cardinalidad de Métricas​

Retención de Métricas​

Resumen

Endpoint de Métricas

Importante: Configuración de Unidad de Tiempo de Métricas

Referencia Completa de Métricas

Métricas de Diámetro

`diameter_response_duration_milliseconds`

`diameter_requests_total`

`diameter_responses_total`

`diameter_peer_state`

Métricas de Generación de Plan de Marcado

1. Métricas de Solicitudes HTTP

`http_dialplan_request_duration_milliseconds`

2. Métricas de Datos de Suscriptores

`subscriber_data_duration_milliseconds`

`subscriber_data_lookups_total`

2. Métricas de Datos de HLR

`hlr_data_duration_milliseconds`

`hlr_lookups_total`

3. Métricas de Autorización de OCS

`ocs_authorization_duration_milliseconds`

`ocs_authorization_attempts_total`

4. Métricas de Procesamiento de Llamadas

`call_param_errors_total`

`authorization_decisions_total`

`freeswitch_variable_set_duration_milliseconds`

5. Métricas de Procesamiento de Módulos

`dialplan_module_duration_milliseconds`

6. Métricas de Volumen de Llamadas

`call_attempts_total`

`active_calls`

7. Métricas de Simulación

`call_simulations_total`

8. Métricas de SS7 MAP

`ss7_map_http_duration_milliseconds`

`ss7_map_operations_total`

9. Métricas de Carga en Línea

`online_charging_events_total`

10. Métricas de Estado del Sistema

`tracked_registrations`

`tracked_call_sessions`

11. Métricas de Solicitudes HTTP

`http_requests_total`

12. Métricas de Rechazo de Llamadas

`call_rejections_total`

13. Métricas de Conexión de Socket de Eventos

`event_socket_connected`

`event_socket_reconnections_total`

Integración del Panel de Grafana

Panel 1: Volumen de Llamadas

Panel 2: Rendimiento de Diámetro

Panel 3: Salud de Carga en Línea

Panel 4: Rendimiento del Sistema

Diseño Recomendado del Panel de Grafana

Alertas Críticas

Ejemplos de Alertas

Par de Diámetro Caído

Alta Latencia de Diámetro

Fallos de Crédito de OCS

Errores de Gateway de SS7 MAP

Socket de Eventos Desconectado

Alta Tasa de Rechazo de Llamadas

Alta Tasa de Error HTTP

Solución de Problemas con Métricas

Problema: Métricas que muestran valores irreales (nanosegundos en lugar de milisegundos)

Problema: El tipo de llamada aparece como "desconocido"

Problema: Las llamadas son lentas

Problema: Las llamadas están fallando

Problema: Alta carga

Problema: Problemas de roaming

Líneas Base de Rendimiento

Valores Típicos (Sistema Bien Ajustado)

Planificación de Capacidad

Integración con Registro

Mejores Prácticas

Configuración

Cardinalidad de Métricas

Retención de Métricas