Consulte e veja métricas

Depois de recolher métricas das cargas de trabalho implementadas no Google Distributed Cloud (GDC) air-gapped, pode começar a analisá-las. Para analisar as métricas, pode visualizá-las e filtrá-las em painéis de controlo do Grafana informativos ou aceder às mesmas diretamente a partir do Cortex através da ferramenta curl para scripting e automatização flexíveis.

Esta página fornece instruções detalhadas sobre como consultar e visualizar as suas métricas através da interface do utilizador do Grafana e da ferramenta curl para o ponto final do Cortex, de modo a obter estatísticas sobre o desempenho da sua carga de trabalho.

Pode aceder às suas métricas através de um dos dois métodos seguintes:

  • Painéis de controlo do Grafana: explore tendências e identifique anomalias com visualizações intuitivas de métricas importantes, como a utilização da CPU, o consumo de armazenamento e a atividade de rede. O Grafana oferece uma interface intuitiva para filtrar e analisar os dados da carga de trabalho em painéis de controlo.
  • Ponto final do Cortex: para exemplos de utilização mais avançados, consulte diretamente a instância do Cortex do seu projeto através da ferramenta curl numa linha de comandos. O Cortex armazena as métricas do Prometheus do seu projeto e fornece um ponto final HTTP para acesso programático. Este acesso permite-lhe exportar dados, automatizar tarefas e criar integrações personalizadas.

Antes de começar

Para receber as autorizações necessárias para consultar e visualizar métricas nos painéis de controlo do Grafana, peça ao administrador de IAM da organização ou ao administrador de IAM do projeto que lhe conceda uma das funções predefinidas de visualizador do Grafana da organização ou visualizador do Grafana do projeto. Consoante o nível de acesso e as autorizações de que precisa, pode obter funções do Grafana numa organização ou num projeto.

Em alternativa, para receber as autorizações necessárias para consultar métricas do ponto final do Cortex, peça ao administrador de IAM do projeto para lhe conceder a função de visualizador do Prometheus do Project Cortex no seu espaço de nomes do projeto.

A tabela seguinte resume os requisitos de Role para PA persona.

Perfil Objeto Cluster Função Espaço de nomes Grupo/utilizador Configuração
PA grafana org-admin project-grafana-viewer platform-obs Grupo 1
PA cortex org-admin project-cortex-prometheus-viewer platform-obs Grupo 2
PA grafana org-admin project-grafana-viewer platform-obs Utilizador 3
PA cortex org-admin project-cortex-prometheus-viewer platform-obs Utilizador 4

Substitua as seguintes variáveis adequadamente:

Variável Descrição
KUBECONFIG Precisa do kubeconfig para o cluster específico que contém o NAMESPACE onde esta RoleBinding vai ser aplicada.
RULE_NAME O nome exclusivo deste recurso RoleBinding no espaço de nomes. Por exemplo, io-root-cortex-prometheus-viewer.
NAMESPACE O espaço de nomes do Kubernetes onde este RoleBinding vai ser criado e aplicado. Procure a coluna Namespace na tabela anterior.
EMAIL_ADDRESS O identificador do utilizador ao qual está a ser concedida a função. Normalmente, trata-se de um endereço de email. Por exemplo, infrastructure-operator@example.com.
ROLE O nome do Role que contém as autorizações que quer conceder ao utilizador. Procure as funções disponíveis na tabela anterior
GROUP_NAME O nome do Role que contém as autorizações que quer conceder ao utilizador. Por exemplo, io-group.
ZONE Nome da zona

Configuração 1

Esta configuração destina-se à persona PA, segmentando o objeto grafana no cluster org-admin. Concede a função project-grafana-viewer no espaço de nomes platform-obs a um Group.

  • Comando Kubectl

    Este é o formato de comando genérico:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewer
    

    Exemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs
    
  • Caminho do ficheiro IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>
    
  • Ficheiro YAML

    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: RULE_NAME
      namespace: platform-obs
    subjects:
    - kind: Group
      name: GROUP_NAME
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: Role
      name: project-grafana-viewer
      apiGroup: rbac.authorization.k8s.io
    

Configuração 2

