Collecte de métriques Prometheus et OpenMetrics avec Kubernetes

Docs > Surveillance des conteneurs > Kubernetes > Collecte de métriques Prometheus et OpenMetrics avec Kubernetes

Présentation

Collectez les métriques Prometheus et OpenMetrics exposées par votre application s’exécutant dans Kubernetes à l’aide de l’Agent Datadog et des intégrations OpenMetrics ou Prometheus. Par défaut, toutes les métriques récupérées par la vérification Prometheus générique sont considérées comme des métriques personnalisées.

Depuis la version 6.5.0, l’Agent inclut les vérifications OpenMetrics et Prometheus, capables d’interroger des endpoints Prometheus. Pour un usage avancé de l’interface OpenMetricsCheck, y compris la création d’une vérification personnalisée, consultez la section Outils pour développeurs.

Cette page explique l’utilisation de base de ces checks, qui vous permettent d’interroger des métriques personnalisées à partir de endpoints Prometheus. Pour une explication du mappage entre les métriques Prometheus et celles de Datadog, consultez le guide Mappage de métriques Prometheus avec des métriques Datadog.

Remarque : nous vous conseillons d’utiliser le check OpenMetrics du fait de son efficacité accrue et de sa prise en charge complète du format texte Prometheus. N’utilisez le check Prometheus que lorsque l’endpoint de métriques ne prend pas en charge un format texte.

Configuration

Installation

Déployez l’Agent Datadog dans votre cluster Kubernetes. Les checks OpenMetrics et Prometheus sont inclus dans le paquet de l’Agent Datadog : vous n’avez donc rien d’autre à installer sur vos conteneurs ou vos hosts.

Configuration

Configurez votre check OpenMetrics ou Prometheus à l’aide de la fonctionnalité Autodiscovery, en appliquant les annotations suivantes à votre pod exposant les métriques OpenMetrics/Prometheus :

Remarque : les annotations AD v2 ont été ajoutées dans la version 7.36 de l’Agent Datadog afin de simplifier la configuration de l’intégration. Pour les versions précédentes de l’Agent Datadog, utilisez les annotations AD v1.

# (...)
metadata:
  #(...)
  annotations:
    ad.datadoghq.com/<CONTAINER_NAME>.checks: |
      {
        "openmetrics": {
          "init_config": {},
          "instances": [
            {
              "openmetrics_endpoint": "http://%%host%%:%%port%%/<PROMETHEUS_ENDPOINT> ",
              "namespace": "<METRICS_NAMESPACE_PREFIX_FOR_DATADOG>",
              "metrics": [{"<METRIC_TO_FETCH>":"<NEW_METRIC_NAME>"}]
            }
          ]
        }
      }      

spec:
  containers:
    - name: '<CONTAINER_NAME>'

# (...)
metadata:
  #(...)
  annotations:
    ad.datadoghq.com/<CONTAINER_NAME>.check_names: |
      ["openmetrics"]      
    ad.datadoghq.com/<CONTAINER_NAME>.init_configs: |
      [{}]      
    ad.datadoghq.com/<CONTAINER_NAME>.instances: |
      [
        {
          "openmetrics_endpoint": "http://%%host%%:%%port%%/<PROMETHEUS_ENDPOINT> ",
          "namespace": "<METRICS_NAMESPACE_PREFIX_FOR_DATADOG>",
          "metrics": [{"<METRIC_TO_FETCH>":"<NEW_METRIC_NAME>"}]
        }
      ]      
spec:
  containers:
    - name: '<CONTAINER_NAME>'

Les placeholders à configurer sont les suivants :

Placeholder	Rôle
`<CONTAINER_NAME>`	Correspond au nom du conteneur qui expose les métriques.
`<ENDPOINT_PROMETHEUS>`	Le chemin d’URL pour les métriques traitées par le conteneur, au format Prometheus.
`<PRÉFIXE_ESPACENOMMAGE_MÉTRIQUES_POUR_DATADOG>`	L’espace de nommage spécifié ici sera ajouté comme préfixe à chaque métrique lors de son affichage dans Datadog.
`<MÉTRIQUE_À_RÉCUPÉRER>`	La clé de la métrique Prometheus à récupérer à partir de l’endpoint Prometheus.
`<NOUVEAU_NOM_MÉTRIQUE>`	Remplace la clé de métrique `<MÉTRIQUE_À_RÉCUPÉRER>` par le `<NOUVEAU_NOM_MÉTRIQUE>` dans Datadog.

La configuration metrics est une liste de métriques à récupérer en tant que métriques personnalisées. Indiquez chaque métrique à collecter ainsi que le nom souhaité dans Datadog sous forme de paires clé-valeur, par exemple : {"<METRIC_TO_FETCH>":"<NEW_METRIC_NAME>"}. Pour éviter des frais excessifs liés aux métriques personnalisées, Datadog recommande de limiter la portée aux seules métriques nécessaires. Vous pouvez également fournir une liste de noms de métriques sous forme de chaînes de caractères, interprétées comme des expressions régulières, pour collecter les métriques souhaitées avec leur nom d’origine. Pour récupérer toutes les métriques, utilisez ".*" plutôt que "*".

