Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance by S3NS. Consulte o artigo Diferenças em relação ao Google Cloud para mais detalhes.

Esta página foi traduzida pela API Cloud Translation.

PromQL para o Cloud Monitoring

Este documento descreve como configurar o Grafana para ler dados de métricas do Cloud Monitoring. Em seguida, pode usar o PromQL para visualizar e criar gráficos de dados. O Grafana e o Cloud Monitoring estão associados através de um processo denominado sincronizador de origens de dados, que permite a comunicação entre uma origem de dados do Grafana e o Cloud Monitoring. O sincronizador da origem de dados faz o seguinte:

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

Este documento descreve como configurar o sincronizador de origens de dados e fornece informações específicas sobre a utilização do PromQL no Cloud Monitoring. Este documento pressupõe que já conhece o Grafana.

Autorize o Grafana a ler dados de métricas

Esta secção descreve como configurar a autorização entre o Cloud Monitoring e o Grafana através de um sincronizador de origens de dados para gerar e sincronizar credenciais.

Use o sincronizador de origens de dados para autorização

Cloud de Confiance by S3NS Todas as APIs requerem autenticação através do OAuth2. No entanto, o Grafana não suporta a autenticação OAuth2 para contas de serviço usadas com origens de dados do Prometheus. Para usar o Grafana com o Cloud Monitoring, usa o sincronizador de origens de dados para gerar credenciais OAuth2 para a sua conta de serviço e sincronizá-las com o Grafana através da API de origens de dados do Grafana.

Tem de usar o sincronizador de origens de dados para configurar e autorizar o Grafana a consultar dados globalmente. Se não seguir estes passos, o Grafana só executa consultas em relação aos dados no servidor Prometheus local.

O sincronizador de origens de dados é uma ferramenta de interface de linha de comandos que envia remotamente valores de configuração para uma determinada origem de dados do Grafana Prometheus. Isto garante que a sua origem de dados do Grafana tem o seguinte configurado corretamente:

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

O sincronizador de origens de dados tem de ser executado repetidamente. Como os tokens de acesso da conta de serviço têm um tempo de vida predefinido de uma hora, a execução do sincronizador da origem de dados a cada 10 minutos garante que tem uma ligação autenticada ininterrupta entre o Grafana e a API Cloud Monitoring.

Configure e autentique a origem de dados do Grafana

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

GKE

Para implementar e executar o sincronizador da origem de dados num cluster do Kubernetes, faça o seguinte:

Escolha um projeto, um cluster e um espaço de nomes para implementar o sincronizador de origens de dados.
Em seguida, certifique-se de que configura e autoriza corretamente o sincronizador da origem de dados:
- Se estiver a usar a Workload Identity Federation para o GKE, siga as instruções para criar e autorizar uma conta de serviço. Certifique-se de que o associa ao espaço de nomes do Kubernetes no qual quer executar o sincronizador da origem de dados.
- Se não estiver a usar a Workload Identity Federation para o GKE, verifique se não modificou a conta de serviço do Compute Engine predefinida.
Determine o URL da sua instância do Grafana, por exemplo, https://yourcompanyname.grafana.net para uma implementação do Grafana Cloud ou http://grafana.NAMESPACE_NAME.svc:3000 para uma instância local configurada usando o YAML de implementação de teste.

Se implementar o Grafana localmente e o cluster estiver configurado para proteger todo o tráfego no cluster através do TLS, tem de usar https:// no URL e autenticar-se através de uma das opções de autenticação TLS suportadas.
Escolha a origem de dados do Grafana Prometheus que quer usar para o Cloud Monitoring, que pode ser uma origem de dados nova ou pré-existente. Em seguida, encontre e anote o UID da origem de dados. Pode encontrar o UID da origem de dados na última parte do URL quando explora ou configura uma origem de dados, por exemplo, https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. Não copie o URL completo da origem de dados. Copie apenas o identificador exclusivo no URL.
Configure uma conta de serviço do Grafana criando a conta de serviço e gerando um token para a conta usar:
1. Na barra lateral de navegação do Grafana, clique em Administração > Utilizadores e acesso > Contas de serviço.
2. Crie a conta de serviço clicando em Adicionar conta de serviço, atribuindo-lhe um nome e concedendo-lhe a função "Administrador" no Grafana. Se a sua versão do Grafana permitir autorizações mais detalhadas, pode usar a função Origens de dados > Escritor.
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 utilização como GRAFANA_SERVICE_ACCOUNT_TOKEN no passo seguinte.

