Créer une intégration

Pour qu’une intégration basée sur l’Agent soit considérée comme complète, et donc prête à être incluse dans le référentiel principal et intégrée au package de l’Agent, un certain nombre d’exigences doivent être satisfaites :

• Le fichier README.md doit être au bon format et inclure le contenu adéquat.
• Une batterie de tests doit être effectuée afin de vérifier la bonne collecte de métriques.
• Le fichier metadata.csv doit énumérer toutes les métriques recueillies.
• Le fichier manifest.json doit être complet.
• Si l’intégration recueille des checks de service, le fichier service_checks.json doit également être présent.

Ces exigences forment une checklist de vérification qui est passée en revue durant le processus d’examen du code. Cette documentation vous expliquera comment satisfaire ces exigences et implémenter correctement votre nouvelle intégration.

Prérequis

• Python 3.8+ doit être disponible sur votre système. Python 2.7 est facultatif, mais conseillé.
• Docker pour exécuter la collection de tests.

Si la création et l’activation d’environnements virtuels Python est conseillé pour isoler l’environnement de développement, ce n’est toutefois pas obligatoire. Pour en savoir plus, consultez la section Environnement Python pour le développement d’intégrations avec l’Agent.

Configuration

Dupliquez le référentiel integrations-extras. Par défaut, cette ressource s’attend à ce que vous travailliez dans le répertoire $HOME/dd/. Ce n’est toutefois pas obligatoire, et vous aurez la possibilité de modifier ce paramètre ultérieurement.

mkdir $HOME/dd && cd $HOME/dd       # facultatif
git clone https://github.com/DataDog/integrations-extras.git

Kit de développement

Le kit de développement est complet et intègre de nombreuses fonctionnalités. Pour démarrer, exécutez cette commande :

pip3 install "datadog-checks-dev[cli]"

Si vous avez choisi de dupliquer ce référentiel à un emplacement autre que $HOME/dd/, vous devez modifier le fichier de configuration :

ddev config set extras "/chemin/vers/integrations-extras"

Si vous prévoyez de travailler principalement sur integrations-extras, définissez-le comme référentiel de travail par défaut :

ddev config set repo extras

Remarque : si vous sautez cette étape, utilisez la commande -e à chaque appel pour vérifier que le contexte est integrations-extras.

ddev -e COMMANDE [OPTIONS]

Architecture

L’une des fonctionnalités du kit de développement est la commande create, qui crée la structure de fichiers et de chemins générale (c’est-à-dire l’« architecture ») nécessaire pour toute nouvelle intégration.

Test d’exécution

Effectuez un test d’exécution avec le flag -n/--dry-run, qui n’écrit aucun contenu sur le disque.

ddev create -n Awesome

Cette commande affiche le chemin où les fichiers auraient été écrits, ainsi que la structure. Vérifiez que le chemin dans la première ligne de la sortie correspond à l’emplacement de votre référentiel Extras.

Mode interactif

Le mode interactif est un assistant conçu pour vous aider à créer des intégrations. Il suffit de répondre à quelques questions pour que l’architecture soit automatiquement définie et préconfigurée.

ddev create Awesome

Après avoir répondu aux questions, la sortie correspond à celle du test d’exécution ci-dessus, à la différence près que l’architecture de votre nouvelle intégration existe vraiment.

Écrire le check

Introduction

Un Check est une classe Python qui doit :

• Les intégrations qui s’exécutent sur l’Agent 7+ doivent être compatibles avec Python 3. Toutefois, les versions 5 et 6 de l’Agent utilisent toujours Python 2.7.
• Être dérivée de AgentCheck
• Fournir une méthode avec la signature check(self, instance)

Les checks se présentent sous la forme de paquets Python classiques stockés dans l’espace de nommage datadog_checks ; votre code résidera donc dans awesome/datadog_checks/awesome. La seule exigence est que le nom du paquet soit le même que le nom du check. Aucune restriction particulière n’est appliquée quant au nom des modules Python dans ce paquet, ni quant au nom de la classe qui implémente le check.

Implémenter la logique du check

Supposons que vous souhaitiez créer un check d’Agent composé uniquement d’un check de service awesome.search qui recherche une chaîne sur une page Web. Ce check renvoie OK si la chaîne est présente, WARNING si la page est accessible mais que la chaîne est absente, et CRITICAL si la page est inaccessible. Consultez la section Envoi de métriques : check custom d’Agent pour découvrir comment envoyer des métriques à l’aide de votre check d’Agent.

Le code contenu dans awesome/datadog_checks/awesome/check.py ressemble à ceci :

import requests

from datadog_checks.base import AgentCheck, ConfigurationError


