RetroDash // LATENCY — Guia de Personalização

Requisitos

Para métricas de latência você precisa de histogramas Prometheus:

http_request_duration_seconds (padrão OpenMetrics)
Ou sua métrica customizada (ex: api_latency_milliseconds)
Com labels: method, endpoint, status
Exportador que publique histogramas (Prometheus client libraries)

Notas de Compatibilidade

Intervalo de rate e tráfego em homelabs

A variável $rate_interval controla a janela de tempo usada nas queries de rate() e histogram_quantile(). O valor padrão é 5m.

Para homelabs com tráfego HTTP baixo ou intermitente, aumente para 15m ou 30m para obter resultados estáveis em vez de janelas vazias com picos.
Para alterar: Configurações do Dashboard → Variables → rate_interval → edite o valor padrão.

"No data" nos painéis de latência é comportamento esperado quando não há tráfego HTTP ativo chegando aos seus serviços — não é um erro de configuração. Os painéis serão preenchidos assim que as requisições começarem a fluir.

Mapa de Painéis

┌────────────────────────────────────────┐
│    LATÊNCIA — PERCENTIS & SLOs         │
├────────────────────────────────────────┤
│  P50      │  P95      │  P99           │
│  (stat)   │  (stat)   │  (stat)        │
├────────────────────────────────────────┤
│  Distribuição Série Temporal [12 cols] │
│  (linhas: P50, P95, P99)               │
├────────────────────────────────────────┤
│  Mapa Calor [6 cols] │ Tabela Endpoint │
│  (buckets tempo)     │ (top handlers)   │
├────────────────────────────────────────┤
│  Alerta SLO — P99 < 500ms [12 cols]   │
└────────────────────────────────────────┘

Personalização por Painel

P50 / P95 / P99 Stats

Três painéis stat que mostram percentis em milissegundos.

Query P50:

histogram_quantile(0.50, rate(http_request_duration_seconds_bucket[5m])) * 1000

Query P95:

histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) * 1000

Query P99:

histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) * 1000

Para métrica customizada (ex: ms já):

histogram_quantile(0.95, rate(my_api_latency_ms_bucket[5m]))

Mudar limiares: Painel → Thresholds → Ajuste limites (ex: 100 amarelo, 200 vermelho)

Distribution Time Series

Gráfico de linhas com evolução de P50, P95, P99 ao longo do tempo.

Adicionar percentis: Em Legend/Aliases, personalize labels:

Percentil	Query	Label
P25	`histogram_quantile(0.25, ...)`	P25
P50	`histogram_quantile(0.50, ...)`	P50 (Mediana)
P90	`histogram_quantile(0.90, ...)`	P90
P95	`histogram_quantile(0.95, ...)`	P95
P99	`histogram_quantile(0.99, ...)`	P99

Mudar janela de rate: Edite [5m] → [1m] para mais sensibilidade ou [15m] para suavizar

Mapa Calor

Visualização de distribuição de latência por buckets ao longo do tempo.

Query padrão (todos buckets):

rate(http_request_duration_seconds_bucket[5m])

Para resolver buckets específicos: Filtre por valores de bucket:

rate(http_request_duration_seconds_bucket{le=~"0.01|0.05|0.1|0.5|1"}[5m])

Ajustar resolução: Painel → Heatmap options → Cell size, mude Bucket para discreto vs. contínuo

Tabela por Endpoint

Tabela dinâmica com latência por endpoint/handler.

Query base:

topk(10, sum by (endpoint) (rate(http_request_duration_seconds_sum[5m])))
/ topk(10, sum by (endpoint) (rate(http_request_duration_seconds_count[5m]))) * 1000

Mudar top N endpoints: Substitua topk(10 com topk(20 ou topk(5

Filtrar por método:

topk(10, sum by (endpoint, method) (rate(http_request_duration_seconds_sum{method="GET"}[5m])))
/ topk(10, sum by (endpoint, method) (rate(http_request_duration_seconds_count{method="GET"}[5m]))) * 1000

Alerta SLO — P99 < 500ms

Stat ou gauge que alerta se P99 ultrapassa o SLO.

SLO padrão (500ms):

histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) * 1000 < 500

Mudar SLO para 300ms:

histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) * 1000 < 300

Para alerta por endpoint:

histogram_quantile(0.99, sum by (endpoint) (rate(http_request_duration_seconds_bucket[5m]))) * 1000 < 250

Cor de alerta: Em Thresholds, configure:

Verde: SLO atendido (< 500ms)
Amarelo: Aproximando SLO (> 400ms)
Vermelho: SLO violado (> 500ms)

Mudar Tema de Cor

Tema	Primário	Secundário	Cor OK
GREEN	`#33FF00`	`#22BB00`	#33FF00
AMBER	`#FFB000`	`#CC8C00`	#FFB000
BLUE	`#00BFFF`	`#0099CC`	#00BFFF

Adaptar à sua Resolução

Tipo	Largura (cols)	Altura (rows)
Mobile (< 768px)	6 (stack vertical)	8
Tablet 10"	12 (largura completa)	10
Tablet 12.9"	12 (largura completa)	12
Desktop 1920×1080	24 (2 colunas)	8

Importar no Grafana

Exporte o painel LATÊNCIA como JSON do Grafana
Ou copie a URI: $GRAFANA_URL/api/dashboards/db/latency
Vá para Dashboards → Import
Cole o JSON ou URL
Certifique-se de selecionar datasource Prometheus
Verifique as métricas em cada painel
Salve e coloque em favoritos

Dicas Avançadas

Correlacionar latência com erros

histogram_quantile(0.95,
  rate(http_request_duration_seconds_bucket{status!~"5.."}[5m])) * 1000

Isso mostra P95 apenas de requisições bem-sucedidas (excluindo 5xx).

Desglose por instância

histogram_quantile(0.95,
  sum by (instance) (rate(http_request_duration_seconds_bucket[5m]))) * 1000

Útil se você tem múltiplos servidores e quer detectar anomalias em instâncias.

Detecção de degradação

rate(increase(http_request_duration_seconds_bucket{le="1"}[5m]))[10m:1m]

Mostra tendência de latência nos últimos 10 minutos com resolução 1m.

RetroDash // LATÊNCIA