Guia de Métricas e Monitoramento do Prometheus

Visão Geral

OmniTAS exporta métricas operacionais abrangentes no formato Prometheus para monitoramento, alerta e observabilidade. Este guia cobre todas as métricas disponíveis, seu uso, solução de problemas e melhores práticas de monitoramento.

Endpoint de Métricas

Todas as métricas são expostas em: http://<tas-ip>:8080/metrics

Importante: Configuração da Unidade de Tempo da Métrica

Todas as métricas de duração neste sistema usam duration_unit: false em suas declarações de Histograma. Isso é crítico porque:

A biblioteca Prometheus Elixir detecta automaticamente nomes de métricas que terminam em _milliseconds
Por padrão, ela converte unidades de tempo nativas do Erlang em milissegundos automaticamente
Nosso código já converte o tempo em milissegundos usando System.convert_time_unit/3
Sem duration_unit: false, a biblioteca converteria milissegundos em nanossegundos (dividindo por ~1.000.000)

Exemplo:

# Configuração correta
Histogram.declare(
  name: :http_dialplan_request_duration_milliseconds,
  help: "Duração das requisições HTTP do dialplan em milissegundos",
  labels: [:call_type],
  buckets: [100, 250, 500, 750, 1000, 1500, 2000, 3000, 5000],
  duration_unit: false  # OBRIGATÓRIO para evitar conversão dupla
)

# Medindo o tempo corretamente
start_time = System.monotonic_time()
# ... fazer trabalho ...
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)

Referência Completa de Métricas

Métricas de Diâmetro

`diameter_response_duration_milliseconds`

Tipo: Histograma
Rótulos: application (ro, sh), command (ccr, cca, etc), result (success, error, timeout)
Buckets: 10, 50, 100, 250, 500, 1000, 2500, 5000, 10000 ms
Descrição: Duração das requisições Diameter em milissegundos

Uso:

# Tempo médio de resposta Diameter
rate(diameter_response_duration_milliseconds_sum[5m]) /
rate(diameter_response_duration_milliseconds_count[5m])

# Latência P95 Diameter
histogram_quantile(0.95, rate(diameter_response_duration_milliseconds_bucket[5m]))

Alerta Quando:

P95 > 1000ms - Respostas Diameter lentas

`diameter_requests_total`

Tipo: Contador
R��tulos: application (ro, sh), command (ccr, udr, etc)
Descrição: Número total de requisições Diameter enviadas

Uso:

# Taxa de requisições
rate(diameter_requests_total[5m])

`diameter_responses_total`

Tipo: Contador
Rótulos: application (ro, sh), command (ccr, udr, etc), result_code (2001, 3002, 5xxx, etc)
Descrição: Número total de respostas Diameter recebidas

Uso:

# Taxa de sucesso
rate(diameter_responses_total{result_code="2001"}[5m]) /
rate(diameter_responses_total[5m]) * 100

`diameter_peer_state`

Tipo: Gauge
Rótulos: peer_host, peer_realm, application (ro, sh)
Descrição: Estado dos pares Diameter (1=up, 0=down)
Intervalo de atualização: A cada 10 segundos

Uso:

# Verificar pares inativos
diameter_peer_state == 0

Alerta Quando:

Qualquer par inativo por > 1 minuto

Métricas de Geração de Dialplan

1. Métricas de Requisições HTTP

`http_dialplan_request_duration_milliseconds`

Tipo: Histograma
Rótulos: call_type (mt, mo, emergency, unknown)
Descrição: Duração da requisição HTTP de ponta a ponta desde o recebimento da requisição HTTP do dialplan até o envio da resposta. Isso inclui todo o processamento: análise de parâmetros, autorização, buscas Diameter (Sh/Ro), buscas HLR (SS7 MAP) e geração de XML.

Uso:

# Tempo médio da requisição HTTP de ponta a ponta
rate(http_dialplan_request_duration_milliseconds_sum[5m]) /
rate(http_dialplan_request_duration_milliseconds_count[5m])

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

# Comparar desempenho 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 Quando:

P95 > 2000ms - Tempos de resposta HTTP lentos
P95 > 3000ms - Problema crítico de desempenho
P99 > 5000ms - Degradação severa de desempenho
Qualquer requisição mostrando call_type="unknown" - Falha na detecção do tipo de chamada