Remarque : les expressions régulières peuvent entraîner l’envoi d’un volume important de métriques custom.

Pour obtenir la liste complète des paramètres disponibles pour les instances, notamment namespace et metrics, consultez l’exemple de configuration openmetrics.d/conf.yaml.

Remarque : la vérification est limitée par défaut à 2 000 métriques. Utilisez le paramètre optionnel max_returned_metrics pour modifier cette limite.

Prise en main

Collecte simple de métriques (OpenMetrics Check)

Lancez l’Agent Datadog.

Utilisez le fichier prometheus.yaml de Prometheus pour lancer un exemple de déploiement Prometheus qui comporte la configuration Autodiscovery sur le pod :

  # (...)
 spec:
   template:
     metadata:
       annotations:
         ad.datadoghq.com/prometheus-example.checks: |
           {
             "openmetrics": {
               "instances": [
                 {
                   "openmetrics_endpoint": "http://%%host%%:%%port%%/metrics",
                   "namespace": "documentation_example_kubernetes",
                   "metrics": [
                       {"promhttp_metric_handler_requests": "handler.requests"},
                       {"promhttp_metric_handler_requests_in_flight": "handler.requests.in_flight"},
                       "go_memory.*"
                     ]
                 }
               ]
             }
           }           
     spec:
       containers:
       - name: prometheus-example
       # (...)

  # (...)
 spec:
   template:
     metadata:
       annotations:
         ad.datadoghq.com/prometheus-example.check_names: |
           ["openmetrics"]           
         ad.datadoghq.com/prometheus-example.init_configs: |
           [{}]           
         ad.datadoghq.com/prometheus-example.instances: |
           [
             {
               "openmetrics_endpoint": "http://%%host%%:%%port%%/metrics",
               "namespace": "documentation_example_kubernetes",
               "metrics": [
                 {"promhttp_metric_handler_requests": "handler.requests"},
                 {"promhttp_metric_handler_requests_in_flight": "handler.requests.in_flight"},
                 "go_memory.*"
               ]
             }
           ]           
     spec:
       containers:
       - name: prometheus-example
       # (...)

Commande pour créer le déploiement Prometheus :

kubectl create -f prometheus.yaml

Rendez-vous sur votre page Fleet Automation et filtrez par l’intégration openmetrics pour consulter des informations détaillées sur l’état de vos vérifications.
Accédez à votre page Metric summary pour visualiser les métriques recueillies à partir de cet exemple de pod. Cette configuration recueillera les métriques promhttp_metric_handler_requests, promhttp_metric_handler_requests_in_flight, ainsi que toutes les métriques commençant par go_memory qui sont exposées.

Collecte de métriques avec les annotations Prometheus (Prometheus Check)

Grâce à la fonctionnalité Autodiscovery Prometheus, l’Agent Datadog peut détecter les annotations Prometheus natives (comme prometheus.io/scrape, prometheus.io/path ou prometheus.io/port) et planifier automatiquement des checks OpenMetrics de façon à recueillir des métriques Prometheus dans Kubernetes.

Prérequis

Agent Datadog v7.27+ ou v6.27+ (pour les checks de pod)
Agent de cluster Datadog v1.11+ (pour les checks de service et d’endpoint)

Configuration

Il est conseillé de commencer par vérifier quels pods et services contiennent l’annotation prometheus.io/scrape=true avant d’activer cette fonctionnalité. Pour ce faire, utilisez les commandes suivantes :

kubectl get pods -o=jsonpath='{.items[?(@.metadata.annotations.prometheus\.io/scrape=="true")].metadata.name}' --all-namespaces

kubectl get services -o=jsonpath='{.items[?(@.metadata.annotations.prometheus\.io/scrape=="true")].metadata.name}' --all-namespaces

Une fois la fonctionnalité Prometheus Scrape activée, l’Agent Datadog recueille des métriques custom à partir de ces ressources. Si vous ne souhaitez pas recueillir de métriques custom à partir de ces ressources, vous pouvez supprimer cette annotation ou mettre à jour les règles Autodiscovery comme décrit dans la section Configuration avancée.

Remarque : l’activation de cette fonctionnalité sans configuration avancée peut entraîner une augmentation importante du nombre de métriques personnalisées, avec des conséquences sur la facturation. Consultez la section de configuration avancée pour apprendre à limiter la collecte à un sous-ensemble de conteneurs/pods/services.

Configuration de base

Mettez à jour la configuration de votre opérateur Datadog pour inclure ce qui suit :

datadog-agent.yaml

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    credentials:
      apiKey: <DATADOG_API_KEY>

  features:
    prometheusScrape:
      enabled: true
      enableServiceEndpoints: true

After making your changes, apply the new configuration by using the following command:

kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

Mettez à jour votre configuration Helm pour inclure ce qui suit :

datadog-values.yaml

datadog:
  # (...)
  prometheusScrape:
    enabled: true
    serviceEndpoints: true
  # (...)

After making your changes, upgrade your Datadog Helm chart using the following command:

