Quem já escreveu queries no Prometheus ou no Grafana sabe: dominar as funções do PromQL é a diferença entre ter um gráfico bonito e conseguir de fato extrair respostas das métricas.

Não basta saber coletar dados , é preciso transformar séries temporais em informações úteis. Para isso, o PromQL oferece funções que permitem calcular taxas de crescimento, detectar picos, fazer agregações, prever tendências e até calcular percentis de latência a partir de histogramas.

Neste artigo, apresento um guia prático (cheat sheet) das funções PromQL mais usadas no dia a dia de SREs, DevOps e engenheiros de observabilidade.

Cada função vem acompanhada de:

  • O que faz.
  • Um exemplo de query.
  • Quando usar no contexto de monitoramento.

Se você já se perguntou se deveria usar rate ou irate, ou como calcular o p95 de latência, este guia é para você.

1. Funções de Taxa e Crescimento

Essas são as mais usadas para métricas de contadores (counters), que só aumentam.

rate(vetor[intervalo])

Calcula a taxa média por segundo no período.

Exemplo: quantas requisições por segundo em média nos últimos 5 minutos.

rate(http_requests_total[5m])

irate(vetor[intervalo])

Taxa instantânea (derivada do último par de pontos). Detecta pico instantâneo, bom para detectar spikes.

irate(http_requests_total[1m])

increase(vetor[intervalo])

Quanto o contador aumentou no período.

increase(http_requests_total[1h])

total de requisições na última hora.

2. Funções de Agregação

Usadas para somar, contar, agrupar séries.

sum

Soma valores.

sum(rate(cpu_usage_seconds_total[5m])) by (instance)

avg

Média.

avg(rate(node_network_receive_bytes_total[1m])) by (device)

max / min

Valor máximo/mínimo.

max(memory_usage_bytes) by (pod)

count

Número de séries retornadas.

count(up{job="node"})

3. Funções de Manipulação de Séries

Mexem nas séries de tempo em si.

rate + sum + by()

Para agrupar séries por rótulos.

sum(rate(container_cpu_usage_seconds_total[5m])) by (namespace)

topk(N, métrica)

Retorna o top N.

topk(5, rate(http_requests_total[5m]))

os 5 endpoints mais acessados.

bottomk(N, métrica)

O inverso: os menores valores.

4. Funções de Previsão e Mudança

predict_linear(vetor[intervalo], tempo)

Projeta valores futuros.

predict_linear(node_filesystem_free_bytes[1h], 4 * 3600)

prevê espaço livre em 4h, ótimo para alertas de disco.

changes(vetor[intervalo])

Quantas vezes o valor mudou.

changes(up[1h])

quantas vezes o serviço caiu/subiu na última hora.

resets(vetor[intervalo])

Quantas vezes um contador foi resetado.

5. Funções Matemáticas

abs: valor absoluto.

ceil / floor: arredondar.

clamp_min / clamp_max: limitar valores.

round(vetor, precisão)

round(cpu_temp_celsius, 0.5)

6. Funções de Histogramas

histogram_quantile(φ, sum(rate(…)))

Usada para métricas de latência.

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

calcula o p95 do tempo de resposta HTTP.

Boas práticas no uso de funções PromQL

Escolha bem a janela de tempo ([5m], [1h]):

  • Janela muito curta = dados ruidosos (spikes falsos)

  • Janela muito longa = suaviza demais e esconde problemas.

Regra prática: use [$__rate_interval] no Grafana para adaptar dinamicamente.

Counters ≠ Gauges:

  • Use rate, irate, increase apenas para counters (métricas que só crescem, como requisições, bytes transmitidos).

  • Para gauges (CPU, memória), use avg_over_time, max_over_time, etc.

Use by() conscientemente:

sum(rate(http_requests_total[5m])) = soma tudo junto.

sum(rate(http_requests_total[5m])) by (job) = mostra por job.

Prefira rate a irate em alertas:

irate é útil para visualizar spikes, mas em alertas pode gerar falsos positivos.

Para latência, sempre histogram_quantile:

Percentis de tempo de resposta só fazem sentido em histogramas. Média de latência isolada pode enganar.

Combine funções: PromQL brilha quando você compõe funções. Exemplo:

topk(5, rate(http_requests_total[5m])) by route)

mostra os 5 endpoints mais acessados no período.

Dúvidas comuns

Quando usar rate vs increase?

rate → “velocidade” (quantos por segundo).

increase → “quanto acumulou” (total em X tempo).

Por que meu gráfico fica serrilhado com irate? Porque ele usa só os dois últimos pontos. Útil para spikes, mas não para visão estável.

Posso usar rate em métricas de memória ou CPU? Não. Essas métricas são gauges (valores atuais). Use avg_over_time, max_over_time, etc.

O que significa offset? É um deslocamento no tempo. rate(http_requests_total[5m]) offset 1d compara hoje com ontem.

Por que meu sum não bate com o total? Provavelmente faltou usar by() corretamente ou algum label está duplicando séries.