Métricas do PromQL para Cloud Monitoring

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

É possível usar a linguagem de consulta do Prometheus (PromQL) para consultar todas as métricas no Cloud Monitoring, incluindo métricas do sistema do Google Cloud, métricas do Kubernetes, métricas personalizadas e métricas baseadas em registros.

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

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 só é compatível com os caracteres especiais : e _, primeiro é necessário tornar os nomes das métricas do Monitoring compatíveis com o PromQL. Para mapear nomes de métricas do Monitoring para PromQL, aplique as seguintes regras:

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

A tabela abaixo lista alguns nomes de métricas e os equivalentes do PromQL:

Nome da métrica do Cloud Monitoring Nome da métrica do PromQL
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 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 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

Como especificar um tipo de recurso monitorado

Quando uma métrica é 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.

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.
  • Acesse a guia Configuração do Metrics Explorer do Cloud Monitoring e digite o nome da métrica. Uma lista de tipos de recursos válidos é exibida. Por exemplo, "Instância de VM". Se você selecionar a métrica e acessar a guia MQL, verá o tipo de recurso monitorado subjacente no campo fetch, por exemplo, gce_instance. A guia MQL é útil para métricas que podem ser associadas a muitos tipos de recursos monitorados, por exemplo, 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 Serviço gerenciado do Prometheus.

Se você não usar o rótulo monitored_resource quando ele for necessário, receberá 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

Como usar rótulos de metadados

É 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)

O único caractere especial que pode ser usado nas chaves de rótulos de metadados é o _. A agregação usando rótulos de metadados com o tipo MULTI_STRING ou KEY_VALUE não é compatível.

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 logging.googleapis.com/user/widget_count.

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

  • Para filtrar o valor do rótulo da métrica, use
    logging_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Temas adicionais

Regras e alertas

É possível usar as métricas do Cloud Monitoring nas regras de gravação e alerta no serviço gerenciado para Prometheus. Para instruçõ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. Veja alguns links úteis:

Diferenças de PromQL

O PromQL para serviço gerenciado para Prometheus pode funcionar de maneira um pouco diferente do PromQL upstream. Para ver uma lista dessas diferenças, consulte Diferenças de PromQL.