Como usar o Prometheus

O Prometheus é uma ferramenta de monitoramento usada com frequência no Kubernetes. Ao configurar o Cloud Operations para GKE e incluir o suporte do Prometheus, as métricas geradas pelos serviços que usam o formato de exposição Prometheus podem ser exportadas do cluster e visualizadas como métricas externas no Cloud Monitoring.

Nesta página, explicamos como configurar e usar o Prometheus com o Cloud Operations para GKE. O código-fonte da integração está disponível em modo público.

Antes de começar

Não é possível configurar clusters usando o Logging e o Monitoring legados com o Prometheus. Saiba mais sobre o Logging e o Monitoring legados em Guias de instruções do Logging e do Monitoring legados.

Esta página não contém instruções para instalar um servidor Prometheus ou para criar um cluster do GKE usando o Cloud Operations para GKE.

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:

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
    #!/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 Monitoring:

    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:

    Exemplo de métrica do Prometheus para um contêiner do Kubernetes.

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.

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.