Algumas ou todas as informações nesta página podem não se aplicar à nuvem confiável da S3NS.

Esta página foi traduzida pela API Cloud Translation.

PromQL para Cloud Monitoring

Neste documento, descrevemos como configurar o Grafana para ler dados de métricas do Cloud Monitoring. Em seguida, use o PromQL para visualizar e criar gráficos de dados. O Grafana e o Cloud Monitoring são vinculados por um processo chamado sincronizador de fonte de dados, que permite a comunicação entre uma fonte de dados do Grafana e o Cloud Monitoring. O sincronizador de fonte de dados faz o seguinte:

Envia valores de configuração para uma fonte de dados do Grafana.
Mantém as credenciais de autenticação de uma conta de serviço Trusted Cloud by S3NS que pode ler dados de métricas do Cloud Monitoring.

Este documento descreve como configurar o sincronizador de fontes de dados e fornece informações específicas sobre o uso do PromQL no Cloud Monitoring. Neste documento, presumimos que você já conhece o Grafana.

Autorizar o Grafana a ler dados de métricas

Esta seção descreve como configurar a autorização entre o Cloud Monitoring e o Grafana usando um sincronizador de fonte de dados para gerar e sincronizar credenciais.

Usar o sincronizador de fonte de dados para autorização

Trusted Cloud by S3NS APIs exigem autenticação com OAuth2. No entanto, o Grafana não oferece suporte à autenticação OAuth2 para contas de serviço usadas com fontes de dados do Prometheus. Para usar o Grafana com o Cloud Monitoring, use o sincronizador de fonte de dados para gerar credenciais do OAuth2 para sua conta de serviço e sincronizá-las com o Grafana usando a API de fonte de dados do Grafana.

Você precisa usar o sincronizador de fontes de dados para configurar e autorizar o Grafana a consultar dados globalmente. Se você não seguir essas etapas, o Grafana só executará consultas nos dados do servidor local do Prometheus.

O sincronizador de fontes de dados é uma ferramenta de interface de linha de comando que envia valores de configuração remotamente para uma determinada fonte de dados do Grafana Prometheus. Isso garante que sua fonte de dados do Grafana tenha os seguintes itens configurados corretamente:

Autenticação, feita com a atualização periódica de um token de acesso OAuth2
A API Cloud Monitoring definida como o URL do servidor do Prometheus
O método HTTP definido como GET
O tipo e a versão do Prometheus definidos como 2.40.x, no mínimo
Os valores de tempo limite de HTTP e de consulta definidos como 2 minutos

O sincronizador de fonte de dados precisa ser executado repetidamente. Como os tokens de acesso da APITrusted Cloud by S3NS têm um ciclo de vida de uma hora, executar o sincronizador da fonte de dados a cada 10 minutos garante uma conexão autenticada ininterrupta entre o Grafana e a API Cloud Monitoring.

Configurar e autenticar a fonte de dados do Grafana

É possível usar o Grafana para consultar dados de métricas do Cloud Monitoring de serviços do Google Kubernetes Engine ou outros ambientes. As instruções usam variáveis editáveis para criar comandos executáveis. Recomendamos usar as variáveis editáveis e os ícones clicáveis de copiar e colar incorporados nos exemplos de código.

GKE

Para implantar e executar o sincronizador de fonte de dados em um cluster do Kubernetes, faça o seguinte:

Escolha um projeto, um cluster e um namespace para implantar o sincronizador de fontes de dados.
Em seguida, configure e autorize corretamente o sincronizador da fonte de dados:
- Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE, siga as instruções para criar e autorizar uma conta de serviço. Vincule-a ao namespace do Kubernetes em que você quer executar o sincronizador da fonte de dados.
- Se você não estiver usando a Federação de Identidade da Carga de Trabalho para GKE, verifique se não modificou a conta de serviço padrão do Compute Engine.
Determine o URL da instância do Grafana. Por exemplo, https://yourcompanyname.grafana.net para uma implantação do Grafana Cloud ou http://grafana.NAMESPACE_NAME.svc:3000 para uma instância local configurada usando o YAML da implantação de teste.