helm upgrade -f datadog-values.yaml <RELEASE NAME> datadog/datadog

Dans votre manifeste DaemonSet pour l’Agent, daemonset.yaml, ajoutez les variables d’environnement suivantes pour le conteneur de l’Agent :

- name: DD_PROMETHEUS_SCRAPE_ENABLED
  value: "true"
- name: DD_PROMETHEUS_SCRAPE_VERSION
  value: "2"

Si l’Agent de cluster est activé, à l’intérieur de son manifeste cluster-agent-deployment.yaml, ajoutez les variables d’environnement suivantes pour le conteneur de l’Agent de cluster :

- name: DD_PROMETHEUS_SCRAPE_ENABLED
  value: "true"
- name: DD_PROMETHEUS_SCRAPE_SERVICE_ENDPOINTS
  value: "true"

Grâce à ces lignes, l’Agent Datadog détecte les pods qui possèdent des annotations Prometheus natives et génère les checks OpenMetrics correspondants.

En outre, lorsqu’il est activé, l’Agent de cluster Datadog détecte également les services qui possèdent des annotations Prometheus natives et génère les checks OpenMetrics correspondants.

prometheus.io/scrape=true : requis.
prometheus.io/path : facultatif (valeur par défaut : /metrics).
prometheus.io/port : facultatif (valeur par défaut : %%port%%). Template variable remplacée par le port du conteneur ou service.

Ces paramètres permettent de générer un check qui recueille toutes les métriques exposées, en se basant sur la configuration par défaut de l’intégration OpenMetrics.

Configuration avancée

Vous pouvez configurer davantage la collecte de métriques (au-delà des annotations Prometheus natives) à l’aide du champ additionalConfigs.

Configurations de checks OpenMetrics supplémentaires

Utilisez additionalConfigs.configurations pour définir des configurations de checks OpenMetrics supplémentaires. Consultez la liste des paramètres OpenMetrics pris en charge que vous pouvez passer via additionalConfigs.

Règles personnalisées d’Autodiscovery

Utilisez additionalConfigs.autodiscovery pour définir des règles personnalisées d’Autodiscovery. Ces règles peuvent reposer sur les noms de conteneurs, les annotations Kubernetes, ou les deux.

additionalConfigs.autodiscovery.kubernetes_container_names

Une liste de noms de conteneurs à cibler, au format expression régulière.

additionalConfigs.autodiscovery.kubernetes_annotations

Deux maps (include et exclude) d’annotations permettant de définir des règles de découverte.

Par défaut :

include:
   prometheus.io/scrape: "true"
exclude:
   prometheus.io/scrape: "false"

Si kubernetes_container_names et kubernetes_annotations sont tous deux définis, une logique ET est appliquée (les deux règles doivent correspondre).

Exemples

La configuration suivante cible un conteneur nommé my-app exécuté dans un pod avec l’annotation app=my-app. La configuration du check OpenMetrics est personnalisée pour activer l’option send_distribution_buckets et définir un délai d’attente personnalisé de 5 secondes.

Mettez à jour la configuration de votre opérateur Datadog pour inclure ce qui suit :

datadog-agent.yaml

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    credentials:
      apiKey: <DATADOG_API_KEY>

  features:
    prometheusScrape:
      enabled: true
      enableServiceEndpoints: true
      additionalConfigs: |-
        - autodiscovery:
            kubernetes_container_names:
              - my-app
            kubernetes_annotations:
              include:
                app: my-app
          configurations:
            - timeout: 5
              send_distribution_buckets: true        

datadog-values.yaml

datadog:
  # (...)
  prometheusScrape:
    enabled: true
    serviceEndpoints: true
    additionalConfigs:
      - autodiscovery:
          kubernetes_container_names:
            - my-app
          kubernetes_annotations:
            include:
              app: my-app
        configurations:
          - timeout: 5
            send_distribution_buckets: true

Pour DaemonSet, la configuration avancée se définit dans la variable d’environnement DD_PROMETHEUS_SCRAPE_CHECKS, et non dans un champ additionalConfigs.

- name: DD_PROMETHEUS_SCRAPE_ENABLED
  value: "true"
- name: DD_PROMETHEUS_SCRAPE_CHECKS
  value: "[{\"autodiscovery\":{\"kubernetes_annotations\":{\"include\":{\"app\":\"my-app\"}},\"kubernetes_container_names\":[\"my-app\"]},\"configurations\":[{\"send_distribution_buckets\":true,\"timeout\":5}]}]"
- name: DD_PROMETHEUS_SCRAPE_VERSION
  value: "2"

Proposer une intégration personnalisée comme intégration officielle

Par défaut, toutes les métriques récupérées par le check Prometheus générique sont considérées comme des métriques custom. Si vous surveillez un logiciel prêt à l’emploi et que vous pensez qu’il mérite une intégration officielle, n’hésitez pas à apporter votre contribution !

Les intégrations officielles utilisent des répertoires dédiés. Le check générique intègre un système de création d’instances qui se charge de coder en dur la configuration par défaut et les métadonnées des métriques. Reportez-vous au référentiel sur l’intégration kube-proxy pour obtenir un exemple.