Écrire un check custom d'Agent

Docs > Extend Datadog > Custom Checks > Écrire un check custom d'Agent

Aperçu

Cette page vous guide à travers le processus de création d’un “Hello world!” vérification d’Agent personnalisée. Elle vous montre également comment modifier l’intervalle de collecte minimum pour la vérification.

Configuration

Installation

Avant de créer une vérification d’Agent personnalisée, installez le Datadog Agent.

Pour travailler avec la dernière version de l'Agent, votre vérification d'Agent personnalisée doit être compatible avec Python 3.

Configuration

Accédez au répertoire conf.d sur votre système. Pour plus d’informations sur l’emplacement du répertoire conf.d, consultez Fichiers de configuration de l’Agent.
Dans le répertoire conf.d, créez un nouveau fichier de configuration pour votre nouvelle vérification d’Agent. Nommez le fichier custom_checkvalue.yaml.
Modifiez le fichier pour inclure ce qui suit :
conf.d/custom_checkvalue.yaml
```
init_config:
instances:
  [{}]
```
Créez un fichier de vérification dans le répertoire checks.d. Nommez le fichier custom_checkvalue.py.
Nommer vos vérifications :
- Il est judicieux de préfixer votre vérification avec custom_ pour éviter les conflits avec le nom d'une intégration Datadog Agent préexistante. Par exemple, si vous avez une vérification Postfix personnalisée, nommez vos fichiers de vérification custom_postfix.py et custom_postfix.yaml au lieu de postfix.py et postfix.yaml.
- Les noms des fichiers de configuration et de vérification doivent correspondre. Si votre vérification s'appelle custom_checkvalue.py, votre fichier de configuration doit être nommé custom_checkvalue.yaml.

Modifiez le fichier pour inclure ce qui suit :

checks.d/custom_checkvalue.py

from checks import AgentCheck
class HelloCheck(AgentCheck):
  def check(self, instance):
    self.gauge('hello.world', 1)

Redémarrez l’Agent et attendez qu’une nouvelle métrique nommée hello.world apparaisse dans le Résumé des Métriques.

Si vous rencontrez des problèmes pour faire fonctionner votre vérification personnalisée, vérifiez les permissions des fichiers. Le fichier de vérification doit être lisible et exécutable par l’utilisateur de l’Agent. Pour plus d’étapes de dépannage, consultez Dépanner une vérification d’Agent.

Mise à jour de l’intervalle de collecte

Pour changer l’intervalle de collecte de votre vérification, utilisez le paramètre min_collection_interval dans votre fichier custom_checkvalue.yaml et spécifiez une valeur en secondes. La valeur par défaut est de 15 secondes. Vous devez ajouter le min_collection_interval au niveau d’une instance. Si votre vérification personnalisée est configurée pour surveiller plusieurs instances, vous devez configurer l’intervalle individuellement par instance.

Définir le min_collection_interval à 30 ne garantit pas que la métrique est collectée toutes les 30 secondes. Le collecteur de l’Agent essaie d’exécuter la vérification toutes les 30 secondes, mais la vérification peut se retrouver en attente derrière d’autres intégrations et vérifications, en fonction du nombre d’intégrations et de vérifications activées sur le même Agent. Si une méthode check prend plus de 30 secondes pour se terminer, l’Agent remarque que la vérification est toujours en cours d’exécution et saute son exécution jusqu’à l’intervalle suivant.

Définissez un intervalle de collecte

Pour une seule instance, utilisez cette configuration pour définir l’intervalle de collecte à 30 secondes :

conf.d/custom_checkvalue.yaml

init_config:

instances:
  - min_collection_interval: 30

L’exemple ci-dessous démontre le changement de l’intervalle pour une vérification d’Agent personnalisée hypothétique qui surveille un service nommé my_service sur deux serveurs distincts :

init_config:

instances:
  - host: "http://localhost/"
    service: my_service
    min_collection_interval: 30

  - host: "http://my_server/"
    service: my_service
    min_collection_interval: 30

Vérification de votre vérification

Pour vérifier que votre check s’exécute, utilisez la commande suivante :

sudo -u dd-agent -- datadog-agent check <CHECK_NAME>

Après avoir vérifié que votre vérification fonctionne, redémarrez l’Agent pour l’inclure et commencer à rapporter des données.

Écriture de vérifications qui exécutent des programmes en ligne de commande