Esta configuração destina-se à persona PA, segmentando o objeto cortex no cluster org-admin. Concede a função project-cortex-prometheus-viewer no espaço de nomes platform-obs a um Group.

  • Comando Kubectl

    Este é o formato de comando genérico:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewer
    

    Exemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obs
    
  • Caminho do ficheiro IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>
    
  • Ficheiro YAML

    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: RULE_NAME
      namespace: platform-obs
    subjects:
    - kind: Group
      name: GROUP_NAME
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: Role
      name: project-cortex-prometheus-viewer
      apiGroup: rbac.authorization.k8s.io
    

Configuração 3

Esta configuração destina-se à persona PA, segmentando o objeto grafana no cluster org-admin. Concede a função project-grafana-viewer no espaço de nomes platform-obs a um User.

  • Comando Kubectl

    Este é o formato de comando genérico:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewer
    

    Exemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs
    
  • Caminho do ficheiro IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>
    
  • Ficheiro YAML

    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: RULE_NAME
      namespace: platform-obs
    subjects:
    - kind: User
      name: EMAIL_ADDRESS
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: Role
      name: project-grafana-viewer
      apiGroup: rbac.authorization.k8s.io
    

Configuração 4

Esta configuração destina-se à persona PA, segmentando o objeto cortex no cluster org-admin. Concede a função project-cortex-prometheus-viewer no espaço de nomes platform-obs a um User.

  • Comando Kubectl

    Este é o formato de comando genérico:

    kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewer
    

    Exemplo:

    kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obs
    
  • Caminho do ficheiro IAC

    /infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>
    
  • Ficheiro YAML

    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: RULE_NAME
      namespace: platform-obs
    subjects:
    - kind: User
      name: EMAIL_ADDRESS
      apiGroup: rbac.authorization.k8s.io
    roleRef:
      kind: Role
      name: project-cortex-prometheus-viewer
      apiGroup: rbac.authorization.k8s.io
    

Para mais informações sobre estas funções, consulte o artigo Prepare as autorizações de IAM.

Obtenha e filtre as suas métricas

Selecione um dos seguintes métodos para criar consultas, visualizar tendências e filtrar métricas das cargas de trabalho do seu projeto:

Painéis de controlo do Grafana

Esta secção descreve como aceder às suas métricas através dos painéis de controlo do Grafana.

Identifique o seu ponto final do Grafana

O seguinte URL é o ponto final da instância do Grafana do seu projeto:

  https://GDC_URL/PROJECT_NAMESPACE/grafana

Substitua o seguinte:

  • GDC_URL: o URL da sua organização no GDC.
  • PROJECT_NAMESPACE: o espaço de nomes do seu projeto.

    Por exemplo, o ponto final do Grafana para o projeto platform-obs na organização org-1 é https://org-1/platform-obs/grafana.

Veja métricas na interface do utilizador do Grafana

Recupere métricas na interface do utilizador do Grafana:

  1. Na consola do GDC, selecione o seu projeto.
  2. No menu de navegação, selecione Operações > Monitorização.
  3. Clique em Ver tudo no Grafana.

    É aberta uma nova página com o seu ponto final do Grafana e apresenta a interface do utilizador.

  4. Na interface do utilizador, clique em explorar Explorar no menu de navegação para abrir a página Explorar.

  5. No menu da barra Explorar, selecione uma origem de dados para obter métricas, de acordo com o tipo de universo:

    • Universos de zona única: selecione prometheus para apresentar métricas da zona única do seu universo.

    • Universos multizona: o Grafana pode ligar-se a diferentes zonas e mostrar dados entre zonas. Selecione Métricas ZONE_NAME para apresentar métricas de qualquer zona do seu universo, independentemente da zona em que tem sessão iniciada.

      Além disso, para ter visualizações de dados entre zonas num único painel de controlo e adicionar várias zonas à sua consulta, selecione Misto como origem de dados.

  6. Introduza uma consulta para pesquisar métricas através de expressões PromQL (Prometheus Query Language). Pode concluir este passo de uma das seguintes formas:

    • Selecione uma métrica e uma etiqueta para a sua consulta nos menus Métrica e Filtros de etiquetas. Clique em adicionar Adicionar para adicionar mais etiquetas à sua consulta. Em seguida, clique em Executar consulta.
    • Introduza a consulta diretamente no campo de texto Métricas e prima Shift+Enter para executar a consulta.

    A página apresenta as métricas que correspondem à sua consulta.

    A opção prometheus está selecionada na página Explorar para obter métricas.

    Figura 1. Opção de menu para consultar métricas a partir da interface do utilizador do Grafana.

    Na figura 1, a opção prometheus apresenta a interface que lhe permite criar consultas a partir do Grafana para obter métricas.

    Para ver exemplos de valores de etiquetas que pode usar para consultar métricas, consulte o artigo Consultas e etiquetas de exemplo.

