Consulte através da API ou da IU do Prometheus

Depois de implementar o serviço gerido do Google Cloud para o Prometheus, pode consultar os dados enviados para o serviço gerido e apresentar os resultados em gráficos e painéis de controlo.

Este documento descreve os âmbitos das métricas, que determinam os dados que pode consultar, e as seguintes formas baseadas no Prometheus de obter e usar os dados que recolheu:

  • A API HTTP do Prometheus
  • A IU do Prometheus

Todas as interfaces de consulta do serviço gerido para Prometheus estão configuradas para obter dados do Monarch através da Cloud Monitoring API. Ao consultar o Monarch em vez de consultar dados de servidores Prometheus locais, recebe monitorização global em grande escala.

Antes de começar

Se ainda não implementou o serviço gerido, configure a recolha gerida ou a recolha autodeployada. Pode ignorar este passo se só tiver interesse em consultar métricas do Cloud Monitoring através do PromQL.

Configure o seu ambiente

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

  • Configure as ferramentas de linha de comandos da seguinte forma:

    • Configure a CLI gcloud para fazer referência ao ID do seu Google Cloud projeto:

      gcloud config set project PROJECT_ID

    • Configure a CLI kubectl para usar o seu cluster:

      kubectl config set-cluster CLUSTER_NAME

    Para mais informações sobre estas ferramentas, consulte o seguinte:

Configure um espaço de nomes

Crie o espaço de nomes do Kubernetes NAMESPACE_NAME para os recursos que criar como parte da aplicação de exemplo:

kubectl create ns NAMESPACE_NAME

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 Managed Service for Prometheus 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 Managed Service for Prometheus 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 para a API Monitoring. Esta secção descreve o seguinte:

Crie e associe a conta de serviço

Este passo aparece em vários locais na documentação do Managed Service for Prometheus. 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.

A seguinte sequência de comandos cria a conta de serviço gmp-test-sa e associa-a à conta de serviço Kubernetes predefinida no espaço de nomes 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 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 Google Cloud 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 à Google Cloud conta de serviçogmp-test-sa as funções da Monitoring API de que precisa para ler dados de métricas.

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

Para autorizar a sua conta de serviço a ler a partir de um âmbito de métricas de vários projetos, siga estas instruções e, em seguida, consulte Altere 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

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

Se tiver problemas com a 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 mais comuns de erros ao configurar 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. Google Cloud Google Cloud

Num ambiente de produção, pode querer 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.

Âmbitos das consultas e métricas

Os dados que pode consultar são determinados pela construção do Cloud Monitoring âmbito das métricas, independentemente do método que usa para consultar os dados. Por exemplo, se usar o Grafana para consultar dados do Managed Service for Prometheus, cada âmbito de métricas tem de ser configurado como uma origem de dados separada.

Um âmbito de métricas de monitorização é uma construção apenas de tempo de leitura que lhe permite consultar dados de métricas pertencentes a vários Google Cloud projetos. Cada âmbito de métricas é alojado por um Google Cloud projeto designado, denominado projeto de âmbito.

Por predefinição, um projeto é o projeto de âmbito para o seu próprio âmbito de métricas e o âmbito de métricas contém as métricas e a configuração desse projeto. Um projeto de âmbito pode ter mais do que um projeto monitorizado no respetivo âmbito de métricas, e as métricas e as configurações de todos os projetos monitorizados no âmbito de métricas são visíveis para o projeto de âmbito. Um projeto monitorizado também pode pertencer a mais do que um âmbito de métricas.

Quando consulta as métricas num projeto de âmbito, e se esse projeto de âmbito alojar um âmbito de métricas de vários projetos, pode obter dados de vários projetos. Se o âmbito das métricas contiver todos os seus projetos, as consultas e as regras são avaliadas globalmente.

Para mais informações sobre o âmbito dos projetos e o âmbito das métricas, consulte o artigo Âmbito das métricas. Para obter informações sobre a configuração do âmbito das métricas de vários projetos, consulte o artigo Veja métricas de vários projetos.

Serviço gerido para dados do Prometheus no Cloud Monitoring

A forma mais simples de verificar se os seus dados do Prometheus estão a ser exportados é usar a página do explorador de métricas do Cloud Monitoring na Google Cloud consola, que suporta PromQL. Para obter instruções, consulte o artigo Consultar com PromQL no Cloud Monitoring.