Il est possible de créer une vérification d’Agent personnalisée qui exécute un programme en ligne de commande et capture sa sortie en tant que métrique personnalisée. Par exemple, une vérification peut exécuter la commande vgs pour rapporter des informations sur les groupes de volumes.

Parce que l’interpréteur Python qui exécute les vérifications est intégré dans l’environnement d’exécution Go multi-threadé, l’utilisation des modules subprocess ou multithreading de la bibliothèque standard Python n’est pas supportée. Pour exécuter un sous-processus dans une vérification, utilisez la fonction get_subprocess_output() du module datadog_checks.base.utils.subprocess_output. La commande et ses arguments sont passés à get_subprocess_output() sous la forme d’une liste, avec la commande et ses arguments comme une chaîne dans la liste.

Si la commande suivante est saisie dans l’invite de commandes :

vgs -o vg_free

doit être passé à get_subprocess_output() comme ceci :

out, err, retcode = get_subprocess_output(["vgs", "-o", "vg_free"], self.log, raise_on_empty_output=True)

Lorsque vous exécutez le programme en ligne de commande, la vérification capture la même sortie que celle obtenue en exécutant la commande dans le terminal. Effectuez un traitement de chaîne sur la sortie et appelez int() ou float() sur le résultat pour retourner un type numérique.

Si vous ne traitez pas la sortie du sous-processus, ou si celle-ci ne retourne ni un entier ni un flottant, la vérification semble s’exécuter sans erreurs mais ne rapporte aucune métrique ni aucun événement. La vérification échoue également à retourner des métriques ou des événements si l’utilisateur de l’Agent n’a pas les permissions correctes sur les fichiers ou répertoires référencés dans la commande, ou les permissions requises pour exécuter la commande passée en argument à get_subprocess_output().

Voici un exemple de check qui renvoie les résultats d’un programme en ligne de commande :

# ...
from datadog_checks.base.utils.subprocess_output import get_subprocess_output

class LSCheck(AgentCheck):
    def check(self, instance):
        files, err, retcode = get_subprocess_output(["ls", "."], self.log, raise_on_empty_output=True)
        file_count = len(files.split('\n')) - 1  #len() returns an int by default
        self.gauge("file.count", file_count,tags=['TAG_KEY:TAG_VALUE'] + self.instance.get('tags', []))

Envoi de données depuis un équilibreur de charge

Un cas d’utilisation courant pour écrire une vérification d’Agent personnalisée est d’envoyer des métriques Datadog depuis un équilibreur de charge. Avant de commencer, suivez les étapes dans Configuration.

Pour étendre les fichiers afin d’envoyer des données depuis votre équilibreur de charge :

Remplacez le code dans custom_checkvalue.py par ce qui suit (en remplaçant la valeur de lburl par l’adresse de votre équilibreur de charge) :

checks.d/custom_checkvalue.py

import urllib2
import simplejson
from checks import AgentCheck

class CheckValue(AgentCheck):
  def check(self, instance):
    lburl = instance['ipaddress']
    response = urllib2.urlopen("http://" + lburl + "/rest")
    data = simplejson.load(response)

    self.gauge('coreapp.update.value', data["value"])

Mettez à jour le fichier custom_checkvalue.yaml (en remplaçant ipaddress par l’adresse IP de votre équilibreur de charge) :
conf.d/custom_checkvalue.yaml
```
init_config:

instances:
  - ipaddress: 1.2.3.4
```
Redémarrez votre Agent. Dans une minute, vous devriez voir une nouvelle métrique apparaître dans le Résumé des métriques appelée coreapp.update.value qui envoie les métriques de votre équilibreur de charge.
Créez un tableau de bord pour cette métrique.

Versionnage de l’Agent

Utilisez le bloc try/except suivant pour vous assurer que le check custom fonctionne avec n’importe quelle version de l’Agent :

try:
    # first, try to import the base class from new versions of the Agent
    from datadog_checks.base import AgentCheck
except ImportError:
    # if the above failed, the check is running in Agent version < 6.6.0
    from checks import AgentCheck

# content of the special variable __version__ will be shown in the Agent status page
__version__ = "1.0.0"

class HelloCheck(AgentCheck):
    def check(self, instance):
        self.gauge('hello.world', 1, tags=['TAG_KEY:TAG_VALUE'] + self.instance.get('tags', []))