PromQL para o Cloud Monitoring

Este documento descreve a utilização da linguagem de consulta Prometheus (PromQL) no Cloud Monitoring. O PromQL oferece uma alternativa à interface orientada por menus do Metrics Explorer para criar gráficos e painéis de controlo.

Pode usar o PromQL para consultar e criar gráficos de dados do Cloud Monitoring a partir das seguintes origens:

Também pode usar ferramentas como o Grafana para criar gráficos de dados de métricas carregados no Cloud Monitoring. As métricas disponíveis incluem métricas do Managed Service for Prometheus e métricas do Cloud Monitoring documentadas nas listas de métricas. Para obter informações sobre a configuração do Grafana e de outras ferramentas baseadas na API Prometheus, consulte a documentação do Managed Service for Prometheus sobre o Grafana.

Também pode importar os seus painéis de controlo do Grafana para o Cloud Monitoring.

Consultar métricas do Cloud Monitoring através do PromQL

As métricas do Cloud Monitoring podem ser consultadas através da especificação UTF-8 para PromQL. Os nomes de métricas UTF-8 têm de estar entre aspas e ser movidos para dentro das chaves. Os nomes das etiquetas também têm de estar entre aspas se contiverem carateres incompatíveis com versões anteriores. Para a métrica do Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, as seguintes consultas são equivalentes:

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

As métricas com valores de distribuição do Cloud Monitoring podem ser consultadas como histogramas do Prometheus, com o sufixo _count, _sum ou _bucket anexado ao nome da métrica.

Os gráficos e os painéis de controlo criados antes da compatibilidade com UTF-8 consultam as métricas do Cloud Monitoring convertendo os respetivos nomes em equivalentes compatíveis com o PromQL antigo. Para mais informações sobre as regras de conversão do PromQL antigo, consulte o artigo Mapeamento de métricas do Cloud Monitoring para o PromQL antigo.

Aprender PromQL

Para aprender as noções básicas da utilização do PromQL, recomendamos que consulte a documentação de código aberto. Os seguintes recursos podem ajudar a começar:

Especificar um tipo de recurso monitorizado

Quando uma métrica do Cloud Monitoring está associada apenas a um único tipo de recurso monitorizado do Cloud Monitoring, a consulta PromQL funciona sem especificar manualmente um tipo de recurso. No entanto, algumas métricas no Cloud Monitoring, incluindo algumas métricas do sistema, são mapeadas para mais do que um tipo de recurso.

Pode ver que tipos de recursos monitorizados são mapeados para uma métrica consultando a lista de Google Cloud métricas. Cada entrada na documentação apresenta os tipos de recursos monitorizados associados na primeira coluna de cada entrada abaixo do tipo. Se não forem indicados tipos de recursos monitorizados, a métrica pode ser associada a qualquer tipo.

Se uma métrica estiver associada a mais do que um tipo de recurso, tem de especificar o tipo de recurso na sua consulta PromQL. Existe uma etiqueta especial, monitored_resource, que pode usar para selecionar o tipo de recurso.

Na maioria dos casos, os tipos de recursos monitorizados são uma string curta, como gce_instance, mas, ocasionalmente, aparecem como URIs completos, como monitoring.googleapis.com/MetricIngestionAttribution. As consultas PromQL bem formadas podem ter o seguinte aspeto:

  • logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Se não usar a etiqueta monitored_resource quando for necessário, recebe o seguinte erro:

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

Resolver conflitos de etiquetas

No Cloud Monitoring, as etiquetas podem pertencer à métrica ou ao recurso. Se uma etiqueta de métrica tiver o mesmo nome de chave que uma etiqueta de recurso, pode consultar especificamente a etiqueta de métrica adicionando o prefixo metric_ ao nome da chave da etiqueta na sua consulta.

Por exemplo, suponhamos que tem uma etiqueta de recurso e uma etiqueta de métrica com o nome pod_name na métrica example.googleapis.com/user/widget_count.

  • Para filtrar pelo valor da etiqueta de recurso, use
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • Para filtrar pelo valor da etiqueta da métrica, use
    example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Mapeamento de nomes de métricas do Cloud Monitoring para PromQL antigo

Os nomes das métricas do Cloud Monitoring incluem dois componentes: um domínio (como compute.googleapis.com/) e um caminho (como instance/disk/max_read_ops_count). Uma vez que o PromQL antigo só suporta os carateres especiais : e _, tem de aplicar as seguintes regras para tornar os nomes das métricas do Monitoring compatíveis com o PromQL antigo:

  • Substituir o primeiro / por :.
  • Substitua todos os outros carateres especiais (incluindo . e outros carateres / ) por _.

A tabela seguinte apresenta alguns nomes de métricas e os respetivos equivalentes do PromQL antigo:

Nome da métrica do Cloud Monitoring Nome da métrica PromQL antiga
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count

As métricas com valor de distribuição do Cloud Monitoring podem ser consultadas como histogramas do Prometheus, com o sufixo _count, _sum ou _bucket anexado ao nome da métrica:

Nome da métrica do Cloud Monitoring Nomes de métricas PromQL antigos
networking.googleapis.com/vm_flow/rtt networking_googleapis_com:vm_flow_rtt_sum
networking_googleapis_com:vm_flow_rtt_count
networking_googleapis_com:vm_flow_rtt_bucket

Compatibilidade com PromQL

O PromQL para o Cloud Monitoring pode funcionar de forma ligeiramente diferente do PromQL upstream.

