Nouveautés de l'Agent v6

Le fichier de configuration principal de l’Agent est désormais au format YAML et non au format INI, ceci afin de prendre en charge les configurations complexes tout en harmonisant l’expérience de configuration de l’Agent et des checks.

Agent v5 datadog.conf –> Agent v6 datadog.yaml

Pour appliquer le nouveau format et les nouveaux chemins de configuration de l’Agent, utilisez la commande suivante :

sudo -u dd-agent -- datadog-agent import

Cette commande parse le fichier datadog.conf existant et convertit les paramètres pris en charge au nouveau format dans datadog.yaml. Elle copie également les fichiers de configuration des checks activés. Pour en savoir plus, consultez Upgrade vers l’Agent v6 de Datadog.

Options

Les options de configuration de l’Agent suivantes ont été modifiées ou supprimées dans l’Agent v6. Les options de configuration supprimées ont été remplacées par d’autres options ou concernent des fonctionnalités qui fonctionnent différemment par rapport aux versions précédentes.

Options modifiées

Options supprimées

L’Agent v6 charge tous les fichiers YAML valides présents dans <RÉPERTOIRE_AGENT>/conf.d/<NOM_CHECK>.d/. Vous avez ainsi la possibilité de créer des configurations complexes décomposées en plusieurs fichiers.

Par exemple, les fichiers de configuration pour le http_check peuvent être :

/etc/datadog-agent/conf.d/http_check.d/
├── backend.yaml
└── frontend.yaml

L’Agent ne charge pas les fichiers de configuration présents dans les sous-répertoires du dossier <NOM_CHECK>.d. Par exemple, le fichier suivant ne sera pas chargé :

/etc/datadog-agent/conf.d/http_check.d/prod.d/
├── backend.yaml

Les fichiers de modèle Autodiscovery (auto_conf.yaml) sont également stockés dans le répertoire de configuration. Voici un exemple de dossier de configuration pour le check redisdb :

/etc/datadog-agent/conf.d/redisdb.d/
├── auto_conf.yaml
└── conf.yaml.example

Le nom des fichiers YAML dans un dossier <NOM_CHECK>.d n’a aucune importance : les fichiers doivent simplement avoir pour extension .yaml ou .yml. Le nom standard est conf.yaml.

Pour préserver la compatibilité avec les versions précédentes, l’Agent récupère toujours les fichiers de configuration au format <RÉPERTOIRE_AGENT>/conf.d/<NOM_CHECK>.yaml. Toutefois, la migration vers le nouveau format est fortement conseillée.

Options de configuration

L’Agent v6 prend en charge les options suivantes dans la section instance d’un check :

La plupart des variables d’environnement utilisées dans l’Agent v6 sont différentes de celles des versions précédentes. Consultez la liste des variables d’environnement pour l’Agent v6.

Remarque : DD_TAGS utilise les mêmes tags, mais ces derniers sont séparés par des espaces dans l’Agent v6. Dans les versions précédentes, ils étaient séparés par des virgules. Exemple pour l’Agent v6 : DD_TAGS="simple-tag-0 tag-key-1:tag-value-1"

Proxies

À partir de la v6.4.0+, les paramètres de proxy de l’Agent peuvent être remplacés via les variables d’environnement suivantes :

Les variables d’environnement standard (HTTP_PROXY, HTTPS_PROXY et NO_PROXY) sont prises en charge dans l’Agent v6, mais nous vous conseillons d’utiliser les variables DD_PROXY_*. Les variables DD_PROXY_* sont appliquées en priorité sur les autres.

Dans l’Agent v6, l’ordre de priorité des options de proxy est différent par rapport aux versions précédentes :

• L’Agent v6 applique les variables d’environnement en premier, puis le fichier de configuration.
• L’Agent v6 remplace les valeurs du fichier de configuration par celles de l’environnement. Par exemple, si les options proxy.http et proxy.https sont définies dans le fichier de configuration mais que seule la variable DD_PROXY_HTTPS est définie dans l’environnement, l’Agent applique la valeur https de l’environnement et la valeur http du fichier de configuration.

Des différences existent au niveau de la résolution du hostname entre l’Agent v5 et l’Agent v6. Pour en savoir plus, consultez la section Comment Datadog détermine-t-il le hostname de l’Agent.

Sous Linux, les changements majeurs dans l’Agent v6 sont les suivants :

