Consultar usando a API ou interface do Prometheus

Depois de implantar o Google Cloud Managed Service para Prometheus, você pode consultar os dados enviados ao serviço gerenciado e exibir os resultados em gráficos e painéis.

Neste documento, descrevemos os escopos de métricas, que determinam os dados que você pode consultar, e as seguintes maneiras de recuperar e usar os dados coletados baseadas no Prometheus:

A API Prometheus HTTP
A interface do Prometheus

Todas as interfaces de consulta do serviço gerenciado para o Prometheus são configuradas para recuperar dados do Monarch usando a API Cloud Monitoring. Ao consultar o Monarch em vez de consultar dados dos servidores locais do Prometheus, você tem o monitoramento global em escala.

Antes de começar

Se você ainda não implantou o serviço gerenciado, configure a coleção gerenciada ou a coleção autoimplantada. Pule isso se quiser apenas consultar métricas do Cloud Monitoring usando o PromQL.

Configurar o ambiente

Para evitar inserir repetidamente o ID do projeto ou o nome do cluster, execute a seguinte configuração:

Configure as ferramentas de linha de comando da seguinte maneira:
- Configure a CLI gcloud para se referir ao ID do projeto do Google Cloud:
```
gcloud config set project PROJECT_ID
```
- Configure a CLI kubectl para usar o cluster:
```
kubectl config set-cluster CLUSTER_NAME
```
Para mais informações sobre essas ferramentas, consulte estes recursos:
- Visão geral da CLI gcloud
- Comandos kubectl

Configurar um namespace

Crie o namespace NAMESPACE_NAME do Kubernetes para os recursos que você criar como parte do aplicativo de exemplo:

kubectl create ns NAMESPACE_NAME

Verificar as credenciais da conta de serviço

Pule essa seção se o cluster do Kubernetes tiver a Identidade da carga de trabalho ativada.

Quando executado no GKE, o Managed Service para Prometheus recuperará 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 Identidade da carga de trabalho 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.

Se você não estiver executando no GKE, consulte Fornecer credenciais explicitamente.

Configurar uma conta de serviço para a Identidade da carga de trabalho

Você poderá pular esta seção se o cluster do Kubernetes não tiver a Identidade da carga de trabalho ativada.

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

Como criar uma conta de serviço dedicada do Google Cloud, gmp-test-sa.
Vincular a conta de serviço do Google Cloud à conta de serviço do Kubernetes padrão em um namespace de teste, NAMESPACE_NAME.
Como conceder a permissão necessária à conta de serviço do Google Cloud.

Criar e vincular a conta de serviço

Essa etapa aparece em vários lugares na documentação do Managed Service para Prometheus. 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 gmp-test-sa 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 gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.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 do Google Cloud. Para mais informações sobre os papéis do Monitoring, consulte Controle de acesso.

O comando a seguir concede à conta de serviço do Google Cloud, gmp-test-sa, os papéis da API Monitoring necessários para ler dados de métricas.

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

Para autorizar a conta de serviço a ler um escopo de métricas de vários projetos, siga estas instruções e consulte alterar o projeto consultado.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer

Depurar a configuração da Identidade da carga de trabalho

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

Como erros de digitação e cópias e colagens incompletas são as fontes mais comuns de erros ao configurar a Identidade da carga de trabalho, é 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.

Identidade da carga de trabalho em ambientes de produção

O exemplo descrito neste documento vincula a conta de serviço do Google Cloud à conta de serviço padrão do Kubernetes e concede à conta de serviço do Google Cloud todas 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 Identidade da carga de trabalho.

Escopos de consultas e métricas

Os dados que você pode consultar são determinados pelo escopo de métricas da construção do Cloud Monitoring, independentemente do método usado para consultar os dados. Por exemplo, se você usar o Grafana para consultar dados gerenciados pelo serviço do Prometheus, cada escopo de métricas precisará ser configurado como uma fonte de dados separada.

Um escopo de métricas do Monitoring é uma construção somente leitura que permite consultar dados de métricas pertencentes a vários projetos do Google Cloud. Cada escopo de métricas é hospedado por um projeto do Google Cloud designado, chamado de projeto de escopo.