Insights:

Esta é a métrica mais importante para entender a latência voltada para o usuário
Valores típicos: P50: 100-500ms, P95: 500-2000ms, P99: 1000-3000ms
Inclui todos os tempos de componentes (Sh + HLR + OCS + processamento)
Se isso estiver lento, aprofunde-se nas métricas de componentes (subscriber_data, hlr_data, ocs_authorization)
Faixa esperada: 100ms (chamadas locais rápidas) a 5000ms (lentas com tentativas/tempo limite)

Notas Importantes:

Substitui a métrica mais antiga dialplan_generation_duration_milliseconds que apenas media a geração de XML
Reflete com precisão o que o FreeSWITCH/SBC experimenta
Use isso para monitoramento de SLA e planejamento de capacidade

2. Métricas de Dados do Assinante

`subscriber_data_duration_milliseconds`

Tipo: Histograma
Rótulos: result (success, error)
Descrição: Tempo levado para recuperar dados do assinante da interface Sh (HSS)

Uso:

# Tempo médio de busca Sh
rate(subscriber_data_duration_milliseconds_sum[5m]) /
rate(subscriber_data_duration_milliseconds_count[5m])

# Tempo de busca Sh no 95º percentil
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m])
)

Alerta Quando:

P95 > 100ms - Respostas HSS lentas
P95 > 500ms - Problema crítico de desempenho do HSS

`subscriber_data_lookups_total`

Tipo: Contador
Rótulos: result (success, error)
Descrição: Número total de buscas de dados do assinante

Uso:

# Taxa de busca Sh
rate(subscriber_data_lookups_total[5m])

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

# Taxa de sucesso da busca Sh em porcentagem
(rate(subscriber_data_lookups_total{result="success"}[5m]) /
 rate(subscriber_data_lookups_total[5m])) * 100

Alerta Quando:

Taxa de erro > 5% - Problemas de conectividade HSS
Taxa de erro > 20% - Falha crítica do HSS

2. Métricas de Dados HLR

`hlr_data_duration_milliseconds`

Tipo: Histograma
Rótulos: result (success, error)
Descrição: Tempo levado para recuperar dados HLR via SS7 MAP

Uso:

# Tempo médio de busca HLR
rate(hlr_data_duration_milliseconds_sum[5m]) /
rate(hlr_data_duration_milliseconds_count[5m])

# Tempo de busca HLR no 95º percentil
histogram_quantile(0.95,
  rate(hlr_data_duration_milliseconds_bucket[5m])
)

Alerta Quando:

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

`hlr_lookups_total`

Tipo: Contador
Rótulos: result_type (msrn, forwarding, error, unknown)
Descrição: Total de buscas HLR por tipo de resultado

Uso:

# Taxa de busca HLR por tipo
rate(hlr_lookups_total[5m])

# Taxa de descoberta MSRN (assinantes em roaming)
rate(hlr_lookups_total{result_type="msrn"}[5m])

# Taxa de descoberta de encaminhamento de chamadas
rate(hlr_lookups_total{result_type="forwarding"}[5m])

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

Alerta Quando:

Taxa de erro > 10% - Problemas de SS7 MAP
Queda súbita na taxa de MSRN - Possível problema de roaming

Insights:

Alta taxa de MSRN indica muitos assinantes em roaming
Alta taxa de encaminhamento indica muitas chamadas encaminhadas
Compare com o volume de chamadas para porcentagem de roaming

3. Métricas de Autorização OCS

`ocs_authorization_duration_milliseconds`

Tipo: Histograma
Rótulos: result (success, error)
Descrição: Tempo levado para autorização OCS

Uso:

# Tempo médio de autenticação OCS
rate(ocs_authorization_duration_milliseconds_sum[5m]) /
rate(ocs_authorization_duration_milliseconds_count[5m])

# Tempo de autenticação OCS no 95º percentil
histogram_quantile(0.95,
  rate(ocs_authorization_duration_milliseconds_bucket[5m])
)

Alerta Quando:

P95 > 1000ms - Respostas OCS lentas
P95 > 5000ms - Problema crítico de desempenho OCS

`ocs_authorization_attempts_total`

Tipo: Contador
Rótulos: result (success, error), skipped (yes, no)
Descrição: Total de tentativas de autorização OCS

