Utiliser Prometheus

Prometheus est un outil de surveillance souvent employé avec Kubernetes. Si vous configurez Kubernetes Engine Operations et faites en sorte qu'il soit compatible avec Prometheus, les métriques générées par les services utilisant le format d'exposition Prometheus peuvent être exportées à partir du cluster et rendues visibles en tant que métriques externes dans Cloud Monitoring.

Cette page explique comment configurer et utiliser Prometheus avec Kubernetes Engine Operations. Le code source servant à l'intégration est disponible publiquement.

Avant de commencer

Vous ne pouvez pas configurer de clusters si vous utilisez les anciennes fonctionnalités Logging et Monitoring avec Prometheus. Pour plus d'informations sur les anciennes fonctionnalités Logging et Monitoring, accédez à la page Guides d'utilisation des anciens Logging et Monitoring.

Cette page ne contient pas d'instructions sur l'installation d'un serveur Prometheus ni sur la création d'un cluster GKE à l'aide de Kubernetes Engine Operations.

Avant d'installer le collecteur Stackdriver, vérifiez attentivement les points suivants:

Installer le collecteur

Pour déployer le collecteur Stackdriver, procédez comme suit :

  1. Identifiez l'objet à mettre à jour grâce à son nom et au type de contrôleur. Seuls les types de contrôleur deployment et statefulset sont acceptés.

  2. Définissez les variables d'environnement suivantes :

    • KUBE_NAMESPACE : espace de noms sur lequel exécuter le script.
    • KUBE_CLUSTER : paramètre de nom de cluster du side-car.
    • GCP_REGION : paramètre de région Google Cloud du side-car.
    • GCP_PROJECT : paramètre de projet Google Cloud du side-car.
    • DATA_DIR : répertoire de données du side-car. Il s'agit du répertoire qui héberge le volume partagé dans lequel votre serveur Prometheus écrit. Dans les instructions suivantes, cette variable est définie sur la valeur /data.
    • DATA_VOLUME : nom du volume partagé dans le répertoire DATA_DIR contenant les données de Prometheus. Dans les instructions suivantes, cette variable est définie sur data-volume.
    • SIDECAR_IMAGE_TAG : version de l'image Docker pour le side-car Prometheus. La dernière version est disponible dans Container Registry.
  3. Exécutez le script suivant et spécifiez les deux paramètres identifiés lors de l'étape initiale de cette procédure :

    #!/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}
    "
    

Une fois le script correctement exécuté, le collecteur Stackdriver est ajouté en tant que side-car aux pods de l'objet identifié lors de la première étape de la procédure. Les deux lignes du script qui sont commentées ne sont pas pertinentes pour la collecte de données métriques à partir de clusters GKE. Toutefois, elles sont pertinentes lorsque vous souhaitez renseigner une ressource MonitoredResource générique.

Vous devez effectuer des étapes supplémentaires pour que les modifications apportées à la configuration soient permanentes. Ces étapes sont décrites dans les sections suivantes.

Valider l'installation

Pour valider l'installation du collecteur Stackdriver, exécutez la commande suivante :

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"}}'
  • Lorsque le side-car Prometheus est correctement installé, le résultat du script répertorie l'image utilisée à partir de Container Registry. Dans l'exemple suivant, la version de l'image est 0.4.3. Dans votre installation, la version peut être différente :

    stackdriver-prometheus-sidecar exists. Image: gcr.io/stackdriver-prometheus/stackdriver-prometheus-sidecar:0.4.3
    
  • Sinon, le résultat du script indique :

    stackdriver-prometheus-sidecar does not exist.
    

Pour déterminer si votre charge de travail est à jour et disponible, exécutez la commande suivante :

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

Rendre permanentes les modifications apportées à la configuration