class AwesomeCheck(AgentCheck):
    """AwesomeCheck est dérivé d'AgentCheck et fournit la méthode de check requise."""

    def check(self, instance):
        url = instance.get('url')
        search_string = instance.get('search_string')

        # Il convient de réaliser quelques contrôles d'intégrité basiques.
        # Soyez aussi précis que possible avec les exceptions.
        if not url or not search_string:
            raise ConfigurationError('Configuration error, please fix awesome.yaml')

        try:
            response = requests.get(url)
            response.raise_for_status()
        # En cas de problème sérieux
        except Exception as e:
            # Un message plus spécifique serait préférable
            self.service_check('awesome.search', self.CRITICAL, message=str(e))
        # La page est accessible
        else:
            # search_string est présent
            if search_string in response.text:
                self.service_check('awesome.search', self.OK)
            # search_string est introuvable
            else:
                self.service_check('awesome.search', self.WARNING)

Pour en savoir plus sur la classe Python de base, consultez la section Anatomie d’un check Python (en anglais).

Écrire des tests

Il existe deux types de tests de base :

• Les tests d’unités, qui permettent de tester une fonctionnalité spécifique
• Les tests d’intégration, qui exécutent la méthode check et vérifient la bonne collecte des métriques

Les tests sont obligatoires si vous souhaitez que votre intégration soit ajoutée à integrations-extras. Remarque : pytest et tox sont utilisés pour exécuter les tests.

Pour en savoir plus, consultez le guide d’installation de ddev (en anglais).

Test d’unité

La première partie de la méthode check récupère et vérifie deux éléments du fichier de configuration. Un test d’unité serait donc particulièrement utile. Ouvrez le fichier awesome/tests/test_awesome.py et remplacez son contenu pour qu’il ressemble à ceci :

import pytest

# N'oubliez pas d'importer votre intégration !
from datadog_checks.awesome import AwesomeCheck
from datadog_checks.base import ConfigurationError


@pytest.mark.unit
def test_config():
    instance = {}
    c = AwesomeCheck('awesome', {}, [instance])

    # instance vide
    with pytest.raises(ConfigurationError):
        c.check(instance)

    # url uniquement
    with pytest.raises(ConfigurationError):
        c.check({'url': 'http://foobar'})

    # chaîne de recherche uniquement
    with pytest.raises(ConfigurationError):
        c.check({'search_string': 'foo'})

    # aucune erreur ne devrait survenir
    c.check({'url': 'http://foobar', 'search_string': 'foo'})

pytest permet d’utiliser ce que l’on appelle des marqueurs, qui servent à regrouper les tests par catégorie. Notez que le marqueur unit a été appliqué à test_config.

L’architecture a déjà été configurée de façon à ce que tous les tests situés dans awesome/tests soient exécutés. Pour exécuter ces tests :

ddev test awesome

Créer un test d’intégration

Ce test ne vérifie toutefois pas la logique de collecte ; vous devez donc ajouter un test d’intégration. docker est utilisé pour lancer un conteneur Nginx et permettre au check de récupérer la page d’accueil. Créez un fichier compose awesome/tests/docker-compose.yml avec le contenu suivant :

version: "3"

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - "8000:80"

Ouvrez ensuite le fichier awesome/tests/conftest.py et remplacez le contenu par ce qui suit :

import os

import pytest

from datadog_checks.dev import docker_run, get_docker_hostname, get_here

URL = 'http://{}:8000'.format(get_docker_hostname())
SEARCH_STRING = 'Thank you for using nginx.'
INSTANCE = {'url': URL, 'search_string': SEARCH_STRING}


@pytest.fixture(scope='session')
def dd_environment():
    compose_file = os.path.join(get_here(), 'docker-compose.yml')

    # On accomplit ici 3 choses :
    #
    # 1. Lancer les services définis dans le fichier compose
    # 2. Attendre que l'URL soit disponible avant de lancer les tests
    # 3. Démonter les services lorsque les tests sont terminés
    with docker_run(compose_file, endpoints=[URL]):
        yield INSTANCE


@pytest.fixture
def instance():
    return INSTANCE.copy()

Test d’intégration

Enfin, ajoutez un test d’intégration au fichier awesome/tests/test_awesome.py :

@pytest.mark.integration
@pytest.mark.usefixtures('dd_environment')
def test_service_check(aggregator, instance):
    c = AwesomeCheck('awesome', {}, [instance])

    # le check doit renvoyer OK
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.OK)

    # le check doit renvoyer WARNING
    instance['search_string'] = 'Apache'
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.WARNING)

Pour un développement plus rapide, lancez les tests d’intégration uniquement avec l’option -m/--marker :

ddev test -m integration awesome

Le check est quasiment fini. Apportons la touche finale en ajoutant les configurations d’intégration.

Créer les ressources du check

Pour qu’un check puisse être inclus, l’ensemble des ressources créées par l’architecture ddev doit être complet :

README.md

Ce fichier contient la documentation de votre check. Il explique sa configuration, les données qu’il recueille, etc.

spec.yaml

