Recueillez vos métriques Prometheus et OpenMetrics exposées à partir de votre application exécutée dans Kubernetes à l’aide de l’Agent Datadog et de l’intégration Datadog/OpenMetrics ou Datadog/Prometheus.

Présentation

Depuis la version 6.5.0, l’Agent inclut des checks OpenMetrics et Prometheus capables de scraper les endpoints Prometheus. 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. Pour en savoir plus sur l’utilisation avancée de l’interface OpenMetricsCheck et le développement d’un check custom, consultez la section Outils de développement. N’utilisez le check Prometheus que lorsque l’endpoint de métriques ne prend pas en charge un format texte.

Cette page décrit les principes d’utilisation de base de ces checks. Ils vous permettent de scraper des métriques custom à partir d’endpoints Prometheus.

Pour obtenir une explication sur le mappage de métriques Prometheus et OpenMetrics avec des métriques Datadog, consultez le guide dédié.

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 :

# (...)
metadata:
  #(...)
  annotations:
    ad.datadoghq.com/<IDENTIFICATEUR_CONTENEUR>.checks: |
      {
        "openmetrics": {
          "init_config": {},
          "instances": [
            {
              "openmetrics_endpoint": "http://%%host%%:%%port%%/<ENDPOINT_PROMETHEUS> ",
              "namespace": "<PRÉFIXE_ESPACENOMMAGE_MÉTRIQUES_POUR_DATADOG>",
              "metrics": [{"<MÉTRIQUES_À_RÉCUPÉRER>":"<NOUVEAU_NOM_MÉTRIQUE>"}]
            }
          ]
        }
      }      

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

# (...)
metadata:
  #(...)
  annotations:
    ad.datadoghq.com/<IDENTIFICATEUR_CONTENEUR>.check_names: |
      ["openmetrics"]      
    ad.datadoghq.com/<IDENTIFICATEUR_CONTENEUR>.init_configs: |
      [{}]      
    ad.datadoghq.com/<IDENTIFICATEUR_CONTENEUR>.instances: |
      [
        {
          "openmetrics_endpoint": "http://%%host%%:%%port%%/<ENDPOINT_PROMETHEUS> ",
          "namespace": "<PRÉFIXE_ESPACENOMMAGE_MÉTRIQUES_POUR_DATADOG>",
          "metrics": [{"<MÉTRIQUES_À_RÉCUPÉRER>":"<NOUVEAU_NOM_MÉTRIQUE>"}]
        }
      ]      
spec:
  containers:
    - name: '<IDENTIFICATEUR_CONTENEUR>'

Les placeholders à configurer sont les suivants :

Le paramètre metrics correspond à la liste des métriques à récupérer sous forme de métriques custom. Ajoutez chaque métrique à récupérer et le nom de métrique souhaité dans Datadog sous la forme de paires key/value : {"<MÉTRIQUE_À_RÉCUPÉRER>":"<NOUVEAU_NOM_MÉTRIQUE>"}. Il est également possible de fournir une liste de noms de métriques sous forme de chaînes, qui seront interprétées en tant qu’expressions régulières, afin de récupérer les métriques de votre choix avec leur nom actuel. Si vous souhaitez récupérer toutes les métriques, utilisez "*" au lieu de ".*".

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.

Prise en main

Collecte de métriques simple

1. Lancez l’Agent Datadog.

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

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

     # (...)
    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
   

3. 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 des annotations Prometheus

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.

Configuration de base

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

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

- 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

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

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

- name: DD_PROMETHEUS_SCRAPE_CHECKS
  value: "[{\"autodiscovery\":{\"kubernetes_annotations\":{\"exclude\":{\"prometheus.io/scrape\":\"false\"},\"include\":{\"prometheus.io/scrape\":\"true\"}}}}]"

- 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.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Recueillir les logs de votre applicationDOCUMENTATION Recueillir les traces de vos applicationsDOCUMENTATION Recueillir automatiquement les métriques et les logs de vos applicationsDOCUMENTATION Limiter la collecte de données à un sous-ensemble de conteneursDOCUMENTATION Attribuer des tags à toutes les données envoyées par un conteneurDOCUMENTATION Mappage de métriques Prometheus avec des métriques DatadogDOCUMENTATION