Se você implantar o Grafana localmente e o cluster estiver configurado para proteger todo o tráfego no cluster usando TLS, use https:// no URL e faça a autenticação usando uma das opções de autenticação TLS aceitas.
Escolha a fonte de dados do Grafana Prometheus que você quer usar no Cloud Monitoring, que pode ser nova ou preexistente. Em seguida, encontre e anote o UID da fonte de dados. O UID da fonte de dados pode ser encontrado na última parte do URL ao explorar ou configurar uma fonte de dados. Por exemplo: https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. Não copie o URL inteiro da fonte de dados. Copie apenas o identificador exclusivo no URL.
Configure uma conta de serviço do Grafana. Para isso, crie a conta de serviço e gere um token para ela usar:
1. Na barra lateral de navegação do Grafana, clique em Administração > Usuários e acesso > Contas de serviço.
2. Crie a conta de serviço clicando em Adicionar conta de serviço, fornecendo um nome e concedendo o papel de "Administrador" no Grafana. Se a sua versão do Grafana permitir permissões mais granulares, use a função Fontes de dados > Gravador.
3. Clique em Adicionar token da conta de serviço.
4. Defina a expiração do token como "Sem expiração" e clique em Gerar token. Em seguida, copie o token gerado para a área de transferência para usar como GRAFANA_SERVICE_ACCOUNT_TOKEN na próxima etapa.

Configure as variáveis de ambiente a seguir usando os resultados das etapas anteriores:

# These values are required.
PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.
GCM_ENDPOINT_OVERRIDE=--gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

Execute o comando a seguir para criar um CronJob que atualiza a fonte de dados na inicialização e a cada 10 minutos. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE, o valor de NAMESPACE_NAME precisará ser o mesmo namespace que você vinculou anteriormente à conta de serviço.

curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' s|$GCM_ENDPOINT_OVERRIDE|'"$GCM_ENDPOINT_OVERRIDE"'|; \
| kubectl -n NAMESPACE_NAME apply -f -

Acesse a fonte de dados do Grafana recém-configurada e verifique se o valor do URL do servidor Prometheus começa com https://monitoring.s3nsapis.fr. Talvez seja necessário atualizar a página. Após a verificação, acesse a parte inferior da página e selecione Salvar e testar. Você precisa selecionar esse botão pelo menos uma vez para garantir que o preenchimento automático de rótulos no Grafana funcione.

Verificar as credenciais da conta de serviço

Se o cluster do Kubernetes tiver a federação de identidade da carga de trabalho para GKE ativada, pule esta seção.

Quando executado no GKE, o Cloud Monitoring recupera automaticamente as credenciais do ambiente com base na conta de serviço padrão do Compute Engine. A conta de serviço padrão tem as permissões necessárias, monitoring.metricWriter e monitoring.viewer, por padrão. Se você não usar a federação de identidade da carga de trabalho para o GKE e tiver removido qualquer um desses papéis da conta de serviço do nó padrão, será necessário adicionar novamente essas permissões que faltam antes de continuar.

Configurar uma conta de serviço para a Federação de Identidade da Carga de Trabalho para GKE

Se o cluster do Kubernetes não tiver a federação de identidade da carga de trabalho para GKE ativada, pule esta seção.

O Cloud Monitoring captura dados de métricas usando a API Cloud Monitoring. Se o cluster estiver usando a federação de identidade da carga de trabalho para o GKE, você precisa conceder permissão à conta de serviço do Kubernetes para a API Monitoring. Esta seção descreve:

Como criar uma Trusted Cloud by S3NS conta de serviço dedicada, SERVICE_ACCT_NAME.
Vincular a conta de serviço Trusted Cloud à conta de serviço padrão do Kubernetes em um namespace de teste, NAMESPACE_NAME.
Como conceder a permissão necessária à conta de serviço Trusted Cloud .

Criar e vincular a conta de serviço

Essa etapa aparece em vários lugares na documentação do Cloud Monitoring. Se você já realizou esta etapa como parte de uma tarefa anterior, não é necessário repeti-la. Pule para Autorizar a conta de serviço.

A sequência de comandos a seguir cria a conta de serviço SERVICE_ACCT_NAME e a vincula à conta de serviço padrão do Kubernetes no namespace NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create SERVICE_ACCT_NAME \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com

Se você estiver usando um namespace ou uma conta de serviço diferente do GKE, ajuste os comandos adequadamente.

Autorizar a conta de serviço

Grupos de permissões relacionadas são coletados em papéis, e você concede os papéis a um principal, neste exemplo, a conta de serviço Trusted Cloud. Para mais informações sobre os papéis do Monitoring, consulte Controle de acesso.

O comando a seguir concede à conta de serviço Trusted Cloud , SERVICE_ACCT_NAME, os papéis da API Monitoring necessários para ler dados de métricas.

