Arquivo secundário do Prometheus legado

O formato de exposição Prometheus é uma convenção usada por muitos aplicativos, especialmente no Kubernetes, para exportar as métricas. O Prometheus é uma ferramenta de monitoramento de código aberto muito usada para coletar, armazenar e consultar essas métricas. Oferecemos algumas maneiras diferentes de integrar métricas no estilo do Prometheus ao Cloud Monitoring.

Abordagem	Status de compatibilidade	Notas
Serviço gerenciado do Google Cloud para o Prometheus (recomendado)	A versão autoimplantada está disponível em todos os ambientes. A coleta gerenciada está disponível em todos os ambientes do Kubernetes. A coleta gerenciada via gcloud está disponível nas versões 1.22 e mais recentes do GKE	Oferece compatibilidade total com o ecossistema de código aberto via PromQL. Preço menor que as métricas externas
Servidor Prometheus com coletor do Stackdriver	Obsoleto O suporte depende da versão do servidor Prometheus	As métricas no estilo do Prometheus são ingeridas como métricas externas
Métricas de carga de trabalho do GKE	Obsoleto Suportado nas versões 1.20.8-gke.2100 a 1.23 do GKE, mas será descontinuado a partir da versão 1.24	Não sujeita a cobrança durante a suspensão de uso

O restante desta página descreve como configurar e usar o Prometheus com o Cloud Operations para GKE usando o coletor do Stackdriver.

O código-fonte da integração está disponível em modo público.

Antes de começar

Aviso: a abordagem descrita neste documento está obsoleta. O Google Cloud Managed Service para Prometheus é recomendado.

Confirme se você já criou um cluster do GKE com o Cloud Operations para GKE ativado e instalou um servidor Prometheus.

O Prometheus não oferece suporte integrado para o Windows Server. Como solução alternativa, implante o servidor Prometheus em um pool de nós Linux adicional para capturar as métricas do Windows e enviar as métricas de volta ao coletor do Stackdriver no pool de nós do Linux.

Antes de instalar o coletor do Stackdriver, leia atentamente estes requisitos:

• Execute um servidor Prometheus compatível e o configure para monitorar os aplicativos no cluster. Para instalar o Prometheus no cluster, veja o guia de primeiros passos do Prometheus.

• Você precisa ter configurado seu cluster para usar o Cloud Operations para GKE. Veja instruções em Como instalar o Cloud Operations para GKE.

• É necessário ter o papel Administrador do Kubernetes Engine Cluster do cluster. Para ver mais informações, leia sobre os papéis do GKE.

• É preciso garantir que a conta de serviço tenha as permissões adequadas. Para ver mais informações, leia Usar as contas de serviço com privilégios mínimos para seus nós.

Como instalar o coletor

Para implantar o coletor do Stackdriver, faça o seguinte:

1. Identifique o objeto a ser atualizado pelo nome e pelo tipo de controlador . Somente os tipos de controladores de deployment e statefulset são compatíveis.

2. Configure as variáveis de ambiente a seguir:

   • KUBE_NAMESPACE: namespace para executar o script.
   • KUBE_CLUSTER: parâmetro do nome do cluster do arquivo secundário.
   • GCP_REGION: parâmetro de região do Google Cloud do arquivo secundário.
   • GCP_PROJECT: parâmetro do projeto do Google Cloud do arquivo secundário.
   • DATA_DIR: diretório de dados do arquivo secundário. Este é o diretório que hospeda o volume compartilhado que o servidor do Prometheus grava. Nas instruções seguintes, essa variável é definida como o valor /data.
   • DATA_VOLUME: nome do volume compartilhado no DATA_DIR que contém os dados do Prometheus. Nas instruções seguintes, essa variável é definida como data-volume.
   • SIDECAR_IMAGE_TAG: versão da imagem do Docker do arquivo secundário do Prometheus. A versão mais recente se encontra no Container Registry.

