Consultar usando o Grafana

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 podem ser consultados, e como usar o Grafana para recuperar e usar os dados coletados.

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:

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:

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 \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

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.

Também é possível importar os painéis do Grafana para o Cloud Monitoring. Isso permite continuar usando os painéis do Grafana pessoais ou criados pela comunidade sem precisar configurar ou implantar uma instância do Grafana.

Grafana

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.

Implante o Grafana, se necessário

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/6ebc1afa8e609febe8d687bb7fa6bd2375e46db1/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.

Em seguida, adicione uma nova fonte de dados do Prometheus ao Grafana da seguinte maneira:

  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 Conexões no menu principal do Grafana e, em seguida, Fontes de dados.

    Como adicionar uma fonte de dados ao Grafana.

  3. Selecione Adicionar fonte de dados e selecione o Prometheus como o banco de dados de séries temporais.

    Como adicionar uma fonte de dados do Prometheus.

  4. Dê um nome à fonte de dados, defina o campo URL como http://localhost:9090 e selecione Salvar e testar. É possível ignorar os erros que dizem que a fonte de dados não está configurada corretamente.

  5. Copie o URL do serviço local para sua implantação, que será semelhante a este:

    http://grafana.NAMESPACE_NAME.svc:3000

Configurar e autenticar a fonte de dados do Grafana

Todas as APIs do Google Cloud 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 serviço gerenciado para Prometheus, use o sincronizador da fonte de dados para gerar credenciais do OAuth2 para sua conta de serviço e sincronizá-las com o Grafana usando o 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 usa um CronJob do Kubernetes para sincronizar 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 da fonte de dados usa a conta de serviço local do cluster para gerar periodicamente um token de acesso da API Google Cloud com as permissões do IAM necessárias para consultar dados do Cloud Monitoring. Como os tokens de acesso da API Google Cloud têm um ciclo de vida de uma hora, o sincronizador da fonte de dados é executado a cada 30 minutos para garantir que você tenha uma conexão autenticada ininterrupta entre o Grafana e a API Cloud Monitoring.

Para implantar e executar o sincronizador de fonte de dados, faça isto:

  1. Escolha um projeto, um cluster e um namespace para implantar o sincronizador de fontes de dados. Recomendamos a implantação do sincronizador da fonte de dados em um cluster pertencente ao projeto de um escopo de métricas de vários projetos. O sincronizador da fonte de dados usa o projeto do Google Cloud configurado como o projeto do escopo.

    Em seguida, configure e autorize corretamente o sincronizador da fonte de dados:

    Em seguida, verifique se é necessário autorizar o sincronizador da fonte de dados para consultas em vários projetos:

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

  3. Escolha a fonte de dados do Grafana Prometheus que você quer usar no Managed Service para Prometheus, 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.

    Localize um UID da fonte de dados no Grafana.

  4. 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 área de transferência para usar como GRAFANA_SERVICE_ACCOUNT_TOKEN na próxima etapa:

      Gere e salve um token de conta de serviço no Grafana.

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

  6. Execute o comando a seguir para criar um CronJob que atualiza a fonte de dados na inicialização e a cada 30 minutos. Se você estiver usando a Identidade da carga de trabalho, 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/main/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"'|;' \
| kubectl -n NAMESPACE_NAME apply -f -

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

Executar consultas usando o Grafana

Agora é possível criar painéis do Grafana e executar consultas usando a fonte de dados configurada. A captura de tela a seguir mostra um gráfico do Grafana que exibe a métrica up:

Gráfico do Grafana para a métrica do serviço gerenciado para Prometheus.

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.

Como executar o sincronizador de fonte de dados fora do GKE

É possível pular esta seção se estiver executando o sincronizador de fonte de dados 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 sincronizador de fonte de dados recupera automaticamente as credenciais 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 fornecidas explicitamente ao sincronizador de fonte de dados usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Defina o contexto para seu projeto de destino:

    gcloud config set project PROJECT_ID

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

  3. 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 \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

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

  5. Defina o caminho do arquivo de chave usando a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

Autorizar o sincronizador de fonte de dados a receber monitoramento de vários projetos

O Managed Service para Prometheus é compatível com o monitoramento de vários projetos usando escopos de métricas. Se o projeto local for o projeto de escopo e você tiver seguido as instruções para verificar ou configurar uma conta de serviço no projeto local, a consulta entre projetos funcionará sem configurações adicionais.

Se o projeto local não for o do escopo, é necessário autorizar que a conta de serviço padrão do Compute do projeto local ou a conta de serviço da Identidade da carga de trabalho tenha acesso monitoring.viewer ao projeto de escopo. Em seguida, transmita o ID do projeto do escopo como o valor da variável de ambiente PROJECT_ID.

Se você usa a conta de serviço default do Compute Engine, pode realizar uma das seguintes ações:

Para conceder a uma conta de serviço as permissões necessárias para acessar outro projeto do Google Cloud, faça o seguinte:

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

  2. Ao configurar o sincronizador da fonte de dados, transmita o ID do projeto do escopo como o valor da variável de ambiente PROJECT_ID.

Inspecionar o CronJob

Para inspecionar o CronJob e garantir que todas as variáveis estejam definidas corretamente, execute o seguinte comando:

kubectl describe cronjob datasource-syncer

Para ver os registros do job que configura inicialmente o Grafana, execute o seguinte comando logo após aplicar o arquivo datasource-syncer.yaml:

kubectl logs job.batch/datasource-syncer-init

Eliminação

Para desativar o Cronjob do sincronizador de fonte de dados, execute o seguinte comando:

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml

Desativar o sincronizador de fonte de dados interrompe a atualização do Grafana vinculado com credenciais de autenticação novas. Como consequência, a consulta do Managed Service para Prometheus não funcionará mais.

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.

A seguir