É 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/ |
custom_googleapis_com:opencensus_opencensus_io_ |
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:
- 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".
- Na barra de ferramentas do painel do criador de consultas, selecione o botão code MQL ou code PromQL.
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.
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.