Se você já concedeu à conta de serviço do Trusted Cloud um papel específico como parte da tarefa anterior, não é necessário fazer isso novamente.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

Depurar a configuração da federação de identidade da carga de trabalho para o GKE

Se você estiver com problemas para fazer a federação de identidade da carga de trabalho para o GKE funcionar, consulte a documentação para verificar a configuração da federação de identidade da carga de trabalho para o GKE e o Guia de solução de problemas da federação de identidade da carga de trabalho para o GKE.

Como erros de digitação e cópias e colagens incompletas são as fontes mais comuns de erros ao configurar a Federação de identidade da carga de trabalho para o GKE, é altamente recomendável usar as variáveis editáveis e os ícones clicáveis de copiar/colar incorporados nos exemplos de código nestas instruções.

Federação de identidade da carga de trabalho para o GKE em ambientes de produção

O exemplo descrito neste documento vincula a conta de serviço Trusted Cloud à conta de serviço padrão do Kubernetes e concede à conta de serviço Trusted Cloudtodas as permissões necessárias para usar a API Monitoring.

Em um ambiente de produção, convém usar uma abordagem mais refinada, com uma conta de serviço para cada componente, cada uma com permissões mínimas. Para mais informações sobre como configurar contas de serviço para gerenciamento de identidades de carga de trabalho, consulte Como usar a Federação de identidade da carga de trabalho para o GKE.

Em outro lugar

Para implantar e executar o sincronizador de fonte de dados em ambientes diferentes do Google Kubernetes Engine, faça o seguinte:

Configure uma conta de serviço para o sincronizador de fonte de dados usar:

Defina o projeto padrão para os comandos gcloud:
```
gcloud config set project PROJECT_ID
```
Crie uma conta de serviço para o sincronizador de fonte de dados usar:
```
gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME
```

Conceda permissão à conta de serviço para ler dados de métricas:

 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
 --role=roles/monitoring.viewer \
 && \
 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
 --role=roles/iam.serviceAccountTokenCreator

Crie uma chave para a conta de serviço:
```
gcloud iam service-accounts keys create DS_SYNCER_SVCACCT_KEYFILE_NAME.json \
--iam-account DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com
```
O caminho para esse diretório é usado para definir uma variável de ambiente em uma etapa posterior. Para receber o caminho, execute o comando pwd e registre o valor:
```
pwd
DS_SYNCER_SVCACCT_KEYFILE_DIR
```

Determine o URL da instância do Grafana. Por exemplo, https://yourcompanyname.grafana.net para uma implantação do Grafana Cloud ou https://localhost:3000 para uma instância de teste local. Esse valor é usado no comando para executar o sincronizador de fontes de dados.

Se você implantar o Grafana localmente para um cluster do Kubernetes configurado para proteger todo o tráfego no cluster usando TLS, use https:// no URL e, na próxima etapa, faça a autenticação usando uma das opções de autenticação TLS aceitas.
No Grafana, adicione uma fonte de dados do Prometheus para usar no Cloud Monitoring e registre o UID da fonte de dados:
1. Clique em Conexões > Origens de dados > Adicionar uma nova origem de dados. Selecione Prometheus na lista de bancos de dados de série temporal.
2. No campo URL do servidor do Prometheus, insira o seguinte valor:
```
https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
```
3. Clique em Salvar e testar.
  
  O URL no navegador da página da fonte de dados contém a interface do usuário da fonte de dados, por exemplo, https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID..
4. Registre o UID da fonte de dados. Esse valor é usado no comando para executar o sincronizador de fontes de dados. Não copie o URL completo da fonte de dados. Copie apenas o identificador exclusivo no URL, que é um valor como ee0z3woqjah34e:
```
GRAFANA_DATASOURCE_UID
```
Configure uma conta de serviço do Grafana. Para isso, crie a conta de serviço e gere um token para ela usar:
1. Na barra lateral de navegação do Grafana, clique em Administração > Usuários e acesso > Contas de serviço.
2. Crie a conta de serviço clicando em Adicionar conta de serviço, fornecendo um nome e concedendo o papel de "Administrador" no Grafana.
3. Clique em Adicionar token da conta de serviço.
4. Defina a expiração do token como "Sem expiração" e clique em Gerar token. Em seguida, copie o token gerado para a seguinte variável editável. Esse valor é usado no comando para executar o sincronizador de fontes de dados.
```
GRAFANA_SERVICE_ACCOUNT_TOKEN
```
Execute o sincronizador de fonte de dados. É possível executar o sincronizador de uma imagem de contêiner pré-criada usando o Docker ou criar o código da fonte e executá-lo manualmente. O sincronizador da fonte de dados é um aplicativo Go. Portanto, você precisa ter o Go instalado para criar o sincronizador da origem.
Docker

