Grafana PromQL: consultas úteis sem sobrecarregar métricas

ANÁLISE EDITORIAL

Uma consulta PromQL pode retornar um gráfico bonito e ainda responder à pergunta errada. Um contador agregado antes de rate(), um histograma sem o rótulo le, uma divisão sem proteção ou uma seleção ampla demais pode distorcer o resultado e pressionar o servidor. A Grafana PromQL organiza esse trabalho em padrões de consulta, validação e revisão para Prometheus, Grafana Mimir e Grafana Cloud Metrics.

A versão auditada vem do repositório oficial grafana/skills, mantido pela Grafana. Ele tinha 231 estrelas na consulta de 27 de agosto de 2026, estava ativo e está fixado no commit 51d33e71e191b409bbd25fc7be2684c610d18166, sob licença Apache-2.0. A adoção fica abaixo da regra geral de mil estrelas, mas a exceção é verificável: o mantenedor é o fornecedor oficial, há documentação, histórico do repositório e licença explícita. O pacote local é somente textual e não inclui cliente, servidor, plugin, script, token ou dado de telemetria.

O que esta Skill faz de verdade

O arquivo principal ensina um agente a escrever, validar e otimizar PromQL. Ele cobre vetores instantâneos e de intervalo, rate, irate, increase, filtros por rótulo, agregações com by e without, quantis de histogramas, proporções, ausência de séries, deslocamentos de tempo, regras de gravação, SLOs e investigação de cardinalidade. A referência patterns.md reúne exemplos curtos para cada grupo.

A utilidade não está em copiar uma fórmula pronta. A Skill induz uma sequência: descobrir nomes e rótulos reais, escolher uma janela coerente com o intervalo de coleta, limitar a consulta, conferir o tipo da métrica e validar a magnitude contra uma evidência conhecida. A documentação oficial de fundamentos do PromQL lembra que consultas amplas podem operar sobre muitas séries e sobrecarregar servidor ou navegador, mesmo quando a saída final parece pequena.

Ela não instala Prometheus, não configura coleta, não descobre automaticamente o significado de uma métrica e não prova que um painel representa o negócio. Também não substitui a investigação de logs, traces, implantação ou instrumentação quando a causa não está nos dados de métricas.

Para quem serve

Serve a profissionais de SRE, DevOps, plataforma, desenvolvimento e observabilidade que precisam criar ou revisar consultas de taxa, erro, latência, saturação, disponibilidade e tendência. Também ajuda quem recebeu uma expressão gerada por IA e precisa verificar se a sintaxe, os rótulos, a janela, a agregação e a unidade fazem sentido antes de colocar a consulta em dashboard ou alerta.

O melhor cenário é uma pergunta operacional específica, por exemplo: “qual é a fração de respostas 5xx por serviço nos últimos cinco minutos?”. O pior cenário é pedir “otimize meu Prometheus” e conceder acesso amplo. A Skill pode preparar consultas e hipóteses, mas decisões sobre retenção, descarte de rótulos, regras, alertas e custo exigem contexto do ambiente e aprovação separada.

Ela é materialmente diferente das Skills já catalogadas sobre Datadog Logs, ES|QL e instrumentação de IA. Essas tratam busca de logs, linguagem de consulta do Elasticsearch ou geração de telemetria. PromQL trabalha com séries temporais numéricas em fontes compatíveis com Prometheus e foca a semântica da consulta, não a coleta nem a busca textual.

Compatibilidade e pré-requisitos

O repositório oficial declara compatibilidade com Claude Code, Cursor, Codex e ferramentas que seguem o padrão Agent Skills. Para uso funcional, é necessário um endpoint Prometheus, Mimir ou Grafana Cloud Metrics acessível pelo usuário, ou uma fonte Prometheus configurada no Grafana Explore. O ZIP local não fornece nenhum desses componentes.

• Cliente capaz de carregar SKILL.md e preservar a referência relativa references/patterns.md.
• Acesso de leitura a um ambiente de teste ou a métricas autorizadas.
• Conhecimento do intervalo de coleta, nomes das métricas, unidades e rótulos disponíveis.
• Ferramenta de consulta, como Grafana Explore, navegador de expressão do Prometheus ou HTTP API.
• Limites de tempo, intervalo, quantidade de séries e custo definidos antes de consultas exploratórias.
• Dados conhecidos ou evento de teste para conferir ordem de grandeza e unidade.

