PromQL Explainer: Entenda qualquer consulta PromQL.

O PromQL Explainer é uma ferramenta gratuita, que roda no navegador, que pega uma consulta PromQL do Prometheus e a decompõe em uma explicação em linguagem simples. Ele percorre cada parte da expressão — o seletor de métrica e seus comparadores de rótulos, qualquer range ou offset, o rate ou a agregação que o envolve, e a comparação de limite no final — para que você possa ler o que uma consulta realmente faz sem analisá-la de cabeça.

Não. O explainer roda 100% no lado do cliente. Sua consulta é analisada e explicada dentro da aba do seu navegador: nada é enviado para um servidor, e não há conta nem cadastro. Você pode colar com segurança consultas que referenciam nomes internos de métricas ou rótulos.

O explainer cobre os padrões que você encontra com mais frequência em alertas e dashboards: seletores de vetores instantâneos e de range com comparadores de rótulos (=, !=, =~, !~), durações de range e offsets, rate / irate / increase, os operadores de agregação (sum, avg, max, min, count e companhia) com agrupamento by / without, funções comuns como histogram_quantile e clamp, e comparações binárias contra um limite. Subconsultas exóticas ou profundamente aninhadas podem ser resumidas em vez de totalmente decompostas.

O Prometheus mostra o resultado de uma consulta; o explainer mostra o significado dela. Ele não se conecta a um servidor Prometheus nem retorna dados de séries temporais: lê a própria expressão e descreve a intenção. Isso o torna útil para revisar a regra de alerta de um colega, aprender PromQL ou conferir a sanidade de uma consulta antes de publicá-la.

Sim. Como cada cláusula é nomeada e descrita, o explainer também funciona como apoio didático: cole um exemplo de um runbook ou dashboard e veja exatamente de qual seletor, range, agregação e comparação ele é construído. Combine-o com a documentação oficial de consultas do Prometheus para a gramática formal.

Não. É uma ferramenta independente e comunitária, e não é afiliada nem endossada pelo projeto Prometheus nem pela Cloud Native Computing Foundation. Prometheus é uma marca registrada da The Linux Foundation. A ferramenta modela a sintaxe do PromQL por familiaridade e usa o nome do fornecedor apenas para descrever o que ela explica.

rate() calcula a taxa média de aumento por segundo de um contador ao longo da janela de range — por exemplo, rate(http_requests_total[5m]) faz a média do aumento por segundo durante os cinco minutos completos. Ela suaviza os picos e é a escolha padrão para métricas de contador e regras de alerta. O explainer identifica rate() e nomeia a duração do range para que você leia a janela num relance.

rate() faz a média do aumento por segundo ao longo de todo o vetor de range, produzindo valores estáveis que se adequam a alertas e contadores de movimento lento. irate() usa apenas as duas últimas amostras da janela, o que o torna mais responsivo, porém mais ruidoso — melhor reservá-lo para gráficos de contadores de movimento rápido em que você quer ver picos curtos. O explainer rotula aquele que aparecer na sua consulta e descreve o seu comportamento.

Colchetes com uma duração definem um vetor de range — eles dizem ao PromQL para retornar todas as amostras de cada série correspondente naquela janela retroativa. [5m] significa os últimos cinco minutos de dados. Funções como rate(), increase() e avg_over_time() exigem um vetor de range como entrada, então os colchetes são o que faz essas funções funcionarem.

As chaves contêm uma lista separada por vírgulas de comparadores de rótulos que filtram quais séries temporais são selecionadas. O operador = corresponde a um valor exato, != o exclui, =~ corresponde por expressão regular e !~ exclui por expressão regular. Então {job="api", status!="200"} seleciona as séries do job api descartando qualquer uma com status HTTP 200. O explainer nomeia cada comparador e seu operador em linguagem simples.