PromQL para Cloud Monitoring

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

O PromQL pode ser usado para consultar e criar gráficos usando dados do Cloud Monitoring destas fontes:

Também é possível usar ferramentas como o Grafana para criar gráficos com dados de métricas ingeridos pelo Cloud Monitoring. As métricas disponíveis incluem as do Managed Service para Prometheus e do Cloud Monitoring que constam nas listas de métricas. Para informações sobre como configurar o Grafana e outras ferramentas com base na API do Prometheus, consulte a documentação do Managed Service para Prometheus sobre o Grafana.

Também é possível importar os painéis do Grafana para o Cloud Monitoring.

Consultar métricas do Cloud Monitoring usando o PromQL

As métricas do Cloud Monitoring podem ser consultadas usando a especificação UTF-8 para PromQL. Os nomes de métricas UTF-8 precisam ser colocados entre as chaves. Os nomes de rótulos também precisam ser colocados entre aspas se contiverem caracteres incompatíveis com versões legadas. Para a métrica do Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, as consultas a seguir 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 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.

É possível usar rótulos de metadados no PromQL como qualquer outro rótulo, mas, como nomes de métricas, os rótulos de metadados também precisam ser compatíveis com o PromQL. A sintaxe para se referir a um rótulo do sistema de metadados version é metadata_system_version, e a sintaxe do rótulo de usuário de metadados version é metadata_user_version. Consultas PromQL bem formadas que usam rótulos de metadados podem ter a seguinte aparência:

  • {"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 do rótulo de metadados tiver caracteres especiais diferentes de _, coloque a chave entre aspas duplas (") de acordo com a especificação UTF-8 do PromQL. Você ainda precisa prefixar o rótulo de metadados com a string metadata_user_.

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

Como acessar o PromQL no Cloud Monitoring

É possível usar o PromQL na guia Código nas seguintes páginas do console Google Cloud :

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

Para informações sobre como acessar e usar o editor, consulte Como usar o editor do PromQL.

Regras e alertas do PromQL

É possível usar o PromQL para criar políticas de alertas para qualquer métrica no Cloud Monitoring. Para mais informações, consulte Políticas de alertas baseadas em PromQL.

Também é possível usar o PromQL para criar regras de gravação e alerta em qualquer métrica no Cloud Monitoring usando alertas no cluster no estilo do Prometheus no Cloud Monitoring. Para mais informações, consulte Avaliação e alerta de regras gerenciadas ou Avaliação e alerta de regras autoimplantadas.

Aprendizado sobre promQL

Para aprender os conceitos básicos do uso do PromQL, recomendamos consultar a documentação de código aberto. Estes recursos podem ajudar você a começar:

Como especificar um tipo de recurso monitorado

Quando uma métrica do Cloud Monitoring é associada a apenas um único tipo de recurso monitorado do Cloud Monitoring, a consulta do 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 geradas por métricas com base em registros, são mapeadas para mais de um tipo de recurso. Se você estiver usando uma dessas métricas, especialmente as com base em registros, especifique explicitamente o tipo de recurso.

Para ver quais tipos de recursos monitorados são mapeados para uma métrica, siga um destes procedimentos:

  • Para métricas selecionadas pelo Google, consulte as listas de métricas disponíveis, incluindo métricas do Google Cloud e do Kubernetes. Cada entrada na documentação lista os tipos de recursos monitorados associados na primeira coluna de cada entrada abaixo do tipo. Se nenhum tipo de recurso monitorado for listado, a métrica poderá ser associada a qualquer tipo.

  • No Metrics Explorer, você pode fazer as seguintes ações:

    1. Insira o nome da métrica no campo Selecionar uma métrica e navegue pelos menus para selecioná-la. O menu de recursos lista os tipos de recurso válidos para essa métrica, como "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 exibida mostra o tipo de recurso como o valor do campo monitored_resource. Em particular, esse método é útil para métricas que podem ser associadas a muitos tipos de recursos monitorados, como métricas com base em registros, métricas personalizadas ou qualquer métrica definida pelo usuário.

Se uma métrica estiver associada a mais de um tipo de recurso, especifique-o na consulta PromQL. Há um rótulo especial, monitored_resource, que pode ser usado para selecionar o tipo de recurso.

Os tipos de recursos monitorados são, na maioria dos casos, uma string curta, como gce_instance. De vez em quando, eles aparecem como URIs completos, como monitoring.googleapis.com/MetricIngestionAttribution. Consultas PromQL bem formadas podem ter a seguinte aparência:

  • 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 o rótulo monitored_resource é especial e se refere ao tipo de recurso padrão prometheus_target usado para métricas do Cloud Monitoring.

Se você não usar o rótulo monitored_resource quando necessário, o seguinte erro será exibido:

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

Como resolver conflitos de rótulos

No Cloud Monitoring, os rótulos podem pertencer à métrica ou ao recurso. Se um rótulo de métrica tiver o mesmo nome de chave que um rótulo de recurso, será possível fazer referência ao rótulo de métrica especificamente adicionando o prefixo metric_ ao nome da chave de rótulo na consulta.

Por exemplo, suponha que você tenha um rótulo de recurso e um rótulo de métrica denominados pod_name na métrica example.googleapis.com/user/widget_count.

  • Para filtrar o valor do rótulo do recurso, use
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • Para filtrar o valor do rótulo 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 o PromQL legado

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). Como o PromQL legado só é compatível com os caracteres especiais : e _, aplique as regras a seguir para tornar os nomes das métricas do Monitoring compatíveis com o PromQL legado:

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