Uso:

# Taxa de autorização OCS
rate(ocs_authorization_attempts_total{skipped="no"}[5m])

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

# Taxa de pulo OCS (emergência, correio de voz, etc.)
rate(ocs_authorization_attempts_total{skipped="yes"}[5m])

# Taxa de sucesso da autorização OCS em porcentagem
(rate(ocs_authorization_attempts_total{result="success",skipped="no"}[5m]) /
 rate(ocs_authorization_attempts_total{skipped="no"}[5m])) * 100

Alerta Quando:

Taxa de erro > 5% - Problemas de conectividade OCS
Taxa de sucesso < 95% - OCS recusando muitas chamadas

Insights:

Alta taxa de pulo indica muitas chamadas de emergência/gratuitas
Picos na taxa de erro indicam falhas no OCS
Compare a taxa de sucesso com as expectativas de negócios

4. Métricas de Processamento de Chamadas

`call_param_errors_total`

Tipo: Contador
Rótulos: error_type (parse_failed, missing_required_params)
Descrição: Erros de análise de parâmetros de chamadas

Uso:

# Taxa de erro de parâmetros
rate(call_param_errors_total[5m])

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

Alerta Quando:

Qualquer erro > 0 - Indica solicitações de parâmetros de chamada malformadas
Erros > 1% do volume de chamadas - Problema crítico

`authorization_decisions_total`

Tipo: Contador
Rótulos: disposition (mt, mo, emergency, unauthorized), result (success, error)
Descrição: Decisões de autorização por tipo de chamada

Uso:

# Taxa de autorização por disposição
rate(authorization_decisions_total[5m]) by (disposition)

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

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

# Taxa de chamadas de emergência
rate(authorization_decisions_total{disposition="emergency"}[5m])

# Taxa de chamadas não autorizadas
rate(authorization_decisions_total{disposition="unauthorized"}[5m])

Alerta Quando:

Taxa não autorizada > 1% - Possível ataque ou má configuração
Aumento súbito em chamadas de emergência - Possível evento de emergência
Mudança inesperada na razão MT/MO - Possível problema

Insights:

A razão MT/MO indica padrões de tráfego
A taxa de chamadas de emergência indica uso do serviço
A taxa não autorizada indica postura de segurança

`freeswitch_variable_set_duration_milliseconds`

Tipo: Histograma
Rótulos: batch_size (1, 5, 10, 25, 50, 100)
Descrição: Tempo para definir Variáveis do Dialplan

Uso:

# Tempo médio para definir variáveis
rate(freeswitch_variable_set_duration_milliseconds_sum[5m]) /
rate(freeswitch_variable_set_duration_milliseconds_count[5m])

# Tempo de definição de variáveis por tamanho de lote
histogram_quantile(0.95,
  rate(freeswitch_variable_set_duration_milliseconds_bucket[5m])
) by (batch_size)

Alerta Quando:

P95 > 100ms - Desempenho lento na definição de variáveis
Tendência crescente - Possível problema de desempenho do sistema

5. Métricas de Processamento de Módulos

`dialplan_module_duration_milliseconds`

Tipo: Histograma
Rótulos: module (MT, MO, Emergency, CallParams, etc.), call_type
Descrição: Tempo de processamento para cada módulo do dialplan

Uso:

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

# Tempo de processamento do módulo MT
histogram_quantile(0.95,
  rate(dialplan_module_duration_milliseconds_bucket{module="MT"}[5m])
)

Alerta Quando:

Qualquer módulo P95 > 500ms - Problema de desempenho
Tendência crescente em qualquer módulo - Vazamento ou problema potencial

Insights:

Identifique qual módulo é o mais lento
Otimize os módulos mais lentos primeiro
Compare os tempos dos módulos entre os tipos de chamadas

6. Métricas de Volume de Chamadas

`call_attempts_total`

Tipo: Contador
Rótulos: call_type (mt, mo, emergency, unauthorized), result (success, rejected)
Descrição: Total de tentativas de chamadas

Uso:

# Taxa de tentativas de chamadas
rate(call_attempts_total[5m])

# Taxa de sucesso por tipo de chamada
(rate(call_attempts_total{result="success"}[5m]) /
 rate(call_attempts_total[5m])) * 100 by (call_type)

