Como usar o Prometheus

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

Nesta página, você aprende a configurar e usar o Prometheus com o Stackdriver Kubernetes Engine Monitoring. 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 Stackdriver legado com o Prometheus. Para ver mais informações sobre o Stackdriver legado, acesse Guias de instruções do Stackdriver legado.

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

Antes de instalar o coletor, leia com atenção 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:

    #!/bin/sh
    
    set -e
    set -u
    
    usage() {
      echo -e "Usage: $0 <deployment|statefulset> <name>\n"
    }
    
    if [  $# -le 1 ]; then
      usage
      exit 1
    fi
    
    # 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}
    "
    

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 exists."}}{{range .spec.template.spec.containers}}{{if eq .name "stackdriver-prometheus-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 é configurado para exportar métricas para o Monitoring como métricas externas.

Para visualizar essas métricas:

  1. No Console do Cloud, selecione Monitoring:

    Acessar o Monitoring

  2. Faça o seguinte:

    • Se Metrics Explorer estiver listado no painel de navegação, clique em Metrics Explorer.

    • Caso contrário, selecione Resources e, em seguida, 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 em um espaço de trabalho:

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

Gerenciamento de custos para métricas derivadas do Prometheus

É comum o Prometheus ser configurado para coletar todas as métricas exportadas pelo seu aplicativo e, por padrão, o coletor do Stackdriver envia essas métricas ao Stackdriver. 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.

Configure filtros no coletor do Stackdriver para selecionar quais métricas são ingeridas no Stackdriver. 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 Stackdriver Monitoring.

Se nenhum dado aparecer no Stackdriver Monitoring depois você ter passado 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 foram enviados ao Stackdriver Monitoring, envie as solicitações para os arquivos usando o parâmetro de linha de comando --stackdriver.store-in-files-directory e, em seguida, inspecione os arquivos nesse diretório.

Estou usando regras de gravação e as métricas não aparecem no Stackdriver Monitoring.

Quando estiver usando papéis de gravação, se possível, ingira a métrica bruta no Stackdriver Monitoring e use os recursos do Stackdriver Monitoring para agregar os dados ao 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 no Stackdriver:

    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 Prometheus no Stackdriver cria um MonitoredResource do Stackdriver Monitoring para seus objetos do Kubernetes a partir de rótulos 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 Stackdriver 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 Stackdriver Monitoring têm uma forma estrita e não são compatíveis com a alteração do tipo de métrica entre o medidor, o contador etc.

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 é programado para exportar métricas ao Stackdriver 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é seis semanas, o descritor de métricas estará sujeito à exclusão.

Não é certo que os descritores de métricas não utilizados sejam excluídos após seis semanas, mas o Monitoring reserva-se o direito de excluir qualquer descritor de métrica do Prometheus que não tenha sido usado nas últimas seis semanas.

Política de suspensão de uso

A integração do Stackdriver ao Prometheus está sujeita à política de suspensão de uso de agentes do Stackdriver.