A documentação do editor Prometheus no Grafana descreve os modos visual e de código e recomenda restringir consultas de alta cardinalidade. Recursos e telas podem mudar por versão, portanto trate o commit auditado como fotografia documental, não como contrato permanente da interface.

Instalação recomendada

Para leitura e auditoria, baixe o pacote local e confira seus quatro arquivos. Compare SKILL.md e references/patterns.md com o diretório oficial no commit auditado. A licença completa está preservada e também pode ser conferida no arquivo Apache-2.0 oficial.

1. Extraia o ZIP em uma pasta de revisão fora de produção.
2. Leia o frontmatter e o corpo do SKILL.md.
3. Abra patterns.md e marque quais exemplos são relevantes para suas métricas reais.
4. Compare os dois arquivos com o commit fixado e registre qualquer diferença.
5. Se decidir instalar, use um projeto de teste e confira exatamente quais arquivos foram gravados.

O README oficial fixado documenta npx skills add grafana/skills e opções específicas para Claude Code. Esse comando consulta a rede e pode instalar um conjunto maior que a pasta PromQL. Revise o destino e prefira manter apenas a Skill necessária quando o cliente permitir seleção.

Configuração antes do primeiro uso

Comece por uma ficha curta: pergunta, fonte de dados, ambiente, métrica, tipo, unidade, rótulos obrigatórios, intervalo de coleta, janela de análise e limite de séries. Sem isso, uma consulta sintaticamente válida pode misturar ambientes, somar unidades incompatíveis ou ocultar uma falha atrás de uma média.

Use identidade somente leitura sempre que a ferramenta permitir. Para Grafana Cloud ou Mimir, mantenha URL, usuário e token fora do prompt, do histórico, do arquivo HTML e do repositório. Não cole cabeçalhos, cookies ou respostas contendo rótulos sensíveis. Se o agente não precisa executar a consulta, forneça apenas nomes e amostras mascaradas.

A regra do arquivo auditado sugere uma janela de pelo menos quatro vezes o intervalo de coleta para rate() e increase(). Essa é uma heurística útil, não uma garantia universal. Confirme lacunas, resets, jitter, retenção e objetivo do painel. A referência oficial de funções deve decidir o comportamento atual de cada função.

Primeiro uso seguro

Peça primeiro uma análise sem alteração: “Dada a pergunta operacional e estes nomes de métricas e rótulos, proponha uma consulta PromQL, explique tipo, unidade, janela e agregação e liste o que precisa ser confirmado. Não execute nem crie regras”. Revise a resposta antes de liberar qualquer endpoint.

Quando houver autorização para consultar, comece no modo tabela, com intervalo curto e filtro por ambiente ou serviço. O documento oficial de fundamentos recomenda reduzir o conjunto antes de gerar gráficos. Use a HTTP API oficial apenas com credencial protegida e parâmetros codificados, ou cole a expressão no Grafana Explore.

Confira três coisas antes de avançar: a consulta retorna séries, os rótulos correspondem ao escopo e a ordem de grandeza bate com uma fonte conhecida. Um resultado vazio não prova ausência de incidente. Pode indicar nome errado, rótulo inexistente, janela curta, coleta interrompida ou permissão insuficiente.

Resultado esperado

A primeira entrega deve ser uma expressão reproduzível acompanhada por pergunta, ambiente, período, fonte, unidade, rótulos preservados, quantidade de séries e interpretação limitada. Para uma taxa de erro, mostre separadamente numerador e denominador antes da divisão. Para latência, diga se o dado vem de histograma clássico, histograma nativo ou summary.

Uma boa revisão inclui comparação com um contador, log ou teste controlado. Também registra o que ainda não foi validado: cobertura da instrumentação, tráfego de baixa frequência, resets de processo, séries ausentes, atraso de coleta e impacto da consulta. O objetivo é tornar o raciocínio auditável, não esconder incerteza atrás de uma expressão compacta.

Se a consulta for repetida ou cara, a Skill sugere uma regra de gravação. A documentação oficial de regras mostra como validar arquivos com promtool check rules. Criar ou carregar uma regra é uma mudança operacional e deve ficar fora do primeiro ciclo de leitura.