3. Execute o script a seguir e forneça os dois parâmetros identificados na etapa inicial deste procedimento:

   kube/patch.sh

   Ver no GitHub

   #!/bin/sh
   
   set -e
   set -u
   
   CLEAN_UP_ORPHANED_REPLICA_SETS='--clean-up-orphaned-replica-sets'
   usage() {
     echo -e "Usage: $0 <deployment|statefulset> <name> [${CLEAN_UP_ORPHANED_REPLICA_SETS}]\n"
   }
   
   if [  $# -le 1 ]; then
     usage
     exit 1
   fi
   
   SHOULD_CLEAN_UP=${3:-}
   
   # Override to use a different Docker image name for the sidecar.
   export SIDECAR_IMAGE_NAME=${SIDECAR_IMAGE_NAME:-'gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar'}
   
   kubectl -n "${KUBE_NAMESPACE}" patch "$1" "$2" --type strategic --patch "
   spec:
     template:
       spec:
         containers:
         - name: sidecar
           image: ${SIDECAR_IMAGE_NAME}:${SIDECAR_IMAGE_TAG}
           imagePullPolicy: Always
           args:
           - \"--stackdriver.project-id=${GCP_PROJECT}\"
           - \"--prometheus.wal-directory=${DATA_DIR}/wal\"
           - \"--stackdriver.kubernetes.location=${GCP_REGION}\"
           - \"--stackdriver.kubernetes.cluster-name=${KUBE_CLUSTER}\"
           #- \"--stackdriver.generic.location=${GCP_REGION}\"
           #- \"--stackdriver.generic.namespace=${KUBE_CLUSTER}\"
           ports:
           - name: sidecar
             containerPort: 9091
           volumeMounts:
           - name: ${DATA_VOLUME}
             mountPath: ${DATA_DIR}
   "
   if [[ "${SHOULD_CLEAN_UP}" == "${CLEAN_UP_ORPHANED_REPLICA_SETS}" ]]; then
     # Delete the replica sets from the old deployment. If the Prometheus Server is
     # a deployment that does not have `revisionHistoryLimit` set to 0, this is
     # useful to avoid PVC conflicts between the old replica set and the new one
     # that prevents the pod from entering a RUNNING state.
     kubectl -n "${KUBE_NAMESPACE}" get rs | grep "$2-" | awk '{print $1}' | xargs kubectl delete -n "${KUBE_NAMESPACE}" rs
   fi
   

Após a execução do script, o coletor do Stackdriver é adicionado como um arquivo secundário aos pods do objeto identificado no primeiro passo do procedimento. As duas linhas do script comentadas não são relevantes para a coleta de dados de métricas dos clusters do GKE. No entanto, essas duas linhas são relevantes caso queira preencher um MonitoredResource genérico.

Há etapas extras que você precisa seguir para tornar as alterações de configuração permanentes. Essas etapas são descritas nas próximas seções:

Como validar a instalação

Para validar a instalação do coletor do Stackdriver, execute o seguinte comando:

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name> -o=go-template='{{$output := "stackdriver-prometheus-sidecar does not exist."}}{{range .spec.template.spec.containers}}{{if eq .name "sidecar"}}{{$output = (print "stackdriver-prometheus-sidecar exists. Image: " .image)}}{{end}}{{end}}{{printf $output}}{{"\n"}}'

• Após a instalação do arquivo secundário do Prometheus, a saída do script lista a imagem usada no registro do contêiner. No exemplo a seguir, a versão da imagem é 0.4.3. Na sua instalação, a versão pode ser diferente:

  stackdriver-prometheus-sidecar exists. Image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:0.4.3
  

• Caso contrário, a saída do script mostrará:

  stackdriver-prometheus-sidecar does not exist.
  

Para determinar se a carga de trabalho está atualizada e disponível, execute:

kubectl -n "${KUBE_NAMESPACE}" get <deployment|statefulset> <name>

Como tornar a alteração de configuração permanente

Depois de verificar se o coletor foi instalado, atualize a configuração do cluster para tornar as alterações permanentes:

1. Configure o servidor do Prometheus para gravar em um volume compartilhado. Nas etapas de exemplo a seguir, presume-se que DATA_DIR foi definido como /data e DATA_VOLUME como data-volume:

   1. Verifique se há um volume compartilhado no pod do Prometheus:

      volumes:
        - name: data-volume
          emptyDir: {}
      

   2. Prometheus montou o volume em /data:

      volumeMounts:
      - name: data-volume
        mountPath: /data
      

   3. Instrua o servidor do Prometheus a gravar no volume compartilhado em /data adicionando o seguinte a seu contêiner args:

      --storage.tsdb.path=/data
      

2. Com as ferramentas que você usa para gerenciar a configuração das cargas de trabalho, aplique de novo a configuração ao cluster e inclua o contêiner do coletor do Stackdriver como um arquivo secundário na configuração nova:

   - name: sidecar
     image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:[SIDECAR_IMAGE_TAG]
     args:
     - "--stackdriver.project-id=[GCP_PROJECT]"
     - "--prometheus.wal-directory=/data/wal"
     - "--prometheus.api-address=[API_ADDRESS]"
     - "--stackdriver.kubernetes.location=[GCP_REGION]"
     - "--stackdriver.kubernetes.cluster-name=[KUBE_CLUSTER]"
     ports:
     - name: sidecar
       containerPort: 9091
     volumeMounts:
     - name: data-volume
       mountPath: /data
   

   Na expressão anterior, [API_ADDRESS] se refere ao endereço da API do Prometheus, que, geralmente, é http://127.0.0.1:9090.

Para ver outros detalhes de configuração do coletor, leia a documentação do arquivo secundário do Prometheus no Stackdriver.

Como ver métricas

O Prometheus está configurado para exportar métricas para o pacote de operações do Google Cloud como métricas externas.

Para visualizar essas métricas:

1. No console do Cloud, selecione Monitoramento:

   Acessar o Monitoramento

2. No painel de navegação do Monitoring, clique em Metrics Explorer.

3. No menu Find resource type and metric menu:

   • Selecione Kubernetes Container (k8s_container) como Resource type.
   • No campo Metric, selecione um com o prefixo external/prometheus/. Por exemplo, é possível selecionar external/prometheus/go_memstats_alloc_bytes.

   No exemplo a seguir, um filtro foi adicionado para exibir as métricas de um cluster específico. Filtrar por nome de cluster é útil quando você tem vários clusters:

   

Gerenciamento de custos para métricas derivadas do Prometheus

Normalmente, o Prometheus é configurado para coletar todas as métricas exportadas por seu aplicativo e, por padrão, o coletor do Stackdriver envia essas métricas para o Cloud Monitoring. Essa coleção inclui métricas exportadas por bibliotecas de que seu aplicativo depende. Por exemplo, a biblioteca de cliente do Prometheus exporta muitas métricas sobre o ambiente do aplicativo.

É possível configurar filtros no coletor do Stackdriver para selecionar quais métricas são ingeridas no Cloud Monitoring. Por exemplo, para importar somente as métricas geradas por kubernetes-pods e kubernetes-service-endpoints, adicione a seguinte instrução --include ao iniciar o stackdriver-prometheus-sidecar:

 --include={job=~"kubernetes-pods|kubernetes-service-endpoints"}

Para ver mais informações, leia a documentação do arquivo secundário do Prometheus no Stackdriver .

Também é possível estimar o quanto essas métricas ajudam na fatura.

Problemas de integração do Prometheus

Nenhum dado é exibido no Cloud Monitoring.

Se nenhum dado aparecer no Cloud Monitoring depois de passar pelas etapas de instalação, procure mensagens de erro nos registros do coletor.

Se os registros não tiverem mensagens de falha óbvias, passe a sinalização --log.level=debug para o coletor a fim de ativar os registros de depuração. Reinicie o coletor para que a alteração de registro funcione. Depois de reiniciar o coletor, procure mensagens de erro nos registros do coletor.

Para verificar se os dados estão sendo enviados para o Cloud Monitoring, envie as solicitações para os arquivos usando o parâmetro de linha de comando --stackdriver.store-in-files-directory e depois inspecionar os arquivos nesse diretório.

Observação: ao terminar de solucionar o problema, remova esse parâmetro, porque as métricas não são enviadas para a API Cloud Monitoring quando o parâmetro é especificado. Uma opção é excluir esses arquivos para economizar espaço de armazenamento.

Permissão negada

Se você vir erros de permissão negada da API Monitoring, revise os requisitos descritos em Antes de começar. Verifique se as contas de serviço têm a permissão correta. Se você usar a identidade da carga de trabalho, crie uma relação entre KSAs e GSAs.

Estou usando regras de gravação, e as métricas não estão aparecendo no Cloud Monitoring.

Quando estiver usando papéis de registro, se possível, processe a métrica bruta no Cloud Monitoring e use os recursos dele para agregar os dados quando criar um gráfico ou painel.

Se não quiser ingerir a métrica bruta, adicione uma entrada static_metadata na configuração do coletor. Esta opção exige que você preserve os rótulos job e instance. Por exemplo, a configuração atual é válida:

• Configuração do servidor Prometheus:

  groups:
  - name: my-groups
    rules:
    - record: backlog_avg_10m
      expr: avg_over_time(backlog_k8s[10m])
    - record: backlog_k8s
      expr: sum(total_lag) by (app, job, instance)
  

• Configuração do coletor do Prometheus:

  static_metadata:
    - metric: backlog_avg_10m
      type: gauge
  

As regras de gravação que alteram ou removem os rótulos job ou instance não são válidas.

Minhas métricas não apresentam os rótulos job e instance do Prometheus.

O coletor do Stackdriver para o Prometheus cria um MonitoredResource do Cloud Monitoring para seus objetos do Kubernetes a partir de marcadores conhecidos do Prometheus. Ao alterar os descritores de rótulo, o coletor não consegue gravar as métricas no Monitoring.

Aparecem os erros "série temporal duplicada" ou "gravações fora de ordem" nos registros.

Esses erros são causados pela gravação de dados de métricas duas vezes na mesma série temporal. Eles ocorrem quando os endpoints do Prometheus usam a mesma métrica duas vezes a partir de um único recurso monitorado do Cloud Monitoring.

Por exemplo, um contêiner do Kubernetes pode enviar métricas do Prometheus em várias portas. Como o recurso monitorado k8s_container do Stackdriver não diferencia recursos com base na porta, o Monitoring detecta que você está gravando dois pontos na mesma série temporal. Para evitar essa situação, adicione um rótulo de métrica ao Prometheus diferenciando a série temporal. Por exemplo, use o rótulo __meta_kubernetes_pod_annotation_prometheus_io_port, porque ele permanece constante nas reinicializações do contêiner.

Aparecem os erros "tipo de métrica precisa ser X, mas é Y" nos registros.

Esses erros são causados pela alteração do tipo de métrica do Prometheus em um descritor de métrica atual. As métricas do Cloud Monitoring são estritamente digitadas e não são compatíveis com a alteração do tipo de métrica entre o medidor, o contador e outros.

Para alterar um tipo de uma métrica, exclua os descritores de métrica correspondentes e crie um novo descritor. A exclusão de descritores de métrica torna os dados da série temporal atual inacessíveis.

Tenho certeza de que já vi os tipos de métricas do Prometheus antes, mas agora não consigo encontrá-los.

O Prometheus é pré-configurado para exportar métricas para o Cloud Monitoring como métricas externas. Quando os dados são exportados, o Monitoring cria o descritor de métricas apropriado para a métrica externa. Se nenhum dado desse tipo de métrica for gravado em até 24 semanas, o descritor de métricas estará sujeito à exclusão.

Não há garantia de que os descritores de métrica não usados sejam excluídos após 24 meses, mas o Monitoring se reserva o direito de excluir qualquer descritor de métrica do Prometheus que não tenha sido usado nos últimos 24 meses.

Política de suspensão de uso

A integração do Prometheus com o Cloud Monitoring está sujeita à política de suspensão de uso de agentes.