A tabela a seguir lista alguns nomes de métricas e os equivalentes legados do PromQL:

Nome da métrica do Cloud Monitoring Nome da métrica do PromQL legada
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 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 legadas do PromQL
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 Cloud Monitoring pode funcionar de maneira um pouco diferente do PromQL upstream.

As consultas da PromQL no Cloud Monitoring são parcialmente avaliadas no back-end do Monarch usando uma linguagem de consulta interna, e há algumas diferenças conhecidas nos resultados da consulta. Além das diferenças listadas nesta seção, o PromQL no Cloud Monitoring é igual ao 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 compatíveis.

Compatibilidade com UTF-8

O PromQL para Cloud Monitoring é compatível com consultas UTF-8.

Se o nome da métrica do Prometheus consistir apenas em caracteres alfanuméricos mais os caracteres _ ou :, e se as chaves de rótulo consistirem apenas em caracteres alfanuméricos mais o caractere _, você poderá consultar usando a sintaxe tradicional do PromQL. Por exemplo, uma consulta válida pode ser assim: job:my_metric:sum{label_key="label_value"}.

No entanto, se o nome da métrica do Prometheus usar caracteres especiais, exceto _ ou :, ou se as chaves de rótulo usarem caracteres especiais, exceto _, você precisará criar a consulta de acordo com a especificação UTF-8 para PromQL.

Os nomes de métricas UTF-8 precisam ser colocados entre aspas e chaves. Os nomes de rótulos também precisam ser colocados entre aspas se contiverem caracteres incompatíveis com versões legadas. Os exemplos de consultas válidas a seguir são 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"}

Como corresponder com nomes de métricas

Só é possível fazer a correspondência exata com nomes de métricas. Você precisa 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 comparador de expressões regulares no marcador __name__:

  • As configurações do adaptador do Prometheus geralmente usam o operador =~ para corresponder a vários nomes de métricas. Para corrigir esse uso, expanda a configuração para usar uma política separada para cada métrica e nomeie cada uma explicitamente. Isso também evita que você faça o escalonamento automático acidentalmente em métricas inesperadas.
  • As expressões regulares são usadas com frequência para representar graficamente várias métricas sem dimensão no mesmo gráfico. Por exemplo, se você tiver uma métrica como cpu_servicename_usage, poderá usar um curinga para representar todos os serviços juntos. Usar métricas não dimensionais como essa é uma prática explicitamente ruim no Cloud Monitoring, e isso leva a um desempenho de consulta extremamente ruim. Para corrigir esse uso, mova toda a dimensionalidade para rótulos de métricas em vez de incorporar dimensões no nome da métrica.
  • A consulta em várias métricas é usada com frequência para ver quais métricas estão disponíveis. Recomendamos que você use a chamada /labels/__name__/values para descobrir métricas. Você também pode descobrir métricas usando a interface do Cloud Monitoring.
  • A correspondência de várias métricas é útil para saber quantas amostras foram coletadas, ingeridas e cobradas por métrica. O Cloud Monitoring fornece essas informações na página Gerenciamento de métricas. Também é possível acessar essas informações como dados de métrica usando a métrica "Exemplos ingeridos" ou "Exemplos gravados por ID de atribuição".

Inatividade

A inatividade não é compatível com o back-end do Monarch.

Cálculo de irate

Quando a janela de lookback da função irate é menor que o tamanho da etapa, aumentamos a janela para o tamanho da etapa. O Monarch requer essa mudança para garantir que nenhum dos dados de entrada seja completamente ignorado na saída. Essa diferença também se aplica a cálculos rate.

Cálculo de rate e increase

Quando a janela de lookback da função rate é menor que o tamanho da etapa, aumentamos a janela para o tamanho da etapa. O Monarch exige essa mudança para garantir que nenhum dos dados de entrada seja completamente ignorado na saída. Essa diferença também se aplica a cálculos irate.

Há diferenças nos cálculos de interpolação e extrapolação. O Monarch usa um algoritmo de interpolação diferente do Prometheus, e essa diferença pode levar a resultados um pouco diferentes. Por exemplo, as amostras do contador Monarch são armazenadas com um intervalo de tempo em vez do único carimbo de data/hora usado pelo Prometheus. Portanto, as amostras de contador no Monarch podem ser incluídas em um cálculo de taxa, mesmo que o carimbo de data/hora do Prometheus as exclua. Isso normalmente gera resultados de taxa mais precisos, especialmente ao consultar o início ou o fim da série temporal subjacente.

Cálculo de histogram_quantile

Um cálculo histogram_quantile do PromQL em um histograma sem amostras produz um valor NaN. O cálculo da linguagem de consulta interna não produz valor. Em vez disso, o ponto no carimbo de data/hora é descartado.

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

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

Embora o Prometheus upstream seja do tipo fraco, o Monarch tem uma classificação forte. Isso significa que a execução de funções específicas para um único tipo em uma métrica de tipo diferente (por exemplo, executar rate() em uma métrica do GAUGE ou histogram_quantile() em uma métrica de COUNTER ou sem tipo) não funciona no Cloud Monitoring, mesmo que essas funções funcionem no Prometheus upstream.