# Taxa de chamadas rejeitadas
rate(call_attempts_total{result="rejected"}[5m])

Alerta Quando:

Taxa de rejeição > 5% - Possível problema
Queda súbita no volume de chamadas - Interrupção do serviço
Aumento súbito no volume de chamadas - Possível ataque

`active_calls`

Tipo: Gauge
Rótulos: call_type (mt, mo, emergency)
Descrição: Chamadas atualmente ativas

Uso:

# Chamadas ativas atuais
active_calls

# Chamadas ativas por tipo
active_calls by (call_type)

# Pico de chamadas ativas (última hora)
max_over_time(active_calls[1h])

Alerta Quando:

Chamadas ativas > capacidade - Sobrecarga
Chamadas ativas = 0 por tempo prolongado - Serviço fora do ar

7. Métricas de Simulação

`call_simulations_total`

Tipo: Contador
Rótulos: call_type (mt, mo, emergency, unauthorized), source (web, api)
Descrição: Simulações de chamadas executadas

Uso:

# Taxa de simulação
rate(call_simulations_total[5m])

# Simulações por tipo
rate(call_simulations_total[5m]) by (call_type)

Insights:

Acompanhe o uso da ferramenta de diagnóstico
Identifique usuários pesados
Correlacione com atividade de solução de problemas

8. Métricas SS7 MAP

`ss7_map_http_duration_milliseconds`

Tipo: Histograma
Rótulos: operation (sri, prn), result (success, error, timeout)
Buckets: 10, 50, 100, 250, 500, 1000, 2500, 5000, 10000 ms
Descrição: Duração das requisições HTTP SS7 MAP em milissegundos

Uso:

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

Alerta Quando:

P95 > 500ms - Respostas SS7 MAP lentas
Taxa de erro > 50% - Problema crítico de SS7 MAP

`ss7_map_operations_total`

Tipo: Contador
Rótulos: operation (sri, prn), result (success, error)
Descrição: Número total de operações SS7 MAP

9. Métricas de Cobrança Online

`online_charging_events_total`

Tipo: Contador
Rótulos: event_type (authorize, answer, reauth, hangup), result (success, nocredit, error, timeout)
Descrição: Número total de eventos de cobrança online

Uso:

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

Alerta Quando:

Alta taxa de falhas de crédito

10. Métricas de Estado do Sistema

`tracked_registrations`

Tipo: Gauge
Descrição: Número de registros SIP atualmente ativos (do banco de dados de registro Sofia do FreeSWITCH)
Intervalo de atualização: A cada 10 segundos

Notas:

Decrementa automaticamente quando os registros expiram (o FreeSWITCH gerencia a expiração)

`tracked_call_sessions`

Tipo: Gauge
Descrição: Número de sessões de chamadas atualmente rastreadas no ETS
Intervalo de atualização: A cada 10 segundos

11. Métricas de Requisições HTTP

`http_requests_total`

Tipo: Contador
Rótulos: endpoint (dialplan, call_event, directory, voicemail, sms_ccr, metrics), status_code (200, 400, 500, etc)
Descrição: Número total de requisições HTTP por endpoint

Uso:

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

Alerta Quando:

Taxa de erro HTTP 5xx > 10%

12. Métricas de Rejeição de Chamadas

`call_rejections_total`

Tipo: Contador
Rótulos: call_type (mo, mt, emergency, unknown), reason (nocredit, unauthorized, parse_failed, missing_params, hlr_error, etc)
Descrição: Número total de rejeições de chamadas por motivo

Uso:

# Taxa de rejeição de chamadas por motivo
sum by (reason) (rate(call_rejections_total[5m]))

Alerta Quando:

Taxa de rejeição > 1/sec - Investigação necessária

13. Métricas de Conexão do Socket de Evento

`event_socket_connected`

Tipo: Gauge
Rótulos: connection_type (main, log_listener)
Descrição: Estado da conexão do Socket de Evento (1=conectado, 0=desconectado)
Intervalo de atualização: Tempo real em mudanças de estado de conexão

Uso:

# Status da Conexão do Socket de Evento
event_socket_connected

Alerta Quando:

Conexão inativa por > 30 segundos

`event_socket_reconnections_total`