Execute o sincronizador de fonte de dados do Docker usando a imagem de contêiner gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0. Para testes, execute o sincronizador manualmente. Depois de verificar se a conexão está funcionando, use um mecanismo automatizado, como um cron job, para executar o sincronizador da fonte de dados a cada 10 minutos. Isso garante que a conexão não seja interrompida, já que os tokens de acesso têm uma vida útil de uma hora.

Use o seguinte comando do Docker para executar o sincronizador de fonte de dados:
```
docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/DS_SYNCER_SVCACCT_KEYFILE_NAME.json" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0
-datasource-uids=UID_OF_GRAFANA_DATASOURCE
-grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
-grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
-project-id=PROJECT_ID
-query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
-gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
```
Para criar um job cron que execute o sincronizador de fonte de dados, faça o seguinte:
1. Edite a tabela cron:
  cron -e
2. Adicione uma entrada que execute o comando anterior a cada 10 minutos:
  */10 * * * * * docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/<KEY_ID>" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
Para mais informações sobre as opções de linha de comando disponíveis ao executar o sincronizador de fonte de dados, consulte o documento README.
Código-fonte
1. Para criar o sincronizador de fonte de dados por conta própria, faça o seguinte:
  1. Crie um diretório para conter o código e mude para ele:
    
    mkdir data-source-syncer-code cd data-source-syncer-code
    
    O caminho para esse diretório é usado para definir uma variável de ambiente em uma etapa posterior. Para receber o caminho, execute o comando pwd e grave-o na variável editável:
    
    pwd PATH_TO_LOCAL_REPO_COPY
  2. Clone o código da versão atual do repositório:
    
    git clone -b 'v0.15.3' --single-branch https://github.com/GoogleCloudPlatform/prometheus-engine
  3. Acesse o diretório datasource-syncer e crie o código:
    
    cd prometheus-engine/cmd/datasource-syncer go build main.go
2. Execute o sincronizador de fonte de dados. Para testes, execute o sincronizador manualmente. Depois de verificar se a conexão está funcionando, use um mecanismo automatizado, como um job cron, para executar o sincronizador da fonte de dados a cada 10 minutos e garantir que a conexão não seja interrompida, já que os tokens de acesso têm um ciclo de vida de uma hora.
  
  Use o comando a seguir para executar o sincronizador de fonte de dados manualmente:
  main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  Para criar um job cron que execute o sincronizador de fonte de dados, faça o seguinte:
  1. Edite a tabela cron:
    
    cron -e
  2. Adicione uma entrada que execute o comando anterior a cada 10 minutos:
    
    */10 * * * * * main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
  Para mais informações sobre as opções de linha de comando disponíveis ao executar o sincronizador de fonte de dados, consulte o documento README.
Acesse a fonte de dados do Grafana recém-configurada e verifique se o valor do URL do servidor Prometheus começa com https://monitoring.s3nsapis.fr. Talvez seja necessário atualizar a página. Após a verificação, acesse a parte de baixo da página e clique em Salvar e testar. Você precisa clicar nesse botão pelo menos uma vez para garantir que o preenchimento automático de rótulos no Grafana funcione.

Conferir métricas no Grafana

Para conferir as métricas do seu projeto Trusted Cloud no Grafana, faça o seguinte:

Clique em Análise no painel de navegação ou na página Fontes de dados.
No campo Métrica, use o menu suspenso para selecionar uma métrica. Também é possível selecionar Metrics Explorer para pesquisar métricas específicas. Se a métrica estiver associada a mais de um recurso monitorado, adicione um filtro de rótulo monitored_resource à consulta e selecione um tipo de recurso.
Adicione mais filtros de rótulo e operações para criar sua consulta.

Para informações sobre como criar visualizações e painéis no Grafana, consulte Painéis e visualizações.

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.

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.

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, são associadas a mais de um tipo de recurso.

Consulte a lista de métricas doTrusted Cloud by S3NS para conferir quais tipos de recursos monitorados são associados a uma métrica. 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.

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"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

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
`compute.googleapis.com/instance/cpu/utilization`	`compute_googleapis_com:instance_cpu_utilization`
`logging.googleapis.com/log_entry_count`	`logging_googleapis_com:log_entry_count`

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.

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.