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

• 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  MQL.

  3. Verifique se MQL está selecionado na opção de ativar/desativar MQL. 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.