Por padrão, um projeto é o projeto de escopo para o próprio escopo de métricas, e o escopo das métricas contém as métricas e a configuração desse projeto. Um projeto de escopo pode ter mais de um projeto monitorado no escopo de métricas, e as métricas e configurações de todos os projetos monitorados no escopo de métricas são visíveis para o projeto de escopo. Um projeto monitorado também pode pertencer a mais de um escopo de métricas.

Quando você consulta as métricas em um projeto, e se ele hospeda um escopo de métricas de vários projetos, é possível recuperar dados de vários projetos. Se o escopo das métricas contiver todos os projetos, as consultas e regras serão avaliadas globalmente.

Para mais informações sobre escopos e projetos de escopo, consulte Escopos de métricas. Para informações sobre como configurar um escopo de métricas de vários projetos, consulte Visualizar métricas de vários projetos.

Serviço gerenciado para dados do Prometheus no Cloud Monitoring

A maneira mais simples de verificar se os dados do Prometheus estão sendo exportados é usar a página do Metrics Explorer do Cloud Monitoring no console do Google Cloud, compatível com PromQL. Para instruções, veja Como consultar usando PromQL no Cloud Monitoring.

Interface de front-end do Prometheus independente

É possível usar a interface de front-end do Prometheus para acessar e visualizar dados ingeridos. Essa interface executa consultas PromQL em todos os dados do projeto do Google Cloud, conforme determinado pelo escopo das métricas associadas ao projeto.

A interface também funciona como um proxy de autenticação para acessar dados ingeridos. Esse recurso pode ser usado para ferramentas de cliente que não são compatíveis com o OAuth2, incluindo o Grafana ou o escalonamento automático horizontal de pods usando a biblioteca prometheus-adapter.

É altamente recomendável configurar o Grafana para ver dados do Managed Service para Prometheus usando o sincronizador de fonte de dados. As instruções para configurar o Grafana usando a interface de front-end independente do Prometheus estão incluídas aqui como referência para usuários que já configuraram o Grafana usando esse método.

Implantar a interface de front-end

Para implantar a interface de front-end do Prometheus para o serviço gerenciado para o Prometheus, execute os seguintes comandos:

Implante o serviço frontend e configure-o para consultar o projeto de escopo do escopo de métricas de sua escolha:

curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/frontend.yaml |
sed 's/\$PROJECT_ID/PROJECT_ID/' |
kubectl apply -n NAMESPACE_NAME -f -

Encaminhe o serviço frontend para sua máquina local. O exemplo a seguir encaminha o serviço para a porta 9090:
```
kubectl -n NAMESPACE_NAME port-forward svc/frontend 9090
```
Esse comando não retorna e, enquanto está em execução, informa acessos ao URL.

Se você quiser continuar usando uma implantação do Grafana instalada pelo kube-prometheus, implante a interface do Prometheus no namespace monitoring.

É possível acessar a interface de front-end do Prometheus no navegador no URL http://localhost:9090. Se você estiver usando o Cloud Shell nesta etapa, poderá ter acesso usando o botão Visualização da Web.

A captura de tela a seguir mostra uma tabela na interface de front-end independente do Prometheus que exibe a métrica up:

Como visualizar uma métrica na interface do Prometheus.

Também é possível configurar a autenticação e autorização adequadas no serviço frontend usando, por exemplo, Identity-Aware Proxy. Para mais informações sobre como expor serviços, consulte Como expor aplicativos usando serviços.

Alterar o projeto consultado para receber monitoramento de vários projetos

A implantação frontend usa o projeto configurado do Google Cloud como o projeto de escopo. Se este for o projeto de escopo de um escopo de métricas de vários projetos, ele poderá ler métricas de todos os projetos no escopo de métricas.

É possível especificar um projeto com um escopo de métricas de vários projetos usando a sinalização --query.project-id.

Normalmente, um projeto dedicado é usado como projeto de escopo, e este projeto não é o mesmo em que a implantação frontend é executada. Para permitir que a implantação leia um projeto de destino diferente, faça o seguinte:

Informe à implementação de frontend qual é o projeto de destino.
Conceda permissão à conta de serviço para ler o projeto de destino. Se você estiver usando a conta de serviço default do Compute Engine, poderá seguir um destes procedimentos:
- Ative a identidade da carga de trabalho para o cluster e siga as etapas de configuração.
- Forneça uma chave de conta de serviço explícita.

Para conceder as permissões necessárias para acessar um projeto diferente do Google Cloud, faça o seguinte:

Conceda permissão à conta de serviço para ler o projeto de destino que você quer consultar:

gcloud projects add-iam-policy-binding SCOPING_PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer

Abra a implantação frontend criada anteriormente para edição:
```
kubectl -n NAMESPACE_NAME edit deploy frontend
```

Especifique o projeto de destino usando a sinalização --query.project-id:

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: frontend
spec:
  template
    containers:
    - name: frontend
      args:
      - --query.project-id=SCOPING_PROJECT_ID
...

Salve o arquivo e feche o editor. Depois que a alteração é aplicada, os pods de front-end são reiniciados e consultam o novo projeto de escopo.

Autenticar a interface de front-end

A implantação frontend oferece suporte à autenticação básica de acesso para acesso autenticado nas versões 0.5.0 e mais recentes. Para ativar a autenticação, adicione as variáveis de ambiente AUTH_USERNAME e AUTH_PASSWORD à implantação:

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: frontend
spec:
  template
    containers:
    - name: frontend
      env:
      - name: AUTH_USERNAME
        value: USERNAME
      - name: AUTH_PASSWORD
        value: PASSWORD
...

Fornecer credenciais explicitamente

É possível pular esta seção se você estiver executando o contêiner frontend em um cluster do Google Kubernetes Engine. Se você estiver com problemas de autenticação no GKE, consulte Verificar as credenciais da conta de serviço.

Durante a execução no GKE, o front-end recupera as credenciais automaticamente do ambiente com base na conta de serviço do nó ou na configuração da identidade da carga de trabalho. Em clusters do Kubernetes que não são do GKE, as credenciais precisam ser explicitamente fornecidas ao front-end usando sinalizações ou a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Defina o contexto para seu projeto de destino:
```
gcloud config set project PROJECT_ID
```
Crie uma conta de serviço:
```
gcloud iam service-accounts create gmp-test-sa
```
Nesta etapa, é criada a conta de serviço que você pode já tiver criado nas instruções de Identidade da carga de trabalho.

Conceda as permissões necessárias à conta de serviço:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer

Crie e faça o download de uma chave para a conta de serviço:

gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Adicione o arquivo de chave como secret ao cluster que não é do GKE:

kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
  --from-file=key.json=gmp-test-sa-key.json

Abra o recurso de implantação de front-end para edição:
```
kubectl -n NAMESPACE_NAME edit deploy frontend
```
1. Adicione o texto exibido em negrito ao recurso:
```
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: frontend
spec:
  template
    containers:
    - name: frontend
      args:
      - --query.credentials-file=/gmp/key.json
...
      volumeMounts:
      - name: gmp-sa
        mountPath: /gmp
        readOnly: true
...
    volumes:
    - name: gmp-sa
      secret:
        secretName: gmp-test-sa
...
```
2. Salve o arquivo e feche o editor. Depois que a alteração é aplicada, os pods são recriados e começam a autenticar no back-end da métrica com a conta de serviço especificada.
Como alternativa, em vez de usar as sinalizações definidas neste exemplo, defina o caminho do arquivo de chave usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
Como usar o Grafana pelo proxy de front-end

O serviço gerenciado para Prometheus usa a fonte de dados integrada do Prometheus para o Grafana, o que significa que você pode continuar usando os painéis pessoais ou criados pela comunidade do Grafana sem alterações. Também é possível importar os painéis do Grafana para o Cloud Monitoring.

Como autenticar nas APIs do Google Cloud