Ponto final do Cortex

Esta secção descreve como aceder às suas métricas através do Cortex.

Identifique o seu ponto final do Cortex

O seguinte URL é o ponto final da instância do Cortex do seu projeto:

  https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/

Substitua o seguinte:

  • GDC_URL: o URL da sua organização no GDC.
  • PROJECT_NAMESPACE: o espaço de nomes do seu projeto.

    Por exemplo, o ponto final do Cortex para o projeto platform-obs na organização org-1 é https://org-1/platform-obs/cortex/prometheus/.

Autentique o pedido curl

  1. Transfira e instale a CLI gcloud.
  2. Defina a propriedade gdcloud:core/organization_console_url

    gdcloud config set core/organization_console_url
    https://GDC_URL
    
  3. Inicie sessão com o Fornecedor de identidade configurado:

    gdcloud auth login
    
  4. Use o seu nome de utilizador e palavra-passe para autenticar e iniciar sessão.

    Quando o início de sessão for bem-sucedido, pode usar o cabeçalho de autorização no seu pedido curl através do comando gdcloud auth print-identity-token. Para mais informações, consulte gdcloud auth.

Chame o ponto final do Cortex

Conclua os passos seguintes para aceder ao ponto final do Cortex através da ferramenta curl:

  1. Autentique o curlpedido.
  2. Use curl para chamar o ponto final da Cortex e expanda o URL com o formato da API HTTP de consulta para consultar métricas.

    Segue-se um exemplo de um pedido curl:

    curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \
    -H "Authorization: Bearer $(gdcloud auth print-identity-token \
    --audiences=https://GDC_URL)"
    

    Obtém o resultado após o comando. A resposta da API está no formato JSON.

Consultas e etiquetas de exemplo

Pode consultar métricas através do nome da métrica e de pares de chave-valor para etiquetas. Uma consulta PromQL tem a seguinte sintaxe:

metric_name{label_one="value", label_two="value"}

As etiquetas permitem-lhe diferenciar as caraterísticas de uma métrica. Desta forma, os autores dos contentores fazem com que as respetivas cargas de trabalho gerem métricas e adicionem etiquetas para filtrar essas métricas.

Por exemplo, pode ter uma métrica api_http_requests_total para contabilizar o número de pedidos HTTP recebidos. Em seguida, pode adicionar uma etiqueta request_method a esta métrica, que assume um valor POST, GET ou PUT. Consequentemente, cria três streams de métricas para cada tipo de pedido que possa receber. Neste caso, para encontrar o número de pedidos HTTP GET, execute a seguinte consulta:

api_http_requests_total{request_method="GET"}

Consulte o artigo Nomenclatura de métricas e etiquetas para mais informações sobre métricas e etiquetas.

Seguem-se algumas das etiquetas predefinidas que o recurso personalizado MonitoringTarget adiciona. Pode usar estas etiquetas predefinidas para consultar métricas:

  • _gdch_service: o diminutivo do serviço.
  • cluster: o nome do cluster.
  • container_name: o nome do contentor num agrupamento.
  • namespace_name: o espaço de nomes do seu projeto.
  • pod_name: o prefixo do nome do agrupamento.

A tabela seguinte descreve as etiquetas que o Prometheus adiciona automaticamente:

Etiquetas predefinidas
Etiqueta da métrica Descrição
job O nome interno da tarefa de recolha de dados usada para recolher a métrica. As tarefas criadas pelo recurso personalizado MonitoringTarget têm um nome com o seguinte padrão:

obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/J

I e J são números únicos determinados internamente para evitar conflitos de nomes.
instance O $IP:$PORT do serviço desativado. Se um recurso de carga de trabalho tiver várias réplicas, use este campo para as diferenciar.

Os exemplos de código seguintes mostram a utilização de pares de chave-valor para etiquetas para consultar diferentes métricas:

  • Veja todas as streams de métricas das operações processadas no seu projeto:

    processed_ops_total
    
  • Veja as operações processadas recolhidas num cluster do Kubernetes:

    processed_ops_total{cluster="CLUSTER_NAME"}
    
  • Veja a utilização da CPU recolhida num cluster do Kubernetes:

    cpu_usage{cluster="CLUSTER_NAME"}
    

Use a ferramenta de reetiquetagem de métricas para adicionar etiquetas não expostas inicialmente pelos contentores eliminados e mudar o nome das métricas produzidas. Tem de configurar o recurso personalizado MonitoringTarget para adicionar etiquetas às métricas que recolhe. Especifique essas etiquetas no campo metricsRelabelings do recurso personalizado. Para mais informações, consulte o artigo Etiquete métricas.

Consultar a API HTTP

Vista geral do formato

As respostas da API são formatadas de forma consistente em JSON. Os pedidos bem-sucedidos recebem sempre um código de estado 2xx.

Para pedidos inválidos, os controladores da API devolvem um objeto de erro JSON juntamente com um dos seguintes códigos de estado HTTP:

  • 400 Pedido errado: se faltarem parâmetros essenciais ou se forem fornecidos incorretamente.
  • 503 Serviço indisponível: se as consultas excederem o respetivo limite de tempo ou forem anuladas.

Todos os dados recolhidos com êxito são incluídos no campo "data" da resposta.

O formato do envelope de resposta JSON é o seguinte:

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only set if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"],
  // Only set if there were info-level annotations while executing the request.
  "infos": ["<string>"]
}

Consultas instantâneas

O seguinte ponto final avalia uma consulta instantânea num único ponto no tempo:

GET /api/v1/query
POST /api/v1/query

Os seguintes parâmetros de consulta de URL estão disponíveis para consultas de expressões do Prometheus:

  • query=<string>: a sequência de carateres de consulta da expressão Prometheus.
  • time=<rfc3339 | unix_timestamp>: uma indicação de tempo de avaliação opcional, especificada como uma string RFC 3339 ou uma indicação de tempo Unix. Se for omitido, é usado o tempo atual do servidor.
  • timeout=<duration>: um limite de tempo de avaliação opcional. O valor predefinido é o valor do sinalizador query.timeout e está limitado por este.
  • limit=<number>: um número máximo opcional de séries a devolver. Isto trunca as séries para matrizes e vetores, mas não afeta os escalares nem as strings. O valor 0 desativa este limite.
  • lookback_delta=<number>: um parâmetro opcional para substituir o período de análise retrospetiva especificamente para esta consulta.

A hora atual do servidor é usada se o parâmetro de tempo for omitido.

Para consultas maiores que possam exceder os limites de carateres do URL, pode enviar estes parâmetros através do método POST. Certifique-se de que o corpo do pedido está codificado por URL e que o cabeçalho Content-Type está definido como application/x-www-form-urlencoded.

A secção de dados do resultado da consulta tem o seguinte formato:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> refere-se aos dados dos resultados da consulta, que têm formatos variáveis consoante o resultType.

O exemplo seguinte avalia a expressão até à hora 2015-07-01T20:10:51.781Z:

curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

Consultas de intervalo

O seguinte ponto final avalia uma consulta de expressão num intervalo de tempo:

GET /api/v1/query_range
POST /api/v1/query_range

