Aperçu

Cette page guide les Partenaires Technologiques à travers le processus de création d’une intégration officielle de l’Agent Datadog.

Les intégrations basées sur l’Agent sont conçues pour collecter de la télémétrie à partir de logiciels ou de systèmes fonctionnant sur une infrastructure gérée par le client, où l’Agent Datadog est installé ou a accès au réseau. Ces intégrations utilisent l’Agent Datadog pour collecter et soumettre des données via des vérifications d’agent personnalisées développées par des Partenaires Technologiques approuvés.

Les vérifications d’agent peuvent émettre des métriques, des événements et des journaux dans le compte Datadog d’un client. Chaque intégration basée sur l’Agent est un package Python construit sur l’Agent Datadog, permettant aux clients de l’installer facilement via l’Agent Datadog. Les traces, cependant, sont collectées en dehors de la vérification de l’agent en utilisant l’un des SDK de Datadog. Pour plus d’informations, consultez la documentation sur l’instrumentation des applications.

Création d’une intégration basée sur l’agent

Avant de commencer, assurez-vous d’avoir rejoint le Réseau de Partenaires Datadog, d’avoir accès à une organisation de développeurs partenaires, et d’avoir créé une fiche sur la Developer Platform.

Suivez ces étapes pour créer votre intégration basée sur l’agent :

1. Installez les outils de développement requis.
2. Configurez l’outil de développement d’intégration de l’Agent Datadog.
3. Générez votre échafaudage
4. Développez votre vérification d’agent.
5. Testez votre intégration.
6. Soumettez votre code pour révision.

Conditions préalables

Assurez-vous que les outils suivants sont installés :

• pipx pour installer les outils de développement et les dépendances
• Datadog Agent Integration Developer Tool (ddev) pour générer l’échafaudage et gérer le développement d’intégration
• Docker pour exécuter l’ensemble des tests
• Git (ligne de commande ou client GitHub Desktop)

Configurez l’outil de développement d’intégration de l’Agent Datadog

Utilisez l’outil de développement de l’Agent Datadog pour construire et tester votre intégration. Les étapes de configuration diffèrent selon que vous développez une intégration prête à l’emploi (OOTB) ou une Intégration Marketplace. Sélectionnez l’onglet approprié ci-dessous.

Générez votre échafaudage

Utilisez la commande ddev create pour générer la structure de fichiers et de répertoires initiale pour votre intégration basée sur un agent.

1. Effectuez une exécution à blanc (recommandé)

   Utilisez l’option -n ou --dry-run pour prévisualiser les fichiers générés, sans rien écrire sur le disque. Confirmez que le chemin de sortie correspond à l’emplacement du dépôt attendu.

   ddev create -nt check_only <YOUR_INTEGRATION_NAME> --skip-manifest
   

2. Générez les fichiers

   Après avoir vérifié l’emplacement du répertoire, exécutez la même commande sans le -n pour créer l’échafaudage. Suivez les instructions pour fournir les détails de l’intégration.

   ddev create -t check_only <YOUR_INTEGRATION_NAME> --skip-manifest
   

Développez votre vérification d’agent

Chaque intégration basée sur un agent tourne autour d’une vérification d’agent, une classe Python qui collecte périodiquement de la télémétrie et la soumet à Datadog.

Les vérifications d’agent héritent de la classe de base AgentCheck et doivent répondre aux exigences suivantes :

• Compatibilité Python :
  • Les intégrations pour Datadog Agent v7+ doivent prendre en charge Python 3. Toutes les nouvelles intégrations doivent cibler v7+.
  • Les intégrations pour Datadog Agent v5-v6 utilisent Python 2.7.
• Héritage de classe : Chaque vérification doit sous-classer AgentCheck.
• Point d’entrée : Chaque vérification doit implémenter une méthode check(self, instance).
• Structure de paquet : Les vérifications sont organisées sous l’espace de noms datadog_checks. Par exemple, une intégration nommée <INTEGRATION_NAME> se trouve dans : <integration_name>/datadog_checks/<integration_name>/.
• Nommage :
  • Le nom du paquet doit correspondre au nom de la vérification.
  • Les noms de module et de classe Python au sein du paquet peuvent être choisis librement.

Implémentez la logique de vérification

L’exemple suivant montre la logique pour une intégration nommée Awesome.