Configure as seguintes variáveis de ambiente com os resultados dos passos 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 seguinte comando para criar um CronJob que atualize a origem de dados na inicialização e, em seguida, a cada 10 minutos. Se estiver a usar a Workload Identity Federation para o GKE, o valor de NAMESPACE_NAME deve ser o mesmo espaço de nomes que associou 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 -

Aceda à origem de dados do Grafana recém-configurada e verifique se o valor do URL do servidor Prometheus começa por https://monitoring.s3nsapis.fr. Pode ter de atualizar a página. Após a validação, aceda à parte inferior da página e selecione Guardar e testar. Tem de selecionar este botão, pelo menos, uma vez para garantir que a funcionalidade de preenchimento automático de etiquetas no Grafana funciona.

Valide as credenciais da conta de serviço

Se o seu cluster do Kubernetes tiver a federação de identidade da carga de trabalho para o GKE ativada, pode ignorar esta secção.

Quando executado no GKE, o Cloud Monitoring obtém automaticamente as credenciais do ambiente com base na conta de serviço predefinida do Compute Engine. A conta de serviço predefinida tem as autorizações necessárias, monitoring.metricWriter e monitoring.viewer, por predefinição. Se não usar a Workload Identity Federation para o GKE e tiver removido anteriormente uma dessas funções da conta de serviço do nó predefinida, tem de readicionar essas autorizações em falta antes de continuar.

Configure uma conta de serviço para a federação de identidades da carga de trabalho para o GKE

Se o seu cluster do Kubernetes não tiver a Workload Identity Federation para o GKE ativada, pode ignorar esta secção.

O Cloud Monitoring captura dados de métricas através da API Cloud Monitoring. Se o seu cluster estiver a usar a Workload Identity Federation para o GKE, tem de conceder autorização à sua conta de serviço do Kubernetes à API Monitoring. Esta secção descreve o seguinte:

Criar uma Cloud de Confiance by S3NS conta de serviço> dedicada, SERVICE_ACCT_NAME.
Associar a Cloud de Confiance conta de serviço à conta de serviço do Kubernetes predefinida num espaço de nomes de testeNAMESPACE_NAME.
Conceder a autorização necessária à Cloud de Confiance conta de serviço.

Crie e associe a conta de serviço

Este passo aparece em vários locais na documentação do Cloud Monitoring. Se já realizou este passo como parte de uma tarefa anterior, não precisa de o repetir. Avance para a secção Autorize a conta de serviço.

Primeiro, crie uma conta de serviço, se ainda não o tiver feito:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create SERVICE_ACCT_NAME

Em seguida, use a seguinte sequência de comandos para associar a conta de serviçoSERVICE_ACCT_NAME à conta de serviço predefinida do Kubernetes no espaço de nomesNAMESPACE_NAME:

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

Se estiver a usar um espaço de nomes ou uma conta de serviço do GKE diferente, ajuste os comandos adequadamente.

Autorize a conta de serviço

Os grupos de autorizações relacionadas são recolhidos em funções e concede as funções a um principal, neste exemplo, a Cloud de Confiance conta de serviço. Para mais informações sobre as funções de monitorização, consulte o artigo Controlo de acesso.

O comando seguinte concede à Cloud de Confiance conta de serviçoSERVICE_ACCT_NAME as funções da Monitoring API de que precisa para ler dados de métricas.

Se já tiver concedido à Cloud de Confiance conta de serviço uma função específica como parte de uma tarefa anterior, não precisa de o fazer novamente.

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

Depure a configuração da federação de identidades de carga de trabalho para o GKE

Se estiver a ter problemas com o funcionamento da federação de identidade da carga de trabalho para o GKE, consulte a documentação para validar a configuração da federação de identidade da carga de trabalho para o GKE e o guia de resolução de problemas da federação de identidade da carga de trabalho para o GKE.

Uma vez que os erros ortográficos e as operações de copiar e colar parciais são as origens de erros mais comuns quando configura a Workload Identity Federation para o GKE, recomendamos vivamente que use as variáveis editáveis e os ícones de copiar e colar clicáveis incorporados nos exemplos de código nestas instruções.

Workload Identity Federation para o GKE em ambientes de produção

O exemplo descrito neste documento associa a conta de serviço à conta de serviço predefinida do Kubernetes e concede à conta de serviço todas as autorizações necessárias para usar a API Monitoring. Cloud de Confiance Cloud de Confiance

Num ambiente de produção, é recomendável usar uma abordagem mais detalhada, com uma conta de serviço para cada componente, cada uma com autorizações mínimas. Para mais informações sobre a configuração de contas de serviço para a gestão de identidades da carga de trabalho, consulte o artigo Usar a federação de identidades da carga de trabalho para o GKE.