Aviso: é altamente recomendável configurar o Grafana para ver dados do Managed Service para Prometheus usando o sincronizador de fonte de dados. Estas instruções para configurar o Grafana usando a interface de front-end independente do Prometheus estão incluídas aqui como referência para usuários que já configuraram o Grafana usando esse método.

Todas as APIs do Google Cloud exigem autenticação usando OAuth2. No entanto, o Grafana não é compatível com a autenticação OAuth2 para fontes de dados do Prometheus. Para usar o Grafana com o Managed Service para Prometheus, use a interface de front-end independente do Prometheus como proxy de autenticação.

Você precisa apontar o Grafana no proxy de interface de front-end autônomo para consultar os dados globalmente. Se você não seguir essas etapas, o Grafana só executará consultas nos dados do servidor local do Prometheus.

Se você ainda não tiver implantado o serviço da interface Prometheus frontend como um proxy, implante-o agora executando o seguinte comando:
```
curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/frontend.yaml |
sed 's/\$PROJECT_ID/PROJECT_ID/' |
kubectl apply -n NAMESPACE_NAME -f -
```
Para clusters do Kubernetes que não são do GKE, como clusters do Anthos, consulte também Fornecer credenciais explicitamente para conceder ao serviço frontend as permissões necessárias para consultar métricas.

Consulte alterar o projeto consultado para saber como configurar o escopo de métricas usado pelo serviço frontend para consultar vários projetos.

Se você tiver uma implantação do Grafana, como uma instalada pela biblioteca kube-prometheus ou uma instalada com um gráfico de helm, poderá continuar usando-a com o serviço gerenciado para Prometheus. Nesse caso, consulte Configurar uma fonte de dados para ver as próximas etapas. Caso contrário, primeiro implante o Grafana.

Implante o Grafana

Se você não tiver uma implantação do Grafana em execução no cluster, será possível criar uma implantação de teste temporária para fazer experimentos.

Para criar uma implantação temporária do Grafana, aplique o manifesto grafana.yaml do serviço gerenciado para o Prometheus ao cluster e encaminhe o serviço grafana para a máquina local. O exemplo a seguir encaminha o serviço para a porta 3000.
1. Aplique o manifesto grafana.yaml:
```
kubectl -n NAMESPACE_NAME apply -f  https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/beb779d32f4dd531a3faad9f2916617b8d9baefd/examples/grafana.yaml
```
2. Encaminhe o serviço grafana para sua máquina local. Este exemplo encaminha o serviço para a porta 3000:
```
kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000
```
  Esse comando não retorna e, enquanto está em execução, informa acessos ao URL.
  
  É possível acessar o Grafana no navegador, no URL http://localhost:3000, com o username:password admin:admin.
Configure uma fonte de dados

Para consultar o Managed Service para Prometheus no Grafana usando a interface do Prometheus como proxy de autenticação, é preciso adicionar uma nova fonte de dados ao Grafana. Para adicionar uma fonte de dados ao serviço gerenciado, faça o seguinte:
1. Acesse sua implantação do Grafana, por exemplo, navegando até o URL http://localhost:3000 para acessar a página de boas-vindas do Grafana.
2. Selecione Configuração no menu principal do Grafana e selecione Fontes de dados.
3. Selecione Adicionar fonte de dados e selecione o Prometheus como o banco de dados de séries temporais.
4. No campo URL do painel HTTP, insira o URL do serviço gerenciado para o Prometheus frontend. Se você configurou a interface do Prometheus para ser executada na porta 9090, o URL de serviço desse campo será http://frontend.NAMESPACE_NAME.svc:9090.
  
  No campo Tempo limite do painel HTTP, defina o valor como 120.
  
  Se você tiver configurado a interface de front-end com a autenticação básica, ative a chave Autenticação básica no painel Autenticação e preencha o nome de usuário e a senha.
  
  No campo Tempo limite da consulta, defina o valor como 2m.
  
  No campo Método HTTP, selecione GET.
  
  No campo Prometheus type, selecione Prometheus.
  
  No campo Versão do Prometheus, selecione 2.40.x ou uma versão mais recente.
  
  Se você tiver várias fontes de dados do Prometheus, poderá dar a ela um nome como "Serviço gerenciado do Prometheus". Não altere os valores padrão dos outros campos.