Cette vérification définit un service de vérification appelé awesome.search, qui recherche une chaîne spécifique sur une page web :

• Renvoie OK si la chaîne est trouvée.
• Renvoie WARNING si la page se charge mais que la chaîne est manquante.
• Renvoie CRITICAL si la page ne peut pas être atteinte.

Pour apprendre à soumettre des données supplémentaires de votre vérification, voir :

• Vérification d’Agent Personnalisée pour soumettre des métriques.
• Collecte de Logs d’Intégration d’Agent pour collecter des logs de votre AgentCheck en utilisant send_log. Meilleur pour l’émission de logs à source unique.
• Tutoriel de Crawler HTTP pour collecter des logs de plusieurs sources de logs, comme lors de l’interrogation de plusieurs points de terminaison ou d’APIs HTTP externes.

Le fichier awesome/datadog_checks/awesome/check.py pourrait ressembler à ceci :

import requests
import time

from datadog_checks.base import AgentCheck, ConfigurationError


class AwesomeCheck(AgentCheck):
    """AwesomeCheck derives from AgentCheck, and provides the required check method."""

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

        # It's a very good idea to do some basic sanity checking.
        # Try to be as specific as possible with the 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()
        # Something went horribly wrong
        except Exception as e:
            # Ideally we'd use a more specific message...
            self.service_check('awesome.search', self.CRITICAL, message=str(e))
            # Submit an error log
            self.send_log({
                'message': f'Failed to access {url}: {str(e)}',
                'timestamp': time.time(),
                'status': 'error',
                'service': 'awesome',
                'url': url
            })
        # Page is accessible
        else:
            # search_string is present
            if search_string in response.text:
                self.service_check('awesome.search', self.OK)
                # Submit an info log
                self.send_log({
                    'message': f'Successfully found "{search_string}" at {url}',
                    'timestamp': time.time(),
                    'status': 'info',
                    'service': 'awesome',
                    'url': url,
                    'search_string': search_string
                })
            # search_string was not found
            else:
                self.service_check('awesome.search', self.WARNING)
                # Submit a warning log
                self.send_log({
                    'message': f'String "{search_string}" not found at {url}',
                    'timestamp': time.time(),
                    'status': 'warning',
                    'service': 'awesome',
                    'url': url,
                    'search_string': search_string
                })

Pour en savoir plus sur la classe de base Python, voir Anatomie d’une Vérification Python.

Écrivez des tests de validation

Il existe deux types de tests :

• Tests unitaires pour des fonctionnalités spécifiques
• Tests d’intégration qui exécutent la méthode check et vérifient la collecte correcte des métriques

pytest et hatch sont utilisés pour exécuter les tests. Des tests sont nécessaires pour publier votre intégration.

Écrivez un test unitaire

La première partie de la méthode check pour Awesome récupère et vérifie deux éléments du fichier de configuration. C’est un bon candidat pour un test unitaire.

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

import pytest

    # Don't forget to import your integration

from datadog_checks.awesome import AwesomeCheck
from datadog_checks.base import ConfigurationError


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

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

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

    # only the search string
    with pytest.raises(ConfigurationError):
        c.check({'search_string': 'foo'})

    # this should not fail
    c.check({'url': 'http://foobar', 'search_string': 'foo'})

pytest a le concept de marqueurs qui peuvent être utilisés pour regrouper les tests en catégories. Remarquez que test_config est marqué comme un test unit.

L’échafaudage est configuré pour exécuter tous les tests situés dans awesome/tests. Pour exécuter les tests, exécutez la commande suivante :

ddev test awesome

Écrivez un test d’intégration

Le test unitaire ci-dessus ne vérifie pas la logique de collection. Pour tester la logique, vous devez créer un environnement pour un test d’intégration et écrire un test d’intégration.

Créez un environnement pour le test d’intégration

L’outil utilise docker pour démarrer un conteneur NGINX et permet à la vérification de récupérer la page d’accueil.

Pour créer un environnement pour le test d’intégration, créez un fichier docker-compose à awesome/tests/docker-compose.yml avec le contenu suivant :

version: "3"

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

Ensuite, ouvrez 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')

    # This does 3 things:
    #
    # 1. Spins up the services defined in the compose file
    # 2. Waits for the url to be available before running the tests
    # 3. Tears down the services when the tests are finished
    with docker_run(compose_file, endpoints=[URL]):
        yield INSTANCE


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

