Como usar o PromQL para as métricas do Cloud Monitoring

É 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 _.

Confira na tabela a seguir alguns nomes de métricas e os equivalentes em 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 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 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 associadas a mais de um tipo de recurso. As métricas

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  MQL ou  PromQL.

  3. Verifique se MQL está selecionado na opção de ativar/desativar Idioma. A alternância de idiomas está na mesma barra de ferramentas que permite formatar sua consulta.

     A consulta exibida mostra o tipo de recurso. Especificamente, a MQL é ú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 Serviço gerenciado do Prometheus.

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 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 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"}

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.

Observação: é possível criar políticas de alertas do Cloud Monitoring com base em consultas PromQL e regras de alerta do Prometheus. Para mais informações, consulte Políticas de alertas com o PromQL.

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:

• Como consultar o Prometheus
• Exemplos de consultas
• Folha de referência do PromQL

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.