• Seules les commandes de cycle de vie (start/stop/restart/status) doivent être exécutées avec sudo service/sudo initctl/sudo systemctl.
• Toutes les autres commandes doivent être invoquées avec le binaire de l’Agent, situé dans le PATH (/usr/bin) en tant que datadog-agent par défaut. La commande dd-agent n’est plus disponible.
• La sous-commande info a été renommée status.
• L’Agent v6 n’intègre pas de script SysV-init (anciennement situé à l’emplacement /etc/init.d/datadog-agent).

Commandes de cycle de vie du service

Les commandes de cycle de vie restent les mêmes si la commande du wrapper service est disponible sur votre système. Par exemple, sous Ubuntu, les commandes de cycle de vie sont les suivantes :

Si la commande du wrapper service n’est pas disponible sur votre système, utilisez :

• Sur les systèmes basés sur upstart : sudo start/stop/restart/status datadog-agent
• Sur les systèmes basés sur systemd : sudo systemctl start/stop/restart/status datadog-agent

Si vous ne savez pas quel système init votre distribution utilise par défaut, consultez le tableau ci-dessous :

Commandes de l’Agent

Avec l’Agent v6+, certaines fonctionnalités sont fournies par le binaire de l’Agent lui-même en tant que sous-commandes et ne doivent pas être invoquées avec service/systemctl/initctl. Voici quelques exemples :

Sous Windows, les changements majeurs dans l’Agent v6 sont les suivants :

• L’interface graphique de Datadog Agent Manager pour Windows utilisée par l’Agent v5 a été remplacée par une interface de gestion cross-platform qui s’utilise depuis un navigateur. Pour en savoir plus, consultez la section Datadog Agent Manager pour Windows.
• Le nom du fichier exécutable principal est agent.exe (contre ddagent.exe précédemment).
• Les commandes doivent être exécutées en utilisant la syntaxe "%PROGRAMFILES%\datadog\datadog agent\embedded\agent.exe" <COMMANDE> depuis une invite de commande avec droits Administrateur :
• Le type de démarrage du service Windows est défini sur « Automatique (début différé) ». Le service est démarré au lancement de Windows, mais après tous les autres services. Cela signifie que l’envoi des métriques est légèrement retardé après un redémarrage.
• L’interface graphique Windows et l’icône de la barre des menus sont implémentées séparément. Pour en savoir plus, consultez la section Datadog Agent Manager pour Windows.

Sous macOS, les changements majeurs dans l’Agent v6 sont les suivants :

• Les commandes de cycle de vie (auparavant datadog-agent start/stop/restart/status) sont remplacées par les commandes launchctl sur le service com.datadoghq.agent et doivent être exécutées depuis le compte utilisateur connecté. Vous pouvez également exécuter ces commandes depuis la barre des menus de l’Agent Datadog.
• Toutes les autres commandes peuvent toujours être exécutées avec le binaire datadog-agent situé dans le PATH (/usr/local/bin/) par défaut.
• La commande info a été renommée status.
• L’interface de configuration graphique est une application basée sur un navigateur. Pour y accéder, exécutez la commande datadog-agent launch-gui ou utilisez la barre des menus.

Exemples de changements :

L’Agent APM est intégré au package de l’Agent v6 sous Linux, macOS et Windows.

L’Agent APM est activé par défaut sous Linux. Pour l’activer sur une autre plateforme ou le désactiver sous Linux, modifiez la clé apm_config dans votre datadog.yaml :

apm_config:
  enabled: true

Si vous utilisez l’image Docker, l’Agent APM est désactivé par défaut. Activez-le en définissant DD_APM_ENABLED sur true. L’Agent écoute toutes les interfaces par défaut. Si vous souhaitez écouter le trafic non local sur une autre plateforme, définissez DD_APM_NON_LOCAL_TRAFFIC sur true. Pour en savoir plus, consultez Tracer des applications Docker.

L’Agent de processus est intégré au package de l’Agent v6 sous Linux uniquement.

L’Agent de processus n’est pas activé par défaut. Pour l’activer, modifiez votre datadog.yaml comme suit :

process_config:
  enabled: "true"

La valeur enabled est une chaîne avec les options suivantes :

• "true" : activer la collecte des processus et des conteneurs par l’Agent de processus.
• "false" (par défaut) : recueillir les conteneurs uniquement (lorsque cela est possible).
• "disabled" : ne pas exécuter l’Agent de processus.

L’Agent v6 prend en charge les versions 1.12 et ultérieures de Docker.

Le check Docker a été réécrit en Go pour tirer parti de l’architecture interne de l’Agent. La version Python (docker_daemon) est donc désormais obsolète.

Le nouveau check est nommé docker. La commande import de l’Agent permet d’importer les paramètres de l’ancienne configuration docker_daemon.yaml. Toutes les fonctionnalités ont été portées, à l’exception des suivantes :