Ajoutez un test d’intégration

Après avoir configuré un environnement pour le test d’intégration, 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])

    # the check should send OK
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.OK)

    # the check should send WARNING
    instance['search_string'] = 'Apache'
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.WARNING)

Pour accélérer le développement, utilisez l’option -m/--marker pour exécuter uniquement les tests d’intégration :

ddev test -m integration awesome

Testez votre vérification d’agent

Les intégrations basées sur l’Agent sont distribuées sous forme de fichiers Python wheel (.whl) que les clients installent via l’Agent Datadog. Avant de publier votre intégration, vous pouvez la tester localement en construisant et en installant manuellement le package wheel.

Construisez le wheel

Le fichier pyproject.toml fournit les métadonnées utilisées pour empaqueter et construire le wheel. Le wheel contient les fichiers nécessaires au fonctionnement de l’intégration elle-même, y compris la vérification de l’agent, le fichier d’exemple de configuration et les artefacts générés lors de la construction du wheel.

Pour en savoir plus sur l’empaquetage Python, consultez Emballage de projets Python.

Une fois que votre pyproject.toml est prêt, créez un wheel en utilisant l’une des options suivantes :

• (Recommandé) Avec l’outil ddev : ddev release build <INTEGRATION_NAME>.
• Sans l’outil ddev : cd <INTEGRATION_DIR> && pip wheel . --no-deps --wheel-dir dist.

Installez le wheel

Le wheel est installé en utilisant la commande Agent integration, disponible dans Agent v6.10.0 ou ultérieur. Selon votre environnement, vous devrez peut-être exécuter cette commande en tant qu’utilisateur spécifique ou avec des privilèges spécifiques :

Linux (en tant que dd-agent) :

sudo -u dd-agent datadog-agent integration install -w /path/to/wheel.whl

OSX (en tant qu’administrateur) :

sudo datadog-agent integration install -w /path/to/wheel.whl

Windows PowerShell (Assurez-vous que votre session shell dispose des privilèges administrateur) :

& "C:\Program Files\Datadog\Datadog Agent\embedded\agent.exe" integration install -w /path/to/wheel.whl

& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" integration install -w /path/to/wheel.whl

Pour installer votre wheel pour tester dans des environnements Kubernetes :

1. Montez le fichier .whl dans un initContainer.
2. Exécutez l’installation du wheel dans l’initContainer.
3. Montez le conteneur d’initialisation dans le conteneur Agent pendant qu’il fonctionne.

Pour les commandes d’installation des clients pour les environnements hôte et conteneur, consultez la documentation sur les intégrations de la communauté et du marché.

Soumettez votre code pour révision

Ouvrez une pull request avec votre répertoire d’intégration dans le dépôt approprié, soit Datadog/integrations-extras soit Datadog/marketplace. La pull request est examinée en parallèle avec votre soumission à la Developer Platform.

Mise à jour de votre intégration

Après la publication de votre intégration, vous pouvez publier des mises à jour via la plateforme développeur.

Mise à jour de la version d’une intégration

Une mise à jour de la version est nécessaire chaque fois que vous ajoutez, supprimez ou modifiez des fonctionnalités (par exemple, lors de l’introduction de nouvelles métriques, de la mise à jour de tableaux de bord ou de la modification du code d’intégration). Ce n’est pas nécessaire pour les mises à jour non fonctionnelles, telles que les modifications de contenu écrit, de branding, de logos ou d’images.

Dans la Developer Platform, incluez une nouvelle entrée dans l’onglet Release Notes en suivant ce format :

## Version Number / Date (YYYY-MM-DD)

***Added***:

* Description of new feature
* Description of new feature

***Fixed***:

* Description of fix
* Description of fix

***Changed***:

* Description of update or improvement
* Description of update or improvement

***Removed***:

* Description of removed feature
* Description of removed feature

Assurez-vous de mettre à jour toutes les références au numéro de version dans la documentation et les instructions d’installation de l’intégration.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Créez une intégrationDOCUMENTATION Python pour le développement d'intégrations basées sur l'AgentDOCUMENTATION Découvrir comment développer sur la plateforme DatadogDOCUMENTATION Créer une intégration pour l'AgentCENTRE D'APPRENTISSAGE