As consultas PromQL no Cloud Monitoring são parcialmente avaliadas no back-end Monarch através de uma linguagem de consulta interna, e existem algumas diferenças conhecidas nos resultados das consultas. Além das diferenças indicadas nesta secção, o PromQL no Cloud Monitoring está em paridade com o PromQL disponível na versão 2.44 do Prometheus.

As funções PromQL adicionadas após a versão 2.44 do Prometheus podem não ser suportadas.

Suporte de UTF-8

O PromQL para o Cloud Monitoring suporta consultas UTF-8.

Se o nome da métrica do Prometheus consistir apenas em carateres alfanuméricos mais os carateres _ ou :, e se as chaves de etiquetas consistirem apenas em carateres alfanuméricos mais o caráter _, pode consultar através da sintaxe tradicional do PromQL. Por exemplo, uma consulta válida pode ter o seguinte aspeto: job:my_metric:sum{label_key="label_value"}.

No entanto, se o nome da métrica do Prometheus usar carateres especiais, exceto os carateres _ ou :, ou se as chaves de etiqueta usarem carateres especiais, exceto o carater _, tem de criar a consulta de acordo com a especificação UTF-8 para PromQL.

Os nomes de métricas UTF-8 têm de estar entre aspas e ser movidos para as chavetas. Os nomes das etiquetas também têm de estar entre aspas se contiverem carateres incompatíveis com versões anteriores. Os seguintes exemplos de consultas válidas são todos equivalentes:

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

Correspondência nos nomes das métricas

Apenas é suportada a correspondência exata nos nomes das métricas. Tem de incluir uma correspondência exata no nome da métrica na sua consulta.

Recomendamos as seguintes soluções alternativas para cenários comuns que usam um motor de correspondência de expressões regulares na etiqueta __name__:

  • As configurações do adaptador do Prometheus usam frequentemente o operador =~ para fazer a correspondência com vários nomes de métricas. Para corrigir esta utilização, expanda a configuração para usar uma política separada para cada métrica e nomeie cada métrica explicitamente. Isto também impede que a escala automática seja feita acidentalmente em métricas inesperadas.
  • As expressões regulares são frequentemente usadas para representar graficamente várias métricas não dimensionais no mesmo gráfico. Por exemplo, se tiver uma métrica como cpu_servicename_usage, pode usar um caráter universal para representar graficamente todos os seus serviços em conjunto. A utilização de métricas não dimensionais como esta é uma prática explicitamente má no Cloud Monitoring, e esta prática leva a um desempenho de consulta extremamente fraco. Para corrigir esta utilização, mova toda a dimensionalidade para etiquetas de métricas em vez de incorporar dimensões no nome da métrica.
  • A consulta de várias métricas é frequentemente usada para ver que métricas estão disponíveis para consulta. Em alternativa, recomendamos que use a chamada /labels/__name__/values para descobrir métricas. Também pode descobrir métricas através da IU do Cloud Monitoring.
  • A correspondência de várias métricas é útil para ver quantas amostras foram extraídas, carregadas e cobradas por métrica. O Cloud Monitoring fornece-lhe estas informações na página Gestão de métricas. Também pode aceder a estas informações como dados de métricas através da métrica Amostras carregadas ou da métrica Amostras escritas pelo ID de atribuição.

Desatualização

A obsolescência não é suportada no back-end do Monarch.

Cálculo de irate

Quando a janela retrospetiva da função irate é inferior ao tamanho do passo, aumentamos a janela para o tamanho do passo. O Monarch requer esta alteração para garantir que nenhum dos dados de entrada é completamente ignorado na saída. Esta diferença também se aplica aos cálculos de rate.

Cálculo de rate e increase

Quando a janela retrospetiva da função rate é inferior ao tamanho do passo, aumentamos a janela para o tamanho do passo. O Monarch requer esta alteração para garantir que nenhum dos dados de entrada é completamente ignorado na saída. Esta diferença também se aplica aos cálculos de irate.

Existem diferenças nos cálculos de interpolação e extrapolação. O Monarch usa um algoritmo de interpolação diferente do Prometheus, e esta diferença pode gerar resultados ligeiramente diferentes. Por exemplo, as amostras de contador do Monarch são armazenadas com um intervalo de tempo, em vez da indicação de tempo única que o Prometheus usa. Por conseguinte, as amostras de contador no Monarch podem ser incluídas num cálculo da taxa, mesmo que a data/hora do Prometheus as exclua. Geralmente, isto resulta em resultados de taxas mais precisos, especialmente quando consulta dados no início ou no fim da série cronológica subjacente.

Cálculo de histogram_quantile

Um cálculo de PromQL histogram_quantile num histograma sem amostras produz um valor NaN. O cálculo da linguagem de consulta interna não produz nenhum valor. Em alternativa, o ponto na data/hora é ignorado.

As diferenças de cálculo das tarifas também podem afetar a entrada de consultas histogram_quantile.

Funções específicas do tipo em métricas com tipos diferentes

Embora o Prometheus a montante seja fracamente tipado, o Monarch é fortemente tipado. Isto significa que a execução de funções específicas de um único tipo numa métrica de tipo diferente (por exemplo, a execução de rate() numa métrica GAUGE ou histogram_quantile() numa métrica COUNTER ou sem tipo) não funciona no Cloud Monitoring, embora estas funções funcionem no Prometheus a montante.