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 baseada em 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 das 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.

Pode usar etiquetas de metadados no PromQL tal como qualquer outra etiqueta, mas, tal como os nomes das métricas, as etiquetas de metadados também têm de ser compatíveis com o PromQL. A sintaxe para referir uma etiqueta do sistema de metadados version é metadata_system_version e a sintaxe para uma etiqueta do utilizador de metadados version é metadata_user_version. As consultas PromQL bem formadas que usam etiquetas de metadados podem ter o seguinte aspeto:

  • {"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

Se a chave da etiqueta de metadados contiver carateres especiais que não sejam o caráter _, tem de incluir a chave da etiqueta entre aspas duplas (") de acordo com a especificação UTF-8 do PromQL. Ainda tem de prefixar a etiqueta de metadados com a string metadata_user_.

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.

Aceder ao PromQL no Cloud Monitoring

Pode usar o PromQL no separador Código nas seguintes páginas na Google Cloud consola:

  • Metrics Explorer
  • Adicionar gráfico ao criar painéis personalizados

Para obter informações sobre como aceder ao editor e usá-lo, consulte o artigo Usar o editor do PromQL.

Regras e alertas do PromQL

Pode usar o PromQL para criar políticas de alerta para qualquer métrica no Cloud Monitoring. Para mais informações, consulte as políticas de alerta baseadas em PromQL.

Também pode usar o PromQL para criar regras de gravação e alerta em qualquer métrica no Cloud Monitoring usando alertas no cluster ao estilo do Prometheus no Cloud Monitoring. Para mais informações, consulte os artigos Avaliação e alertas de regras geridas ou Avaliação e alertas de regras implementadas autonomamente.

Aprender PromQL

Para saber o básico sobre a 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 e muitas das geradas por métricas baseadas em registos, são mapeadas para mais do que um tipo de recurso. Se estiver a usar uma destas métricas, especialmente métricas baseadas em registos, tem de especificar explicitamente o tipo de recurso.

Pode ver que tipos de recursos monitorizados são mapeados para uma métrica através de um dos seguintes métodos:

  • Para métricas organizadas pela Google, pode consultar as listas de métricas disponíveis, incluindo Google Cloud métricas e métricas do Kubernetes. 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.

  • No Explorador de métricas, pode fazer o seguinte:

    1. Introduza o nome da métrica no campo Selecionar uma métrica e, de seguida, navegue pelos menus para selecionar a métrica. O menu de recursos apresenta os tipos de recursos válidos para essa métrica, por exemplo, "Instância de VM".

    2. Na barra de ferramentas do painel do criador de consultas, selecione o botão com o nome < > PromQL.

      A consulta PromQL apresentada mostra o tipo de recurso como o valor do campo monitored_resource. Em particular, este método é útil para métricas que podem ser associadas a muitos tipos de recursos monitorizados, por exemplo, métricas baseadas em registos, métricas personalizadas ou qualquer métrica definida pelo utilizador.

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.

Os tipos de recursos monitorizados são, na maioria dos casos, 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"}
  • custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

O valor de "" para a etiqueta monitored_resource é especial e refere-se ao tipo de recurso prometheus_target predefinido que é usado para as métricas do Cloud Monitoring.

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 de 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
kubernetes.io/container/cpu/limit_cores kubernetes_io:container_cpu_limit_cores
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count
custom.googleapis.com/opencensus/opencensus.io/
http/server/request_count_by_method		 custom_googleapis_com:opencensus_opencensus_io_
http_server_request_count_by_method
agent.googleapis.com/disk/io_time agent_googleapis_com:disk_io_time

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:

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 a montante.

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 PromQL tradicional. 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 faça a escala automática 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 Samples Ingested ou da métrica Samples Written by Attribution ID.

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 originar 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 com um 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.