Ce fichier permet de générer un conf.yaml.example à l’aide de l’outil ddev (consultez l’onglet « Modèle de configuration » ci-dessous). Pour en savoir plus, consultez la section Spécification de la configuration (en anglais).

conf.yaml.example

Ce fichier contient les options de configuration par défaut (ou des exemples) pour votre check d’Agent. Ne modifiez surtout pas ce fichier manuellement. Il est généré à partir du contenu du fichier spec.yaml. Consultez les références relatives au fichier de configuration pour mieux comprendre sa logique.

manifest.json

Ce fichier contient les métadonnées de votre check d’Agent, telles que le titre, les catégories, etc. Consultez les références relatives au fichier de manifeste pour en savoir plus.

metadata.csv

Ce fichier contient la liste de toutes les métriques recueillies par votre check d’Agent. Consultez les références relatives au fichier metadata des métriques pour en savoir plus.

service_check.json

Ce fichier contient la liste de tous les checks de service recueillis par votre check d’Agent. Consultez les références relatives au fichier service_check pour en savoir plus.

Dans cet exemple, ces fichiers ressembleraient à ce qui suit :

name: Awesome
files:
- name: awesome.yaml
  options:
  - template: init_config
    options:
    - template: init_config/default
  - template: instances
    options:
    - name: url
      required: true
      description: The URL to check.
      value:
        type: string
        example: http://example.org
    - name: search_string
      required: true
      description: The string to search for.
      value:
        type: string
        example: Example Domain
    - name: flag_follow_redirects
      # required: false est implicite, mettez-le en commentaire pour voir ce qui se passe !
      required: false
      description: Follow 301 redirects.
      value:
        type: boolean
        example: false
    # Essayez d'intervertir ces modèles pour voir ce qui se passe !
    #- template: instances/http
    - template: instances/default

ddev validate config --sync awesome

{
  "display_name": "awesome",
  "maintainer": "email@example.org",
  "manifest_version": "1.0.0",
  "name": "awesome",
  "metric_prefix": "awesome.",
  "metric_to_check": "",
  "creates_events": false,
  "short_description": "",
  "guid": "x16b8750-df1e-46c0-839a-2056461b604x",
  "support": "contrib",
  "supported_os": ["linux", "mac_os", "windows"],
  "public_title": "Intégration Datadog/Awesome",
  "categories": ["web"],
  "type": "check",
  "is_public": false,
  "integration_id": "awesome",
  "assets": {
    "dashboards": {
      "Awesome Overview": "assets/dashboards/overview.json",
      "Awesome Investigation Dashboard": "assets/dashboards/investigation.json"
    },
    "monitors": {},
    "service_checks": "assets/service_checks.json"
  }
}

[
  {
    "agent_version": "6.0.0",
    "integration": "awesome",
    "check": "awesome.search",
    "statuses": ["ok", "warning", "critical"],
    "groups": [],
    "name": "Recherche Awesome",
    "description": "Renvoie `CRITICAL` si le check n'accède pas à la page, `WARNING` si la chaîne de recherche n'a pas été trouvée ou `OK` pour les autres cas."
  }
]

Compilation

Le fichier pyproject.toml fournit les métadonnées servant à compiler le package et créer le wheel. Pour en savoir plus sur les packages Python, consultez la section Compilation de projets Python (en anglais).

Une fois votre fichier pyproject.toml prêt, créez un wheel :

• Avec l’outil ddev (conseillé) : ddev release build <NOM_INTÉGRATION>
• Sans l’outil ddev : cd <RÉPERTOIRE_INTÉGRATION> && pip wheel . --no-deps --wheel-dir dist

Que contient le wheel ?

Le wheel contient tous les fichiers nécessaires au bon fonctionnement de l’intégration. Il s’agit notamment du check, de l’exemple de fichier de configuration et de certains artefacts générés durant la compilation du wheel. Tous les autres éléments, y compris les fichiers de métadonnées, ne sont pas supposés se trouver dans le wheel. Ces éléments sont utilisés ailleurs par l’écosystème et la plateforme Datadog.

Installation

Le wheel est installé à l’aide de la commande integration de l’Agent, disponible dans les versions 6.10.0 et ultérieures de l’Agent. En fonction de votre environnement, il est possible que vous deviez utiliser un utilisateur spécifique ou certaines autorisations précises pour exécuter cette commande :

Linux (en tant que dd-agent) :

sudo -u dd-agent datadog-agent integration install -w /chemin/vers/wheel.whl

OSX (en tant qu’admin) :

sudo datadog-agent integration install -w /chemin/vers/wheel.whl

Windows (veillez à ce que votre session shell dispose des privilèges administrateur) :

Pour les versions <= 6.11 de l’Agent :

"C:\Program Files\Datadog\Datadog Agent\embedded\agent.exe" integration install -w /chemin/vers/wheel.whl

Pour les versions >= 6.12 de l’Agent :

"C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" integration install -w /chemin/vers/wheel.whl