Tipo: Contador
Rótulos: connection_type (main, log_listener), result (attempting, success, failed)
Descrição: Número total de tentativas de reconexão do Socket de Evento

Integração com o Dashboard do Grafana

As métricas podem ser visualizadas no Grafana usando a fonte de dados Prometheus. Painéis recomendados:

Dashboard 1: Volume de Chamadas

Gauge de chamadas ativas
Taxa de tentativas de chamadas por tipo (MO/MT/Emergency)
Taxa de rejeição de chamadas

Dashboard 2: Desempenho do Diâmetro

Mapa de calor do tempo de resposta
Taxas de requisição/resposta
Tabela de status de pares
Taxa de erro por código de resultado

Dashboard 3: Saúde da Cobrança Online

Taxa de sucesso da autorização de crédito
Taxa de eventos "Sem crédito"
Taxa de tempo limite OCS

Dashboard 4: Desempenho do Sistema

Latência de geração do dialplan (P50/P95/P99)
Tempos de resposta SS7 MAP
Disponibilidade geral do sistema

Layout Recomendado do Dashboard do Grafana

Linha 1: Volume de Chamadas

Taxa de tentativas de chamadas (por tipo)
Gauge de chamadas ativas
Porcentagem da taxa de sucesso

Linha 2: Desempenho

Tempo P95 da requisição HTTP do dialplan (por tipo de chamada) - MÉTRICA PRINCIPAL
Tempo P95 de busca Sh
Tempo P95 de busca HLR
Tempo P95 de autorização OCS
Tempo P95 de processamento do módulo do dialplan (por módulo)

Linha 3: Taxas de Sucesso

Taxa de sucesso da busca Sh
Taxa de sucesso da busca HLR
Taxa de sucesso da autorização OCS
Taxa de sucesso das tentativas de chamadas

Linha 4: Desempenho do Módulo

Tempo de processamento P95 por módulo
Contagens de chamadas por módulo

Linha 5: Erros

Erros de parâmetros
Tentativas não autorizadas
Erros Sh
Erros HLR
Erros OCS

Alertas Críticos

Prioridade 1 (Página imediatamente):

# Dialplan completamente fora do ar
rate(call_attempts_total[5m]) == 0

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

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

Prioridade 2 (Alerta):

# Geração de dialplan lenta
histogram_quantile(0.95,
  rate(dialplan_generation_duration_milliseconds_bucket[5m])
) > 1000

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

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

Prioridade 3 (Aviso):

# Latência HSS elevada
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m])
) > 100

# Latência OCS elevada
histogram_quantile(0.95,
  rate(ocs_authorization_duration_milliseconds_bucket[5m])
) > 1000

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

Exemplos de Alerta

Par Diameter Inativo

alert: DiameterPeerDown
expr: diameter_peer_state == 0
for: 1m
annotations:
  summary: "Par Diameter {{ $labels.peer_host }} está inativo"

Alta Latência Diameter

alert: HighDiameterLatency
expr: histogram_quantile(0.95, rate(diameter_response_duration_milliseconds_bucket[5m])) > 1000
for: 5m
annotations:
  summary: "Latência P95 Diameter acima de 1s"

Falhas de Crédito OCS

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

Erros de Gateway 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: "Taxa de erro SS7 MAP acima de 50%"

Socket de Evento Desconectado

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

Alta Taxa de Rejeição de Chamadas

alert: HighCallRejectionRate
expr: rate(call_rejections_total[5m]) > 1
for: 2m
annotations:
  summary: "Alta taxa de rejeição de chamadas: {{ $value }} rejeições/segundo"

Alta Taxa de Erro HTTP