Os seguintes parâmetros de consulta de URL estão disponíveis para consultas de expressões do Prometheus:

  • query=<string>: a sequência de carateres de consulta da expressão Prometheus.
  • start=<rfc3339 | unix_timestamp>: indicação de tempo de início, inclusive.
  • end=<rfc3339 | unix_timestamp>: data/hora de fim, inclusive.
  • step=<duration | float>: largura do passo de resolução da consulta no formato de duração ou número de segundos flutuante.
  • timeout=<duration>: um limite de tempo de avaliação opcional. O valor predefinido é o valor do sinalizador query.timeout e está limitado por este.
  • limit=<number>: um número máximo opcional de séries a devolver. Isto trunca as séries para matrizes e vetores, mas não afeta os escalares nem as strings. O valor 0 desativa este limite.
  • lookback_delta=<number>: um parâmetro opcional para substituir o período de análise retrospetiva especificamente para esta consulta.

Para consultas maiores que possam exceder os limites de carateres do URL, pode enviar estes parâmetros através do método POST. Certifique-se de que o corpo do pedido está codificado por URL e que o cabeçalho Content-Type está definido como application/x-www-form-urlencoded.

A secção de dados do resultado da consulta tem o seguinte formato:

{
  "resultType": "matrix",
  "result": <value>
}

O exemplo seguinte avalia a expressão up num intervalo de 30 segundos com uma resolução de consulta de 15 segundos.

curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

Nomenclatura de métricas e etiquetas

Diretrizes de nomenclatura de métricas

Ao definir nomes de métricas, tenha em consideração os seguintes princípios:

  • Um nome de métrica DEVE incluir um prefixo de aplicação de uma única palavra, que as bibliotecas de cliente referem por vezes como um "espaço de nomes". Este prefixo identifica o domínio ao qual a métrica pertence. Para métricas específicas da aplicação, o nome da aplicação é normalmente usado como prefixo.

    Exemplos:

    • prometheus_notifications_total (específico do servidor Prometheus)
    • process_cpu_seconds_total (exportado por muitas bibliotecas de cliente)
    • http_request_duration_seconds (para todos os pedidos HTTP)
  • Um nome de métrica TEM de representar uma única unidade (por exemplo, evite misturar segundos com milissegundos ou segundos com bytes).

  • Um nome de métrica DEVE usar unidades base (por exemplo, segundos, bytes, metros) em vez de unidades derivadas (por exemplo, milissegundos, megabytes, quilómetros).

  • Um nome de métrica DEVE incluir um sufixo de unidade no plural. Para contagens de acumulação, deve usar o sufixo "total" além do sufixo da unidade, se aplicável.

    Exemplos:

    • http_request_duration_seconds
    • node_memory_usage_bytes
    • http_requests_total (para uma contagem acumulada sem unidade)
    • process_cpu_seconds_total (para uma contagem acumulada com unidade)
    • foobar_build_info (para uma pseudométrica que fornece metadados sobre o ficheiro binário em execução)
  • Um nome de métrica PODE ordenar os respetivos componentes para facilitar o agrupamento conveniente quando ordenado lexicograficamente, desde que todas as outras regras sejam seguidas. As métricas relacionadas têm frequentemente componentes de nomes comuns colocados em primeiro lugar para garantir que são ordenadas em conjunto.

    Exemplos:

    • prometheus_tsdb_head_truncations_closed_total
    • prometheus_tsdb_head_truncations_established_total
    • prometheus_tsdb_head_truncations_failed_total
    • prometheus_tsdb_head_truncations_total
  • Um nome de métrica DEVE representar consistentemente a mesma "coisa a ser medida" lógica em todas as dimensões de etiquetas.

    Exemplos:

    • duração do pedido
    • bytes de transferência de dados
    • utilização instantânea de recursos como percentagem

Diretrizes de nomenclatura de etiquetas

Quando mede algo, use etiquetas para distinguir as respetivas caraterísticas. Por exemplo:

  • Para o total de pedidos HTTP da API (api_http_requests_total), diferencie por tipo de operação, por exemplo, create, update, delete (tipos de pedidos: operation="create|update|delete").
  • Para a duração do pedido da API em segundos (api_request_duration_seconds), diferencie por fase do pedido, por exemplo, extract, transform, load (fases do pedido: stage="extract|transform|load").

Evite incluir nomes de etiquetas no próprio nome da métrica, uma vez que isto cria redundância e pode gerar confusão se essas etiquetas forem agregadas posteriormente.