Permissões e riscos

O ZIP é somente Markdown e licença. O risco aparece quando o agente recebe endpoint, token, acesso ao Grafana ou permissão para alterar regras. Uma consulta ampla pode consumir CPU, memória e amostras. Uma regra mal desenhada pode multiplicar séries. Um rótulo com identificador de usuário pode expor dados ou provocar cardinalidade explosiva.

• Comece com leitura, intervalo curto e filtros específicos.
• Não entregue tokens, cookies, cabeçalhos ou URLs privadas ao contexto do agente.
• Evite selecionar todos os nomes ou todos os valores de rótulo em ambiente desconhecido.
• Separe consulta exploratória, regra de gravação, alerta e descarte de rótulos em aprovações diferentes.
• Antes de remover um rótulo na coleta, confirme dashboards, alertas, SLOs e investigações que dependem dele.
• Valide custo e volume no backend usado, pois Prometheus local, Mimir e Grafana Cloud têm limites diferentes.

Os exemplos de SLO e burn rate exigem definição de objetivo, evento bom, evento total, janela e política de alerta. Não use um alvo genérico do exemplo como compromisso real do serviço.

Erros comuns

Agregar antes de calcular taxa: para contadores, aplique rate() por série antes de somar, preservando a capacidade de detectar resets. Depois agregue pelos rótulos necessários.

Quantil inválido: histogramas clássicos precisam manter le na agregação interna. A documentação oficial de histogramas explica a diferença entre buckets, summaries e histogramas nativos.

Divisão vazia ou enganosa: inspecione numerador e denominador, alinhe rótulos e trate ausência de tráfego. Uma proteção sintática contra zero não decide qual valor representa o negócio.

Série demais: restrinja métrica, ambiente e intervalo antes de agregar. topk ajuda a investigar, mas não corrige uma estratégia ruim de rótulos.

Regra de gravação diferente da expressão: compare ambas no mesmo instante e considere atraso e intervalo de avaliação. A prática oficial de nomes e agregações ajuda a manter o resultado legível.

Alerta baseado em pico: irate() reage aos dois últimos pontos e pode ser instável para alertas. Confirme o comportamento desejado e use rate() quando a janela completa for necessária.

Versão auditada e download local

A curadoria fixou o commit 51d33e71e191b409bbd25fc7be2684c610d18166 de grafana/skills, consultado em 27/08/2026 com 231 estrelas e licença Apache-2.0. A exceção ao piso de mil estrelas foi aceita porque a Skill é mantida oficialmente pela Grafana e possui documentação, licença e histórico verificáveis.

O pacote tem 8.568 bytes e SHA-256 5495b49b170ba6512edf16ad51068cebde8d0e8998b6ba1ac0dd166002f13b77. Baixar o pacote documental auditado. O botão do repositório oficial permanece separado no card. Compare o hash depois do download e use o catálogo de Skills do Bastidores da IA para conferir o padrão de distribuição.

Entradas incluídas: SKILL.md, references/patterns.md, LICENSE e ORIGEM.md. Não há scripts, manifests, clientes, plugins, binários, dependências, credenciais, consultas executadas ou dados de métricas.

Resultado esperado e limite final

A Skill pode transformar uma pergunta vaga em uma consulta explicada, limitada e verificável. Ela também pode apontar erros de agregação, histogramas, proporções e cardinalidade antes que uma expressão seja copiada para um painel ou alerta. Ainda assim, não conhece sozinha a semântica da sua instrumentação, não valida cobertura e não mede o impacto real sem dados autorizados.

Use o primeiro ciclo para leitura e proposta. Use o segundo para uma consulta curta em ambiente controlado. Só depois discuta regra de gravação ou alerta, com diff, promtool, revisão de custo e rollback. Descartar rótulos, mudar coleta ou publicar um alerta são decisões operacionais separadas.

Ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela, painel real, logotipo oficial, consulta executada, alerta disparado nem prova de redução de custo.

Fontes primárias

• Grafana PromQL no commit auditado
• SKILL.md oficial fixado
• Biblioteca oficial de padrões
• Fundamentos oficiais do PromQL
• Operadores do PromQL
• Consulta no Grafana Mimir