alert: HighHTTPErrorRate
expr: rate(http_requests_total{status_code=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.1
for: 3m
annotations:
  summary: "Taxa de erro HTTP 5xx acima de 10%"

Solução de Problemas com Métricas

Problema: Métricas mostrando valores irreais (nanossegundos em vez de milissegundos)

Sintomas:

Valores de _sum do histograma são extremamente pequenos (por exemplo, 0.000315 em vez de 315)
Todas as requisições mostrando no menor bucket (< 5ms) quando deveriam ser mais lentas
Valores parecem ser 1.000.000x menores do que o esperado

Causa Raiz: A biblioteca Prometheus Elixir converte automaticamente as unidades de tempo quando os nomes das métricas terminam em _milliseconds, _seconds, etc. Se duration_unit: false não estiver definido, a biblioteca converterá seus milissegundos já convertidos em nanossegundos.

Investigação:

Verifique a declaração da métrica em lib/metrics.ex

Verifique se duration_unit: false está presente:

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

Verifique se o código de medição usa a conversão de tempo adequada:

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

Resolução:

Adicione duration_unit: false à declaração do histograma
Reinicie a aplicação (necessário para recarregar as declarações de métricas)
Verifique se as métricas mostram valores realistas após a correção

Exemplo de Correção:

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

# Depois (CORRETO - mostrará milissegundos)
Histogram.declare(
  name: :http_dialplan_request_duration_milliseconds,
  buckets: [100, 250, 500, 750, 1000, 1500, 2000, 3000, 5000],
  duration_unit: false
)

Problema: Tipo de chamada mostrando como "desconhecido"

Sintomas:

Todas as métricas mostram call_type="unknown" em vez de mt, mo ou emergency
Não é possível diferenciar o desempenho entre os tipos de chamadas

Causa Raiz: A extração do tipo de chamada está falhando ou não está sendo passada corretamente pelo pipeline de processamento.

Investigação:

Verifique os logs para mensagens de "requisição HTTP do dialplan" - elas devem mostrar o tipo de chamada correto
Verifique se process_call/1 retorna a tupla {xml, call_type}, não apenas xml
Verifique se fsapi_conn/1 extrai o tipo de chamada da tupla: {xml, call_type} = process_call(body)

Resolução: Assegure-se de que o pipeline de processamento do dialplan passe corretamente o tipo de chamada por todas as funções.

Problema: Chamadas estão lentas

Investigação:

Verifique o P95 de http_dialplan_request_duration_milliseconds - COMECE AQUI
Se alto, verifique os tempos dos componentes:
- Verifique subscriber_data_duration_milliseconds para atrasos Sh
- Verifique hlr_data_duration_milliseconds para atrasos HLR
- Verifique ocs_authorization_duration_milliseconds para atrasos OCS
- Verifique dialplan_module_duration_milliseconds para atrasos específicos de módulo
Verifique se call_type="unknown" - indica falha na detecção do tipo de chamada
Compare os tempos de processamento MT vs MO vs Emergency
Correlacione com logs do sistema para mensagens de erro detalhadas

Resolução: Otimize o componente mais lento

Problema: Chamadas estão falhando

Investigação:

Verifique a taxa de call_attempts_total{result="rejected"}
Verifique subscriber_data_lookups_total{result="error"} para problemas Sh
Verifique hlr_lookups_total{result_type="error"} para problemas HLR
Verifique ocs_authorization_attempts_total{result="error"} para problemas OCS
Verifique authorization_decisions_total{disposition="unauthorized"} para problemas de autorização

Resolução: Corrija o componente que está falhando

Problema: Alta carga

Investigação:

Verifique o valor atual de active_calls
Verifique a taxa de call_attempts_total
Verifique se a taxa corresponde ao tráfego esperado
Compare a razão MT vs MO
Verifique padrões incomuns (picos, crescimento constante)

Resolução: Escale para cima ou investigue tráfego incomum

Problema: Problemas de roaming

Investigação:

Verifique a taxa de hlr_lookups_total{result_type="msrn"}
Verifique hlr_data_duration_milliseconds para atrasos
Use a ferramenta de busca HLR para assinantes específicos
Verifique se o MSRN está sendo recuperado corretamente

Resolução: Corrija a conectividade ou configuração HLR

Linhas de Base de Desempenho

Valores Típicos (Sistema Bem Ajustado)

Requisição HTTP do dialplan (de ponta a ponta): P50: 100-500ms, P95: 500-2000ms, P99: 1000-3000ms
Tempo de busca Sh: P50: 15ms, P95: 50ms, P99: 100ms
Tempo de busca HLR: P50: 100ms, P95: 300ms, P99: 800ms
Tempo de autenticação OCS: P50: 150ms, P95: 500ms, P99: 1500ms
Processamento do módulo do dialplan: P50: 1-5ms, P95: 10-25ms, P99: 50ms
Taxa de sucesso Sh: > 99%
Taxa de sucesso HLR: > 95% (menor é normal devido a assinantes offline)
Taxa de sucesso OCS: > 98%
Taxa de sucesso de chamadas: > 99%

Nota: O tempo de requisição do dialplan HTTP é a soma de todos os tempos de componentes mais a sobrecarga. Deve ser aproximadamente igual a: busca Sh + busca HLR + autenticação OCS + processamento do módulo do dialplan + sobrecarga de rede/análise. O tempo mínimo esperado é ~100ms (quando apenas a busca Sh é necessária), o tempo máximo típico é ~2000ms (com todas as buscas e tentativas).

Planejamento de Capacidade

Monitore essas tendências:

Crescimento na taxa de call_attempts_total
Crescimento no pico de active_calls
Latências P95 estáveis ou em melhoria
Taxas de sucesso estáveis ou em melhoria

Planeje para escalar quando:

Chamadas ativas se aproximarem de 80% da capacidade
Latências P95 crescendo apesar da carga estável
Taxas de sucesso em declínio apesar de sistemas externos estáveis

Integração com Logging

Correlacione métricas com logs:

Alta taxa de erro nas métricas → Pesquise logs para mensagens de ERRO
Tempos de resposta lentos → Pesquise logs para mensagens de AVISO sobre timeouts
Problemas de chamadas específicas → Pesquise logs por ID de chamada ou número de telefone
Use a ferramenta de simulação para reproduzir e depurar

Melhores Práticas

Configure dashboards antes que os problemas ocorram
Defina limites de alerta com base em sua linha de base
Teste alertas usando o Simulador de Chamadas
Revise métricas semanalmente para identificar tendências
Correlacione métricas com eventos de negócios (campanhas, interrupções, etc.)
Use métricas para justificar investimentos em infraestrutura
Compartilhe dashboards com a equipe de operações
Documente seus procedimentos de resposta a alertas

Configuração

A coleta de métricas é automaticamente habilitada quando a aplicação é iniciada. O endpoint de métricas é exposto na mesma porta que a API (padrão: 8080).

Para configurar o Prometheus para coletar métricas, adicione este trabalho ao seu prometheus.yml:

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

Cardinalidade das Métricas

As métricas são projetadas com cardinalidade controlada para evitar sobrecarregar o Prometheus:

Rótulos de pares: Limitados apenas aos pares configurados
Tipos de chamadas: Conjunto fixo (mo, mt, emergency, unauthorized)
Códigos de resultado: Limitados aos códigos de resultado Diameter/OCS reais recebidos
Operações: Conjunto fixo por interface (sri/prn para MAP, ccr/cca para Diameter)

Total estimado de séries temporais: ~200-500 dependendo do número de pares configurados e códigos de resultado ativos.

Retenção de Métricas

Períodos de retenção recomendados:

Métricas brutas: 30 dias (alta resolução)
Agregados de 5 minutos: 90 dias
Agregados de 1 hora: 1 ano
Agregados diários: 5 anos

Isso suporta:

Solução de problemas em tempo real (métricas brutas)
Análise semanal/mensal (agregados de 5 min/1 hora)
Planejamento de capacidade (agregados diários)
Comparação histórica (agregados anuais)

Visão Geral​

Endpoint de Métricas​

Importante: Configuração da Unidade de Tempo da Métrica​

Referência 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 Geração de Dialplan​

1. Métricas de Requisições HTTP​

http_dialplan_request_duration_milliseconds​

2. Métricas de Dados do Assinante​

subscriber_data_duration_milliseconds​

subscriber_data_lookups_total​

2. Métricas de Dados HLR​

hlr_data_duration_milliseconds​

hlr_lookups_total​

3. Métricas de Autorização OCS​

ocs_authorization_duration_milliseconds​

ocs_authorization_attempts_total​

4. Métricas de Processamento de Chamadas​

call_param_errors_total​

authorization_decisions_total​

freeswitch_variable_set_duration_milliseconds​

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

dialplan_module_duration_milliseconds​

6. Métricas de Volume de Chamadas​

call_attempts_total​

active_calls​

7. Métricas de Simulação​

call_simulations_total​

8. Métricas SS7 MAP​

ss7_map_http_duration_milliseconds​

ss7_map_operations_total​

9. Métricas de Cobrança Online​

online_charging_events_total​

10. Métricas de Estado do Sistema​

tracked_registrations​

tracked_call_sessions​

11. Métricas de Requisições HTTP​

http_requests_total​

12. Métricas de Rejeição de Chamadas​

call_rejections_total​

13. Métricas de Conexão do Socket de Evento​

event_socket_connected​

event_socket_reconnections_total​

Integração com o Dashboard do Grafana​

Dashboard 1: Volume de Chamadas​

Dashboard 2: Desempenho do Diâmetro​

Dashboard 3: Saúde da Cobrança Online​

Dashboard 4: Desempenho do Sistema​

Layout Recomendado do Dashboard do Grafana​

Alertas Críticos​

Exemplos de Alerta​

Par Diameter Inativo​

Alta Latência Diameter​

Falhas de Crédito OCS​

Erros de Gateway SS7 MAP​

Socket de Evento Desconectado​

Alta Taxa de Rejeição de Chamadas​

Alta Taxa de Erro HTTP​

Solução de Problemas com Métricas​

Problema: Métricas mostrando valores irreais (nanossegundos em vez de milissegundos)​

Problema: Tipo de chamada mostrando como "desconhecido"​

Problema: Chamadas estão lentas​

Problema: Chamadas estão falhando​

Problema: Alta carga​

Problema: Problemas de roaming​

Linhas de Base de Desempenho​

Valores Típicos (Sistema Bem Ajustado)​

Planejamento de Capacidade​

Integração com Logging​

Melhores Práticas​

Configuração​

Cardinalidade das Métricas​

Retenção de Métricas​

Visão Geral

Endpoint de Métricas

Importante: Configuração da Unidade de Tempo da Métrica

Referência 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 Geração de Dialplan

1. Métricas de Requisições HTTP

`http_dialplan_request_duration_milliseconds`

2. Métricas de Dados do Assinante

`subscriber_data_duration_milliseconds`

`subscriber_data_lookups_total`

2. Métricas de Dados HLR

`hlr_data_duration_milliseconds`

`hlr_lookups_total`

3. Métricas de Autorização OCS

`ocs_authorization_duration_milliseconds`

`ocs_authorization_attempts_total`

4. Métricas de Processamento de Chamadas

`call_param_errors_total`

`authorization_decisions_total`

`freeswitch_variable_set_duration_milliseconds`

5. Métricas de Processamento de Módulos

`dialplan_module_duration_milliseconds`

6. Métricas de Volume de Chamadas

`call_attempts_total`

`active_calls`

7. Métricas de Simulação

`call_simulations_total`

8. Métricas SS7 MAP

`ss7_map_http_duration_milliseconds`

`ss7_map_operations_total`

9. Métricas de Cobrança Online

`online_charging_events_total`

10. Métricas de Estado do Sistema

`tracked_registrations`

`tracked_call_sessions`

11. Métricas de Requisições HTTP

`http_requests_total`

12. Métricas de Rejeição de Chamadas

`call_rejections_total`

13. Métricas de Conexão do Socket de Evento

`event_socket_connected`

`event_socket_reconnections_total`

Integração com o Dashboard do Grafana

Dashboard 1: Volume de Chamadas

Dashboard 2: Desempenho do Diâmetro

Dashboard 3: Saúde da Cobrança Online

Dashboard 4: Desempenho do Sistema

Layout Recomendado do Dashboard do Grafana

Alertas Críticos

Exemplos de Alerta

Par Diameter Inativo

Alta Latência Diameter

Falhas de Crédito OCS

Erros de Gateway SS7 MAP

Socket de Evento Desconectado

Alta Taxa de Rejeição de Chamadas

Alta Taxa de Erro HTTP

Solução de Problemas com Métricas

Problema: Métricas mostrando valores irreais (nanossegundos em vez de milissegundos)

Problema: Tipo de chamada mostrando como "desconhecido"

Problema: Chamadas estão lentas

Problema: Chamadas estão falhando

Problema: Alta carga

Problema: Problemas de roaming

Linhas de Base de Desempenho

Valores Típicos (Sistema Bem Ajustado)

Planejamento de Capacidade

Integração com Logging

Melhores Práticas

Configuração

Cardinalidade das Métricas

Retenção de Métricas