Après avoir vérifié que le collecteur a bien été installé, mettez à jour la configuration du cluster pour rendre les modifications permanentes :

  1. Configurez le serveur Prometheus de sorte qu'il écrive sur un volume partagé. Dans les exemples d'étapes suivants, nous partons du principe que DATA_DIR a été défini sur /data et que DATA_VOLUME a été défini sur data-volume :

    1. Vérifiez que le pod Prometheus comprend un volume partagé :

      volumes:
        - name: data-volume
          emptyDir: {}
      
    2. Faites en sorte que Prometheus installe le volume sous /data :

      volumeMounts:
      - name: data-volume
        mountPath: /data
      
    3. Indiquez au serveur Prometheus d'écrire sur le volume partagé dans /data. Pour ce faire, ajoutez le code suivant à son conteneur args :

      --storage.tsdb.path=/data
      
  2. À l'aide des outils dont vous vous servez pour gérer la configuration de vos charges de travail, appliquez de nouveau la configuration au cluster et incluez le conteneur collecteur Stackdriver comme side-car dans la nouvelle configuration :

    - 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
    

    Dans l'expression précédente, [API_ADDRESS] fait référence à l'adresse de l'API Prometheus, qui est généralement http://127.0.0.1:9090.

Pour plus de détails sur la configuration du collecteur, reportez-vous à la documentation relative au side-car Stackdriver Prometheus.

Afficher les métriques

Prometheus est configuré pour exporter des métriques vers la suite d'opérations de Google Cloud en tant que métriques externes.

Pour afficher ces métriques, procédez comme suit :

  1. Dans Cloud Console, sélectionnez Monitoring :

    Accéder à Monitoring

  2. Dans le volet de navigation Monitoring, cliquez sur Metrics Explorer (Explorateur de métriques).

  3. Dans le menu Find resource type and metric (Rechercher un type de ressource et une métrique) :

    • Sélectionnez Kubernetes Container (Conteneur Kubernetes) (k8s_container) pour le champ Resource type (Type de ressource).
    • Pour le champ Metric (Métrique), sélectionnez-en une dotée du préfixe external/prometheus/ Par exemple, vous pouvez sélectionner external/prometheus/go_memstats_alloc_bytes.

    Dans l'exemple suivant, un filtre a été ajouté de façon à afficher les métriques d'un cluster spécifique. Le filtrage par nom de cluster est utile lorsque vous disposez de plusieurs clusters dans un espace de travail :

    Exemple de métrique Prometheus pour un conteneur Kubernetes.

Gérer les coûts des métriques dérivées de Prometheus

En règle générale, Prometheus est configuré pour collecter toutes les métriques exportées par votre application et, par défaut, le collecteur Stackdriver envoie ces métriques à Cloud Monitoring. Cette collecte inclut les métriques exportées par les bibliothèques dont dépend votre application. Par exemple, la bibliothèque cliente Prometheus exporte de nombreuses métriques sur l'environnement d'application.

Vous pouvez configurer des filtres dans le collecteur Stackdriver pour sélectionner les métriques qui doivent être ingérées dans Cloud Monitoring. Par exemple, pour importer seulement les métriques générées par kubernetes-pods et kubernetes-service-endpoints, ajoutez l'instruction --include suivante lors du démarrage du side-car Stackdriver Prometheus :

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

Pour en savoir plus, consultez la documentation sur le side-car Stackdriver Prometheus.

Vous pouvez également estimer l'impact de ces métriques sur votre facture.

Problèmes d'intégration de Prometheus

Aucune donnée n'apparaît dans Cloud Monitoring.

Si aucune donnée ne s'affiche dans Cloud Monitoring une fois la procédure d'installation exécutée, recherchez les messages d'erreur dans les journaux du collecteur.

Si les journaux ne contiennent aucun message d'échec évident, activez la journalisation des données de débogage en transmettant l'option --log.level=debug au collecteur. Vous devez redémarrer le collecteur pour que la modification de la journalisation prenne effet. Après avoir redémarré le collecteur, recherchez les messages d'erreur dans les journaux du collecteur.

Pour vérifier que les données sont envoyées à Cloud Monitoring, vous pouvez envoyer les requêtes aux fichiers à l'aide du paramètre de ligne de commande --stackdriver.store-in-files-directory, puis inspecter les fichiers de ce répertoire.