• url, api_version et tags* sont obsolètes. Nous vous conseillons d’utiliser les variables d’environnement Docker standard.
• ecs_tags, performance_tags et container_tags sont obsolètes. Tous ces tags sont désormais recueillis par défaut.
• Il n’est plus possible d’utiliser collect_container_count pour activer la métrique docker.container.count. Vous devez utiliser docker.containers.running et .stopped.

Certaines options ont été déplacées du fichier docker_daemon.yaml vers le fichier datadog.yaml principal :

• collect_labels_as_tags a été renommé docker_labels_as_tags et prend désormais en charge les tags dotés d’une cardinalité élevée. Consultez la section Appliquer et extraire des tags pour en savoir plus.
• Les listes exclude et include ont été renommées ac_include et ac_exclude. Afin d’obtenir un filtrage cohérent entre tous les composants de l’Agent, le filtrage des tags arbitraires a été abandonné. Les seuls tags de filtrage pris en charge sont image (nom de l’image) et name (nom du conteneur). Le filtrage à l’aide d’expressions régulières est toujours disponible. Consultez Gestion de la découverte de conteneurs pour en savoir plus.
• L’option docker_root a été divisée en deux options : container_cgroup_root et container_proc_root.
• exclude_pause_container a été ajouté afin d’exclure les conteneurs en pause sur Kubernetes et Openshift (valeur par défaut : true).

L’Agent v6 prend en charge les versions 1.3 et ultérieures de Kubernetes.

L’intégration Kubernetes fournit des informations pertinentes en combinant :

• Les métriques du check Kubelet recueillies à partir du kubelet
• Les événements du check kubernetes_apiserver et les checks de service recueillis à partir du serveur d’API

La commande import de l’Agent (v6.2+) permet d’importer les paramètres de l’ancienne configuration kubernetes.yaml. Les options suivantes sont désormais obsolètes :

• Informations d’authentification au serveur d’API (api_server_url, apiserver_client_crt, apiserver_client_key, apiserver_ca_cert) : désormais, vous devez spécifier un fichier kubeconfig à l’Agent avec kubernetes_kubeconfig_path.
• use_histogram : contactez l’assistance Datadog pour déterminer l’alternative la plus adaptée à vos besoins.
• namespaces et namespace_name_regexp : l’Agent v6 recueille les métriques à partir de tous les espaces de nommage disponibles.

La nouvelle logique permet de rendre la collecte de métriques Prometheus compatible avec les versions 1.7.6+ de Kubernetes. Si vous utilisez une version plus ancienne ou que vous souhaitez rétablir la logique de collecte de cadvisor, définissez cadvisor_port sur 4194 (le port sur lequel votre kubelet expose cadvisor).

Le check kubernetes_state fonctionne avec l’Agent v5 ou l’Agent v6.

Tagging

Si l’Agent v5 recueillait automatiquement toutes les étiquettes de pod en tant que tags, l’Agent v6 utilise une liste d’autorisation. Pour modifier cette liste, utilisez l’option kubernetes_pod_labels_as_tags dans datadog.yaml. Consultez la documentation relative à l’application et à l’extraction des tags pour en savoir plus.

Les options et tags suivants sont désormais obsolètes :

• label_to_tag_prefix a été remplacée par kubernetes_pod_labels_as_tags.
• Les tags container_alias ne sont plus recueillis.
• kube_replicate_controller est uniquement ajouté si le pod a été créé par un replication controller. Utilisez plutôt le tag creator pertinent (kube_deployment, kube_daemon_set, etc.).

L’Agent v6 intègre JMXFetch. Les changements sont les suivants :

Jmxterm

L’Agent v6 n’intègre pas le JAR jmxterm. Pour télécharger et utiliser jmxterm, consultez le projet upstream.

Commandes de dépannage

La syntaxe des commandes de dépannage a été modifiée. Ces commandes sont valables pour les versions v6.2.0+ ; pour les versions plus anciennes, consultez la documentation relative au dépannage de l’Agent JMX :

Remarque : par défaut, ces commandes sont exécutées sur tous les checks JMX configurés. Pour spécifier un check, utilisez le flag --checks. Exemple : sudo datadog-agent jmx list collected --checks tomcat

Affecte uniquement les Agents Windows

Avec l’Agent v5 sous Windows, les métriques system.mem.pagefile.* affichent des unités incohérentes (erronées de 10^6).

Ce problème est résolu par la v6 de l’Agent pour Windows, mais l’erreur reste présente dans la v5 de l’Agent, pour des raisons de rétrocompatibilité. Par conséquent, les valeurs envoyées (et les moniteurs associés) sont amenées à changer après une mise à niveau vers la v6.