Noutro lugar

Para implementar e executar o sincronizador de origens de dados em ambientes que não sejam o Google Kubernetes Engine, faça o seguinte:

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

Defina o projeto predefinido para comandos gcloud:
```
gcloud config set project PROJECT_ID
```
Crie uma conta de serviço para o sincronizador da origem de dados usar:
```
gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME
```

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

 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com \
 --role=roles/monitoring.viewer \
 && \
 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns.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.iam.gserviceaccount.com
```
O caminho para este diretório é usado para definir uma variável de ambiente num passo subsequente. Para obter o caminho, execute o comando pwd e registe o valor:
```
pwd
DS_SYNCER_SVCACCT_KEYFILE_DIR
```

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

Se implementar o Grafana localmente para um cluster do Kubernetes configurado para proteger todo o tráfego no cluster através do TLS, tem de usar https:// no seu URL e, no passo seguinte, autenticar-se através de uma das opções de autenticação TLS suportadas.
No Grafana, adicione uma origem de dados do Prometheus para usar na Cloud Monitoring e registe o UID da origem de dados:
1. Clique em Associações > Origens de dados > Adicionar uma nova origem de dados. Selecione Prometheus na lista de bases de dados de séries cronológicas.
2. No campo URL do servidor Prometheus, introduza o seguinte valor:
```
https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
```
3. Clique em Guardar e testar
  
  O URL no navegador para a página da origem de dados contém a IU da origem de dados, por exemplo, https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.
4. Registe o UID da origem de dados. Este valor é usado no comando para executar o sincronizador da origem de dados. Não copie o URL completo da origem 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 criando a conta de serviço e gerando um token para a conta de serviço usar:
1. Na barra lateral de navegação do Grafana, clique em Administração > Utilizadores e acesso > Contas de serviço.
2. Crie a conta de serviço clicando em Adicionar conta de serviço, atribuindo-lhe um nome e concedendo-lhe a função "Administrador" no Grafana.
3. Clique em Adicionar token da conta de serviço.
4. Defina a validade do token como "Sem validade", clique em Gerar token e, de seguida, copie o token gerado para a seguinte variável editável. Este valor é usado no comando para executar o sincronizador da origem de dados.
```
GRAFANA_SERVICE_ACCOUNT_TOKEN
```
Execute o sincronizador de origens de dados. Pode executar o sincronizador a partir de uma imagem de contentor pré-criada usando o Docker ou pode criar o código a partir da origem e executá-lo manualmente. O sincronizador de origens de dados é uma aplicação Go, pelo que tem de ter o Go instalado para criar o sincronizador a partir da origem.
Docker

Execute o sincronizador da origem de dados a partir do Docker através da imagem do contentor gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0. Para testar, pode executar o sincronizador manualmente. Depois de verificar que a ligação está a funcionar, uma vez que os tokens de acesso têm uma duração de uma hora, tem de usar um mecanismo automático, como uma tarefa cron, para executar o sincronizador da origem de dados a cada 10 minutos para garantir que a ligação não é interrompida.

Use o seguinte comando do Docker para executar o sincronizador de origens 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 uma tarefa cron para executar o sincronizador da origem 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 acerca das opções da linha de comandos disponíveis quando executa o sincronizador da origem de dados, consulte o documento README.
Código fonte
1. Para criar o sincronizador de origens de dados, faça o seguinte:
  1. Crie um diretório para conter o código e mude para esse diretório:
    
    mkdir data-source-syncer-code cd data-source-syncer-code
    
    O caminho para este diretório é usado para definir uma variável de ambiente num passo subsequente. Para obter o caminho, execute o comando pwd e registe-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. Aceda ao diretório datasource-syncer e crie o código:
    
    cd prometheus-engine/cmd/datasource-syncer go build main.go
2. Execute o sincronizador de origens de dados. Para testar, pode executar o sincronizador manualmente. Depois de verificar se a ligação está a funcionar, uma vez que os tokens de acesso têm uma duração de uma hora, tem de usar um mecanismo automático, como uma tarefa cron, para executar o sincronizador da origem de dados a cada 10 minutos para garantir que a ligação não é interrompida.
  
  Use o seguinte comando para executar o sincronizador de origens 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 uma tarefa cron para executar o sincronizador da origem 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 acerca das opções da linha de comandos disponíveis quando executa o sincronizador da origem de dados, consulte o documento README.
Aceda à origem de dados do Grafana recém-configurada e verifique se o valor do URL do servidor Prometheus começa com https://monitoring.s3nsapis.fr. Pode ter de atualizar a página. Após a validação, aceda à parte inferior da página e clique em Guardar e testar. Tem de clicar neste botão, pelo menos, uma vez para garantir que a conclusão automática de etiquetas no Grafana funciona.

Veja métricas no Grafana

Para ver as métricas do seu Cloud de Confiance projeto no Grafana, faça o seguinte:

Clique em Explorar no painel de navegação ou na página Origens de dados.
No campo Métrica, use o menu pendente para selecionar uma métrica. Também pode selecionar o Explorador de métricas para pesquisar métricas específicas. Se a métrica estiver associada a mais do que um recurso monitorizado, tem de adicionar um filtro de etiqueta monitored_resource à sua consulta e selecionar um tipo de recurso.
Adicione mais filtros de etiquetas e operações para criar a consulta.

Para obter informações sobre a criação de visualizações e painéis de controlo no Grafana, consulte Painéis e visualizações.

Consultar métricas do Cloud Monitoring através do PromQL

As métricas do Cloud Monitoring podem ser consultadas através da especificação UTF-8 para PromQL. Os nomes das métricas UTF-8 têm de estar entre aspas e ser movidos para dentro das chaves. Os nomes das etiquetas também têm de estar entre aspas se contiverem carateres incompatíveis com versões anteriores. Para a métrica do Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, as seguintes consultas 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 valores 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 os painéis de controlo criados antes da compatibilidade com UTF-8 consultam as métricas do Cloud Monitoring convertendo os respetivos nomes em equivalentes compatíveis com o PromQL antigo. Para mais informações sobre as regras de conversão do PromQL antigo, consulte o artigo Mapeamento de métricas do Cloud Monitoring para o PromQL antigo.

Aprender PromQL

Para saber o básico sobre a utilização do PromQL, recomendamos que consulte a documentação de código aberto. Os seguintes recursos podem ajudar a começar:

Especificar um tipo de recurso monitorizado

Quando uma métrica do Cloud Monitoring está associada apenas a um único tipo de recurso monitorizado do Cloud Monitoring, a consulta 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 mapeadas para mais do que um tipo de recurso.

Pode ver que tipos de recursos monitorizados são mapeados para uma métrica consultando a lista de Cloud de Confiance by S3NS métricas. Cada entrada na documentação apresenta os tipos de recursos monitorizados associados na primeira coluna de cada entrada abaixo do tipo. Se não forem indicados tipos de recursos monitorizados, a métrica pode ser associada a qualquer tipo.

Se uma métrica estiver associada a mais do que um tipo de recurso, tem de especificar o tipo de recurso na sua consulta PromQL. Existe uma etiqueta especial, monitored_resource, que pode usar para selecionar o tipo de recurso.

Os tipos de recursos monitorizados são, na maioria dos casos, uma string curta, como gce_instance, mas, ocasionalmente, aparecem como URIs completos, como monitoring.googleapis.com/MetricIngestionAttribution. As consultas PromQL bem formadas podem ter o seguinte aspeto:

logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Se não usar a etiqueta monitored_resource quando for necessário, recebe 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

Resolver conflitos de etiquetas

No Cloud Monitoring, as etiquetas podem pertencer à métrica ou ao recurso. Se uma etiqueta de métrica tiver o mesmo nome de chave que uma etiqueta de recurso, pode consultar especificamente a etiqueta de métrica adicionando o prefixo metric_ ao nome da chave da etiqueta na sua consulta.

Por exemplo, suponhamos que tem uma etiqueta de recurso e uma etiqueta de métrica com o nome pod_name na métrica example.googleapis.com/user/widget_count.

Para filtrar pelo valor da etiqueta de recurso, use
example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}
Para filtrar pelo valor da etiqueta 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 PromQL antigo

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). Uma vez que o PromQL antigo só suporta os carateres especiais : e _, tem de aplicar as seguintes regras para tornar os nomes das métricas do Monitoring compatíveis com o PromQL antigo:

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

A tabela seguinte apresenta alguns nomes de métricas e os respetivos equivalentes do PromQL antigo:

Nome da métrica do Cloud Monitoring	Nome da métrica PromQL antiga
`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 valores 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 PromQL antigos
`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 o Cloud Monitoring pode funcionar de forma ligeiramente diferente do PromQL a montante.

As consultas PromQL no Cloud Monitoring são parcialmente avaliadas no back-end Monarch através de uma linguagem de consulta interna, e existem algumas diferenças conhecidas nos resultados das consultas. Além das diferenças indicadas nesta secção, o PromQL no Cloud Monitoring está em paridade com o 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 suportadas.

Suporte de UTF-8

O PromQL para o Cloud Monitoring suporta consultas UTF-8.

Se o nome da métrica do Prometheus consistir apenas em carateres alfanuméricos mais os carateres _ ou :, e se as chaves de etiquetas consistirem apenas em carateres alfanuméricos mais o caráter _, pode consultar através da sintaxe tradicional do PromQL. Por exemplo, uma consulta válida pode ter o seguinte aspeto: job:my_metric:sum{label_key="label_value"}.

No entanto, se o nome da métrica do Prometheus usar carateres especiais, exceto os carateres _ ou :, ou se as chaves de etiqueta usarem carateres especiais, exceto o carater _, tem de criar a consulta de acordo com a especificação UTF-8 para PromQL.

Os nomes de métricas UTF-8 têm de estar entre aspas e ser movidos para as chavetas. Os nomes das etiquetas também têm de estar entre aspas se contiverem carateres incompatíveis com versões anteriores. Os seguintes exemplos de consultas válidas são todos 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"}

Correspondência nos nomes das métricas

Apenas é suportada a correspondência exata nos nomes das métricas. Tem de 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 motor de correspondência de expressões regulares na etiqueta __name__:

As configurações do adaptador do Prometheus usam frequentemente o operador =~ para fazer a correspondência com vários nomes de métricas. Para corrigir esta utilização, expanda a configuração para usar uma política separada para cada métrica e nomeie cada métrica explicitamente. Isto também impede que a escala automática seja feita acidentalmente em métricas inesperadas.
As expressões regulares são frequentemente usadas para representar graficamente várias métricas não dimensionais no mesmo gráfico. Por exemplo, se tiver uma métrica como cpu_servicename_usage, pode usar um caráter universal para representar graficamente todos os seus serviços em conjunto. A utilização de métricas não dimensionais como esta é uma prática explicitamente má no Cloud Monitoring, e esta prática leva a um desempenho de consulta extremamente fraco. Para corrigir esta utilização, mova toda a dimensionalidade para etiquetas de métricas em vez de incorporar dimensões no nome da métrica.
A consulta de várias métricas é frequentemente usada para ver que métricas estão disponíveis para consulta. Em alternativa, recomendamos que use a chamada /labels/__name__/values para descobrir métricas.

Desatualização

A obsolescência não é suportada no back-end do Monarch.

Cálculo de `irate`

Quando a janela retrospetiva da função irate é inferior ao tamanho do passo, aumentamos a janela para o tamanho do passo. O Monarch requer esta alteração para garantir que nenhum dos dados de entrada é completamente ignorado na saída. Esta diferença também se aplica aos cálculos de rate.

Cálculo de `rate` e `increase`

Quando a janela retrospetiva da função rate é inferior ao tamanho do passo, aumentamos a janela para o tamanho do passo. O Monarch requer esta alteração para garantir que nenhum dos dados de entrada é completamente ignorado na saída. Esta diferença também se aplica aos cálculos de irate.

Existem diferenças nos cálculos de interpolação e extrapolação. O Monarch usa um algoritmo de interpolação diferente do Prometheus, e esta diferença pode gerar resultados ligeiramente diferentes. Por exemplo, as amostras de contador do Monarch são armazenadas com um intervalo de tempo, em vez da indicação de tempo única que o Prometheus usa. Por conseguinte, as amostras de contador no Monarch podem ser incluídas num cálculo da taxa, mesmo que a data/hora do Prometheus as exclua. Geralmente, isto resulta em resultados de taxas mais precisos, especialmente quando consulta dados no início ou no fim da série cronológica subjacente.

Cálculo de `histogram_quantile`

Um cálculo de PromQL histogram_quantile num histograma sem amostras produz um valor NaN. O cálculo da linguagem de consulta interna não produz nenhum valor. Em alternativa, o ponto na data/hora é ignorado.

As diferenças de cálculo das tarifas também podem afetar a entrada de consultas histogram_quantile.

Funções específicas do tipo em métricas com tipos diferentes

Embora o Prometheus a montante seja fracamente tipado, o Monarch é fortemente tipado. Isto significa que a execução de funções específicas de um único tipo numa métrica de tipo diferente (por exemplo, a execução de rate() numa métrica GAUGE ou histogram_quantile() numa métrica COUNTER ou sem tipo) não funciona no Cloud Monitoring, embora estas funções funcionem no Prometheus a montante.