Autorisation refusée

Si vous voyez des erreurs "Autorisation refusée" de l'API Monitoring, consultez les exigences décrites dans la section Avant de commencer. Assurez-vous que vos comptes de service disposent de l'autorisation appropriée. Si vous utilisez Workload Identity, veillez à créer une relation entre les KSA et les GSA.

J'utilise des règles d'enregistrement, et les métriques n'apparaissent pas dans Cloud Monitoring.

Lorsque vous utilisez des règles d'enregistrement, ingérez si possible la métrique brute dans Cloud Monitoring et utilisez les fonctionnalités de Cloud Monitoring pour agréger les données lorsque vous créez un graphique ou un tableau de bord.

Si l'ingestion de la métrique brute n'est pas possible, ajoutez une entrée static_metadata dans la configuration du collecteur. Cette option nécessite de conserver les étiquettes job et instance. Par exemple, la configuration actuelle est valide :

  • Configuration du serveur 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)
    
  • Votre configuration du collecteur Prometheus:

    static_metadata:
      - metric: backlog_avg_10m
        type: gauge
    

Les règles d'enregistrement qui modifient ou suppriment les étiquettes job ou instance ne sont pas acceptées.

Mes métriques ne comportent pas les étiquettes Prometheus job et instance.

Le collecteur Stackdriver pour Prometheus crée une MonitoredResource Cloud Monitoring pour vos objets Kubernetes à partir de libellés Prometheus connus. Lorsque vous modifiez les descripteurs d'étiquettes, le collecteur ne peut pas écrire les métriques dans Monitoring.

Des erreurs telles que "série temporelle en double" ou "écritures non ordonnées" s'affichent dans les journaux.

Ces erreurs sont causées par une double écriture de données métriques dans la même série temporelle. Elles se produisent lorsque vos points de terminaison Prometheus utilisent deux fois la même métrique à partir d'une seule ressource surveillée Cloud Monitoring.

Par exemple, un conteneur Kubernetes peut envoyer des métriques Prometheus sur plusieurs ports. Comme la ressource surveillée k8s_container de Monitoring ne différencie pas les ressources en fonction du port, Monitoring détecte que vous écrivez deux points sur la même série temporelle. Pour éviter cette situation, ajoutez dans Prometheus une étiquette de métrique qui différencie la série temporelle. Par exemple, vous pouvez utiliser l'étiquette __meta_kubernetes_pod_annotation_prometheus_io_port, car elle reste constante au fur et à mesure des redémarrages du conteneur.

Je vois des erreurs telles que "le type de métrique est X, mais il devrait être Y" dans les journaux.

Ces erreurs sont causées par la modification du type de métrique Prometheus pour un descripteur de métrique existant. Les métriques Cloud Monitoring correspondent à des types stricts et ne permettent pas de modifier leur type entre jauge, compteur et autres.

Pour modifier le type d'une métrique, vous devez supprimer les descripteurs de métrique correspondants et créer un nouveau descripteur. La suppression d'un descripteur de métrique rend inaccessibles les données de séries temporelles existantes.

Je suis sûr d'avoir déjà vu des types de métriques Prometheus, mais je ne les trouve plus.

Prometheus est préconfiguré pour exporter les métriques vers Cloud Monitoring en tant que métriques externes. Une fois les données exportées, Monitoring crée le descripteur approprié pour la métrique externe. Si aucune donnée de ce type de métrique n'est écrite pendant au moins 24 mois, le descripteur de la métrique est sujet à suppression.

Il n'y a aucune garantie que les descripteurs de métriques inutilisés soient supprimés après 24 mois, mais Monitoring se réserve le droit de supprimer tout descripteur de métrique Prometheus qui n'a pas été utilisé au cours des 24 mois précédents.

Règle relative aux abandons

L'intégration de Prometheus à Cloud Monitoring est soumise au Règlement relatif aux abandons des agents.