Lorsque vous utilisez Kubernetes, Autodiscovery extrait les informations du kubelet au lieu du daemon Docker. Autodiscovery peut ainsi fonctionner sans accéder au socket Docker. De plus, par défaut, les modèles Autodiscovery sont récupérés à partir des annotations des pods. Vous pouvez activer le config-provider docker pour utiliser les étiquettes de conteneurs, et remplacer l’écouteur kubelet par l’écouteur Docker si vous avez besoin d’utiliser Autodiscovery sur des conteneurs à court de pods.

Lorsque vous spécifiez des modèles Autodiscovery dans des annotations de pod, le préfixe du nom de l’annotation est ad.datadoghq.com/. Le préfixe d’annotation précédent (service-discovery.datadoghq.com/) est toujours pris en charge par l’Agent v6, mais cette compatibilité sera supprimée dans une future version.

Les modèles Autodiscovery dans les étiquettes Docker fonctionnent avec le même préfixe de nom, com.datadoghq.ad.*.

L’étiquette utilisée pour remplacer l’identificateur s’intitule com.datadoghq.ad.check.id, au lieu de com.datadoghq.sd.check.id, pour plus de cohérence. L’ancien nom est toujours pris en charge par l’Agent v6, mais cette compatibilité sera supprimée dans une future version.

Bien que l’Agent v6 prenne entièrement en charge les checks Python, certaines intégrations officielles de l’Agent v5 ont été supprimées ou remplacées :

• agent_metrics : supprimée
• docker_daemon : remplacée par le check Docker
• kubernetes : remplacée par les checks Kubernetes

La classe principale pour les checks Python (AgentCheck) est importée depuis datadog_checks.base.checks. Plusieurs fonctions ont été supprimées ou modifiées dans l’API de la classe. De plus, chaque instance de check est désormais sa propre instance de classe. Il n’est donc plus possible de partager un statut entre plusieurs instances.

Les méthodes suivantes de la classe AgentCheck ne sont pas implémentées :

• service_metadata
• get_service_metadata
• generate_historate_func
• generate_histogram_func
• stop

La signature de fonction des émetteurs de métriques a été modifiée :

# Anciennes versions
gauge(self, metric, value, tags=None, hostname=None, device_name=None, timestamp=None)

# Agent v6
gauge(self, name, value, tags=None, hostname=None, device_name=None)

Les méthodes suivantes ont été définitivement supprimées de la classe AgentCheck :

• _roll_up_instance_metadata
• instance_count
• is_check_enabled
• read_config
• set_check_version
• set_manifest_path
• _get_statistic_name_from_method
• _collect_internal_stats
• _get_internal_profiling_stats
• _set_internal_profiling_stats
• get_library_versions
• get_library_info
• from_yaml
• get_service_checks
• has_warnings
• get_metrics
• has_events
• get_events

Remarque : toutes les intégrations officielles ont été mises à jour pour supprimer les méthodes obsolètes. Ces changements n’affectent que les checks custom.

Priorité

Avec l’Agent v6, les checks officiels ont la priorité sur les checks custom (situés dans <RÉPERTOIRE_AGENT>/checks.d). Les checks custom portant le même nom qu’un check officiel sont ignorés.

Pour corriger la configuration de vos checks avec l’Agent v6, donnez un nouveau nom unique aux checks custom affectés, puis renommez les fichiers de configuration .yaml associés.

Dépendances

Si vous utilisez des checks custom, il est possible que votre code fasse appel à du code Python qui n’est plus intégré à l’Agent v6. Les packages suivants ne sont plus inclus dans l’Agent :

• backports.ssl-match-hostname
• datadog
• decorator
• future
• futures
• google-apputils
• pycurl
• pyOpenSSL
• python-consul
• python-dateutil
• python-etcd
• python-gflags
• pytz
• PyYAML
• rancher-metadata
• tornado
• uptime
• websocket-client

Si votre code fait appel à l’un de ces packages, installez le package manquant en exécutant :

sudo -u dd-agent -- /opt/datadog-agent/embedded/bin/pip install <NOM_PACKAGE>

De la même manière, vous avez peut-être ajouté un package PIP pour répondre à une exigence d’un check custom lorsque vous utilisiez l’Agent v5. Si le package PIP ajouté avait des dépendances internes avec des packages intégrés à l’Agent v5 (voir la liste ci-dessus), ces dépendances seront perdues après un passage à l’Agent v6. Installez les dépendances manquantes comme décrit ci-dessus.