Interface do utilizador do frontend do Prometheus autónomo

Pode usar a IU autónoma do frontend do Prometheus para aceder e visualizar os dados carregados. Esta IU executa consultas PromQL em todos os dados no seu Google Cloud projeto, conforme determinado pelo âmbito das métricas associado ao seu projeto.

A IU de front-end também funciona como um proxy de autenticação para aceder aos dados carregados. Esta funcionalidade pode ser usada para ferramentas de cliente que não suportam o OAuth2 para contas de serviço, incluindo o Grafana ou o dimensionamento automático horizontal de pods através da prometheus-adapterbiblioteca.

Recomendamos vivamente que configure o Grafana para visualizar dados do Managed Service for Prometheus através do sincronizador de origens de dados. As instruções para configurar o Grafana através da IU de front-end do Prometheus autónomo estão incluídas aqui como referência para os utilizadores que configuraram anteriormente o Grafana através deste método.

Implemente a IU de front-end

Para implementar a IU do frontend do Prometheus autónomo para o Managed Service for Prometheus, execute os seguintes comandos:

  1. Implemente o serviço frontend e configure-o para consultar o projeto de âmbito do âmbito das métricas à sua escolha:

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

  2. Encaminhe a porta do serviço frontend para a sua máquina local. O exemplo seguinte encaminha o serviço para a porta 9090:

    kubectl -n NAMESPACE_NAME port-forward svc/frontend 9090

    Este comando não é devolvido e, enquanto está em execução, comunica os acessos ao URL.

Se quiser continuar a usar uma implementação do Grafana instalada pelo kube-prometheus, implemente a IU de frontend do Prometheus autónoma no espaço de nomes monitoring.

Pode aceder à IU do frontend do Prometheus autónomo no seu navegador através do URL http://localhost:9090. Se estiver a usar a Cloud Shell para este passo, pode aceder através do botão Pré-visualização Web.

A captura de ecrã seguinte mostra uma tabela na IU autónoma do frontend do Prometheus que apresenta a métrica up:

Visualizar uma métrica na interface do Prometheus.

Também pode configurar a autenticação e a autorização adequadas no serviço frontend usando, por exemplo, o Identity Aware Proxy. Para mais informações sobre a exposição de serviços, consulte o artigo Expor aplicações através de serviços.

Altere o projeto consultado para obter a monitorização de vários projetos

A implementação frontend usa o projeto configurado Google Cloud como o projeto de âmbito. Se este projeto for o projeto de âmbito de um âmbito de métricas de vários projetos, pode ler métricas de todos os projetos no âmbito de métricas.

Pode especificar um projeto com um âmbito de métricas de vários projetos através da flag --query.project-id.

Normalmente, usa um projeto dedicado como projeto de âmbito e este projeto não é o mesmo projeto no qual a implementação do frontend é executada. Para permitir que a implementação leia um projeto de destino diferente, tem de fazer o seguinte:

  • Indicar à implementação frontend qual é o projeto de destino.

  • Conceda à conta de serviço autorização para ler o projeto de destino. Se tem usado a conta de serviço do Compute Engine, pode fazer uma das seguintes ações:default

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

  1. Conceda à conta de serviço autorização para ler a partir do projeto de destino que 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. Abra a implementação frontend criada anteriormente para edição:

    kubectl -n NAMESPACE_NAME edit deploy frontend

  3. Especifique o projeto de destino através do sinalizador --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
...

    Guarde o ficheiro e feche o editor. Após a aplicação da alteração, os pods de front-end são reiniciados e consultam o novo projeto de âmbito.

Autentique a IU de front-end

A implementação frontend suporta a autenticação de acesso básico para acesso autenticado nas versões 0.5.0 e superiores. Para ativar a autenticação, adicione as variáveis de ambiente AUTH_USERNAME e AUTH_PASSWORD à implementaçã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
...

Forneça credenciais explicitamente

Pode ignorar esta secção se estiver a executar o contentor frontend num cluster do Google Kubernetes Engine. Se estiver a ter problemas de autenticação no GKE, consulte o artigo Valide as credenciais da conta de serviço.