5. Clique em Salvar e testar e procure a mensagem "A fonte de dados está funcionando".
Observação: também é possível implantar o contêiner frontend como um arquivo secundário no pod do Grafana e acessar a fonte de dados no URL http://localhost:9090.

Usar a nova fonte de dados

Agora é possível criar painéis do Grafana usando a nova fonte de dados. Também é possível redirecionar painéis existentes para a nova fonte de dados. A captura de tela a seguir mostra um gráfico do Grafana que exibe a métrica up:

Como conectar o Managed Service para Prometheus ao Thanos

É possível federar o Managed Service para Prometheus em uma pilha Thanos autoimplantada usando o thanos-promql-connector de código aberto. O Google Cloud não oferece suporte para essa integração.

API Prometheus HTTP

O serviço gerenciado para o Prometheus é compatível com a API Prometheus HTTP do upstream no URL prefixado por https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/. Para informações sobre os endpoints compatíveis, consulte Compatibilidade da API.

Essa API pode ser acessada por qualquer ferramenta que interaja com um servidor Prometheus padrão. Esse é apenas um endpoint da API. ele não exibe uma IU. Como uma API do Google Cloud, a API usa a autenticação OAuth2 e, como parte da API Cloud Monitoring, o valor de PROJECT_ID é o projeto de escopo de um escopo de métricas. Assim, é possível recuperar dados de qualquer projeto no escopo das métricas. Para mais informações sobre o escopo, consulte Escopos de métricas.

Para usar esse endpoint, forneça uma expressão PromQL. Por exemplo, a consulta instantânea a seguir recupera todas as séries temporais que têm o nome da métrica up:
```
curl https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/query \
  -d "query=up" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"
```
Se a solicitação for bem-sucedida, a consulta retornará um resultado como o seguinte, que foi formatado para legibilidade:
```
{
  "status":"success",
  "data":{
    "resultType":"vector",
    "result":[{
      "metric": {
        "__name__":"up",
        "cluster":"gmp-test",
        "instance":"prom-example-84c6f547f5-g4ljn:web",
        "job":"prometheus",
        "location":"us-central1-a",
        "project_id":"a-gcp-project"
      },
      "value": [1634873239.971,"1"]
    }]
  }
}
```
Para mais informações sobre como consultar as métricas do sistema do Google Cloud usando o PromQL, consulte PromQL para métricas do Cloud Monitoring.

Compatibilidade de API

Os endpoints da API Prometheus HTTP a seguir são compatíveis com o serviço gerenciado para o Prometheus com o URL prefixado por https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/.

Para ter acesso à documentação completa, consulte a documentação de referência da API Cloud Monitoring.

Para ver informações sobre a compatibilidade com o PromQL, consulte Compatibilidade com o PromQL (em inglês).
- Os endpoints a seguir são totalmente compatíveis:
  - /api/v1/query
  - /api/v1/query_range
  - /api/v1/metadata
  - /api/v1/labels
  - /api/v1/query_exemplars
- O endpoint /api/v1/label/<label_name>/values só funciona se o rótulo __name__ for fornecido usando-o como o valor <label_name> ou correspondendo exatamente a ele usando um seletor de série. Por exemplo, as seguintes chamadas são totalmente compatíveis:
  - /api/v1/label/__name__/values
  - /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
  - /api/v1/label/labelname/values?match[]={__name__="metricname"}
  Essa limitação causa falhas nas consultas de variáveis label_values($label) no Grafana. Em vez disso, use label_values($metric, $label). Esse tipo de consulta é recomendado porque evita buscar valores de rótulos em métricas que não são relevantes para o painel fornecido.
- O endpoint /api/v1/series é compatível com solicitações GET, mas não POST. Quando você usa o sincronizador de fonte de dados ou o proxy de front-end, essa restrição é gerenciada para você. Também é possível configurar as fontes de dados do Prometheus no Grafana para que emitam apenas solicitações GET.