Quando executado no GKE, o front-end obtém automaticamente as credenciais do ambiente com base na conta de serviço do nó ou na configuração da federação de identidades da carga de trabalho para o GKE. Em clusters do Kubernetes não pertencentes ao GKE, as credenciais têm de ser fornecidas explicitamente ao front-end através de flags ou da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Defina o contexto para o projeto de destino:

    gcloud config set project PROJECT_ID

  2. Crie uma conta de serviço:

    gcloud iam service-accounts create gmp-test-sa

    Este passo cria a conta de serviço que pode já ter criado nas instruções da federação de identidades da carga de trabalho para o GKE.

  3. Conceda as autorizaçõ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

  4. Crie e transfira 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. Adicione o ficheiro de chave como um segredo ao seu cluster não GKE:

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

  6. Abra o recurso de implementação de frontend para edição:

    kubectl -n NAMESPACE_NAME edit deploy frontend

    1. Adicione o texto apresentado 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. Guarde o ficheiro e feche o editor. Após a aplicação da alteração, os pods são recriados e começam a autenticar-se no back-end de métricas com a conta de serviço fornecida.

    Em alternativa, em vez de usar as flags definidas neste exemplo, pode definir o caminho do ficheiro de chave usando a GOOGLE_APPLICATION_CREDENTIALSvariável de ambiente.

    Usar o Grafana através do proxy de front-end

    O Managed Service for Prometheus usa a origem de dados do Prometheus incorporada para o Grafana, o que significa que pode continuar a usar todos os painéis de controlo do Grafana criados pela comunidade ou pessoais sem alterações. Também pode importar os seus painéis de controlo do Grafana para o Cloud Monitoring.

    Autenticação nas Google Cloud APIs

    Google Cloud 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 Managed Service for Prometheus, pode usar a IU do frontend do Prometheus autónomo como um proxy de autenticação.

    Tem de direcionar o Grafana para o proxy da IU de front-end autónomo para consultar dados globalmente. Se não seguir estes passos, o Grafana só executa consultas em relação aos dados no servidor Prometheus local.

    Se ainda não implementou o serviço Prometheus UI frontend como um proxy, implemente-o agora executando o seguinte comando:

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

    Para clusters do Kubernetes que não sejam do GKE, como clusters do Anthos, consulte também o artigo Faculte credenciais explicitamente para conceder ao frontend serviço as autorizações necessárias para consultar métricas.

    Consulte o artigo altere o projeto consultado para obter instruções sobre como configurar o âmbito das métricas usado pelo serviço frontend para consultar vários projetos.

    Se tiver uma implementação do Grafana pré-existente, como uma instalada pela biblioteca kube-prometheus ou uma instalada através de um gráfico Helm, pode continuar a usá-la com o Managed Service for Prometheus. Se for o caso, consulte o artigo Configure uma origem de dados para ver os passos seguintes. Caso contrário, tem de implementar primeiro o Grafana.

    Implemente o Grafana

    Se não tiver uma implementação do Grafana em execução no cluster, pode criar uma implementação de teste efémera para experimentar.

    Para criar uma implementação efémera do Grafana, aplique o manifesto do Managed Service for Prometheus grafana.yaml ao seu cluster e encaminhe a porta do serviço grafana para a sua máquina local. O exemplo seguinte 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 a porta do serviço grafana para a sua máquina local. Este exemplo encaminha o serviço para a porta 3000:

      kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000

      Este comando não é devolvido e, enquanto está em execução, comunica os acessos ao URL.

      Pode aceder ao Grafana no seu navegador no URL http://localhost:3000 com o nome de utilizador:palavra-passe admin:admin.

    Configure uma origem de dados

    Para consultar o Managed Service for Prometheus no Grafana através da IU do Prometheus como proxy de autenticação, tem de adicionar uma nova origem de dados ao Grafana. Para adicionar uma origem de dados para o serviço gerido, faça o seguinte:

    1. Aceda à sua implementação do Grafana, por exemplo, navegando para o URL http://localhost:3000 para aceder à página de boas-vindas do Grafana.

    2. Selecione Configuração no menu principal do Grafana e, de seguida, selecione Origens de dados.

      Adicionar uma origem de dados no Grafana.

    3. Selecione Adicionar origem de dados e selecione Prometheus como a base de dados de séries cronológicas.

      Adicionar uma origem de dados do Prometheus.

    4. No campo URL do painel HTTP, introduza o URL do serviço Managed Service for Prometheus frontend. Se configurou a IU de front-end do Prometheus para ser executada na porta 9090, o http://frontend.NAMESPACE_NAME.svc:9090 é o URL do serviço para este campo.

      No campo Limite de tempo do painel HTTP, defina o valor como 120.

      Se configurou o proxy da IU de front-end com autenticação básica, ative o interruptor Autenticação básica no painel Autenticação e preencha o nome de utilizador e a palavra-passe.

      No campo Tempo limite da consulta, defina o valor como 2m.

      No campo Método HTTP, selecione GET.

      No campo Tipo Prometheus, selecione Prometheus.

      No campo Versão do Prometheus, selecione 2.40.x ou superior.

      Se tiver várias origens de dados do Prometheus, pode atribuir a esta o nome "Serviço Prometheus gerido". Pode deixar outros campos com os respetivos valores predefinidos.

      Configurar uma origem de dados do Managed Service for Prometheus.

    5. Clique em Guardar e testar e procure a mensagem "A origem de dados está a funcionar".

      Testar a origem de dados do Managed Service for Prometheus.

    Use a nova origem de dados

    Agora, pode criar painéis de controlo do Grafana com a nova origem de dados. Também pode redirecionar os painéis de controlo existentes para a nova origem de dados. A captura de ecrã seguinte mostra um gráfico do Grafana que apresenta a métrica up:

    Gráfico do Grafana para a métrica de atividade do Managed Service for Prometheus.

    Associar o Managed Service for Prometheus ao Thanos

    Pode federar o Managed Service for Prometheus para uma pilha Thanos implementada automaticamente usando o thanos-promql-connector de código aberto. Google Cloudnão oferece suporte técnico para esta integração.

    API HTTP do Prometheus

    O Managed Service for Prometheus suporta a API HTTP Prometheus a montante no URL com o prefixo https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/. Para informações sobre os pontos finais suportados, consulte a secção Compatibilidade da API.

    Esta API pode ser acedida por qualquer ferramenta que possa interagir com um servidor Prometheus padrão. Este é apenas um ponto final da API; não publica uma IU. Como Google Cloud API, a API usa a autenticação OAuth2 e, como parte da API Cloud Monitoring, o valor de PROJECT_ID é o projeto de âmbito de um âmbito de métricas, pelo que pode obter dados de qualquer projeto no âmbito de métricas. Para mais informações sobre o âmbito, consulte o artigo Âmbito das métricas.

    Para usar este ponto final, forneça uma expressão PromQL. Por exemplo, a seguinte consulta instantânea obtém todos os intervalos 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 o pedido for bem-sucedido, a consulta devolve um resultado semelhante ao seguinte, que foi formatado para facilitar a leitura:

    {
  "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 obter informações sobre como consultar Google Cloud métricas do sistema através do PromQL, consulte o artigo PromQL para métricas do Cloud Monitoring.

    Compatibilidade da API

    Os seguintes pontos finais da API HTTP do Prometheus são suportados pelo Managed Service for Prometheus no URL com o prefixo https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/.

    Para aceder à documentação completa, consulte a documentação de referência da API Cloud Monitoring. Os pontos finais HTTP do Prometheus não estão disponíveis nas bibliotecas cliente específicas do idioma do Cloud Monitoring.

    Para informações sobre a compatibilidade com o PromQL, consulte o suporte do PromQL.

    • Os seguintes pontos finais são totalmente suportados:

    • O ponto final /api/v1/label/<label_name>/values só funciona se a etiqueta __name__ for fornecida através da sua utilização como o valor <label_name> ou através da correspondência exata com a mesma usando um seletor de séries. Por exemplo, as seguintes chamadas são totalmente suportadas:

      • /api/v1/label/__name__/values
      • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
      • /api/v1/label/labelname/values?match[]={__name__="metricname"}

      Esta limitação faz com que as consultas de variáveis no Grafana falhem.label_values($label) Em alternativa, pode usar label_values($metric, $label). Este tipo de consulta é recomendado porque evita obter valores para etiquetas em métricas que não são relevantes para o painel de controlo especificado.

    • O ponto final /api/v1/series é suportado para pedidos GET, mas não para pedidos POST. Quando usa o sincronizador de origens de dados ou o proxy de front-end, esta restrição é gerida por si. Também pode configurar as suas origens de dados do Prometheus no Grafana para emitir apenas pedidos GET. O parâmetro match[] não suporta a correspondência de expressões regulares na etiqueta __name__.