Información general

En esta página se explica a los socios tecnológicos cómo crear una integración de Datadog Agent, que se puede incluir como producto listo para usar en la página de Integraciones o por un precio en la página de Marketplace.

Integraciones basadas en Agent

Las integraciones basadas en Agent utilizan Datadog Agent para enviar datos a través de checks escritos por el desarrollador. Los checks pueden emitir métricas, eventos y checks de servicios hacia la cuenta de un cliente de Datadog. El propio Agent también puede emitir logs, pero eso se configura fuera del check.

El código de implementación de estas integraciones se aloja en Datadog. Las integraciones de Agent son las más adecuadas para recopilar datos de sistemas o aplicaciones que se encuentran en una red de área local (LAN) o una nube privada virtual (VPC). Para crear una integración de Agent, debes publicar y desplegar tu solución como una rueda de Python (.whl).

Puedes incluir activos listos para usar, como monitores, dashboards y canalizaciones de logs, en tu integración basada en Agent. Cuando un usuario haga clic en Install (Instalar) en el cuadro de la integración, se le pedirá que siga las instrucciones de configuración, y todos los dashboards listos para usar aparecerán en su cuenta. Otros activos, como las canalizaciones de logs, aparecerán para los usuarios tras la correcta instalación y configuración de la integración.

Proceso de desarrollo

El proceso para crear una integración basada en Agent tiene el siguiente aspecto:

1. Una vez que te acepten en la Red de socios de Datadog, te reunirás con el equipo de socios tecnológicos de Datadog para analizar tu oferta y tus casos de uso.
2. Solicita una cuenta de prueba de Datadog para el desarrollo a través del portal de la Red de socios de Datadog.
3. Comienza a desarrollar tu integración, que incluye la escritura del código de la integración por tu parte, así como la creación e instalación de una rueda de Python (.whl).
4. Prueba la integración en tu cuenta de prueba de Datadog.
5. Una vez que hayas probado y completado el trabajo de desarrollo, rellena los activos del cuadro con información como instrucciones de configuración, imágenes, información de soporte, etc., que conformarán el cuadro de la integración que se mostrará en la página de Integrations (Integraciones) o Marketplace.
6. Una vez enviada y aprobada tu solicitud de extracción, el equipo de socios tecnológicos de Datadog programará una demostración para una revisión final de la integración.
7. Tendrás la opción de probar el cuadro y la integración en tu cuenta de prueba de Datadog antes de publicarlos, o podrás publicar inmediatamente la integración para todos los clientes.

Requisitos previos

Las herramientas de desarrollo requeridas para la integración de Datadog Agent son las siguientes:

• Python v3.11, pipx y la herramienta de desarrollo para la integración de Agent (ddev). Para obtener instrucciones de instalación, consulta Instalar la herramienta de desarrollo para la integración de Datadog Agent.
• Docker para ejecutar el conjunto de prueba completo.
• La [línea de comandos] de git5 o el cliente de escritorio de GitHub.

mkdir $HOME/dd && cd $HOME/dd

Crear la integración

Una vez que hayas descargado Docker, instalado una versión adecuada de Python y preparado tu entorno de desarrollo, puedes empezar a crear una integración basada en Agent.

En las siguientes instrucciones se utiliza una integración de ejemplo denominada Awesome. Sigue las instrucciones utilizando el código de Awesome o sustitúyelo por tu propio código, así como el nombre de tu integración dentro de los comandos. Por ejemplo, utiliza ddev create <your-integration-name> en lugar de ddev create Awesome.

Crear un andamiaje para la integración

El comando ddev create ejecuta una herramienta interactiva que crea la estructura básica de archivos y rutas (o andamiaje) necesaria para una integración basada en Agent.

1. Antes de crear el primer directorio de la integración, intenta realizar una ejecución de prueba utilizando el indicador -n/--dry-run, que no escribe nada en el disco:

   ddev create -n Awesome
   

   Este comando muestra la ruta donde se habrían escrito los archivos, así como la propia estructura. Asegúrate de que la ruta en la primera línea de salida coincide con la localización de tu repositorio.

2. Ejecuta el comando sin el indicador -n. La herramienta te pedirá un correo electrónico y un nombre y, a continuación, creará los archivos que necesitas para empezar a trabajar con una integración.

   Si estás creando una integración para Datadog Marketplace, asegúrate de que tu directorio sigue el patrón de {partner name}_{integration name}.

   ddev create Awesome
   

Programar un check de Agent

En la base de cada integración basada en Agent hay un Agent Check (Control de Agent) que recopila periódicamente información y la envía a Datadog.

Los checks heredan su lógica de la clase base AgentCheck y tienen los siguientes requisitos:

• Las integraciones que se ejecutan en Datadog Agent v7 o versiones posteriores deben ser compatibles con Python 3. Las integraciones que se ejecutan en Datadog Agent v5 y v6 todavía utilizan Python 2.7.
• Los checks deben derivarse de AgentCheck.
• Los checks deben otorgar un método con esta firma: check(self, instance).
• Los checks están organizados en paquetes comunes de Python en el espacio de nombresdatadog_checks. Por ejemplo, el código de Awesome se encuentra en el directorio awesome/datadog_checks/awesome/.
• El nombre del paquete debe ser el mismo que el del check.
• No hay restricciones sobre el nombre de los módulos de Python dentro de ese paquete, ni sobre el nombre de la clase que implementa el check.

Implementar la lógica del check

Para Awesome, el check de Agent se compone de un check de servicio denominado awesome.search que busca una cadena en una página web. El resultado es OK si la cadena está presente, WARNING si se puede acceder a la página pero no se ha encontrado la cadena y CRITICAL si no se puede acceder a la página.

Para saber cómo enviar métricas con el check de Agent, consulta Personalizar el check de Agent.

El código contenido en awesome/datadog_checks/awesome/check.py tiene el siguiente aspecto:

import requests

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))
        # Page is accessible
        else:
            # search_string is present
            if search_string in response.text:
                self.service_check('awesome.search', self.OK)
            # search_string was not found
            else:
                self.service_check('awesome.search', self.WARNING)

Para obtener más información sobre la clase base de Python, consulta Anatomía de un check de Python.

Programar pruebas de validación

Existen dos tipos de pruebas:

• Pruebas unitarias para funciones específicas
• Pruebas de integración que ejecutan el método check y verifican la correcta recopilación de métricas

Para ejecutar las pruebas, se utiliza pytest y hatch. Las pruebas son necesarias para publicar tu integración.

Programar una prueba unitaria

La primera parte del método check para Awesome recupera y verifica dos elementos del archivo de configuración. Esta es una buena opción para una prueba unitaria.

Abre el archivo en awesome/tests/test_awesome.py y sustituye el contenido por lo siguiente:

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 tiene el concepto de marcadores que pueden utilizarse para agrupar pruebas en categorías. Observa que test_config está marcado como prueba unitaria mediante unit.

El andamiaje está configurado para ejecutar todas las pruebas ubicadas en awesome/tests. Para ejecutar las pruebas, ejecuta el siguiente comando:

ddev test awesome

Programar una prueba de integración

La prueba unitaria anterior no comprueba la lógica de la recopilación. Para probar la lógica, necesitas crear un entorno para una prueba de integración y programar una prueba de integración.

Crear un entorno para la prueba de integración

El kit de herramientas utiliza docker para iniciar un contenedor NGINX y deja que el check recupere la página de bienvenida.

Para crear un entorno para la prueba de integración, crea un archivo docker-compose en awesome/tests/docker-compose.yml con el siguiente contenido:

version: "3"

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

A continuación, abre el archivo en awesome/tests/conftest.py y sustituye el contenido por lo siguiente:

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

Añadir una prueba de integración

Después de configurar un entorno para la prueba de integración, añade una prueba de integración al archivo 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)

Para acelerar el desarrollo, utiliza la opción -m/--marker para ejecutar únicamente las pruebas de integración:

ddev test -m integration awesome

Tu integración está casi completa. A continuación, añade los activos de check necesarios.

Rellenar los activos de integración

El siguiente conjunto de activos creados por el andamiaje ddev debe rellenarse con información relevante para tu integración:

README.md

contiene la documentación de tu check de Agent, cómo configurarlo, qué datos recopila e información de soporte.

spec.yaml

se utiliza para generar el conf.yaml.example mediante la herramienta ddev. Para obtener más información, consulta Especificación de la configuración.

conf.yaml.example

contiene las opciones por defecto (o de ejemplo) de la configuración del check de Agent. No edites este archivo manualmente. Se genera a partir del contenido de spec.yaml. Para obtener más información, consulta la Documentación de referencia del archivo de configuración.

manifest.json

contiene los metadatos del check de Agent, como el título y las categorías. Para obtener más información, consulta la Documentación de referencia del archivo de manifiesto.

metadata.csv

contiene la lista de todas las métricas recopiladas por el check de Agent. Para obtener más información, consulta la Documentación de referencia del archivo de metadatos de métricas.

service_check.json

contiene la lista de todos los checks de servicios recopilados por el check de Agent. Para obtener más información, consulta la Documentación de referencia del archivo de checks de servicios.

Para obtener más información sobre los archivos README.md y manifest.json, consulta Crear un cuadro y Referencia de activos de integraciones.

Crear la rueda

El archivo pyproject.toml otorga los metadatos que se utilizan para empaquetar y crear la rueda. La rueda contiene los archivos necesarios para el funcionamiento de la propia integración, lo que incluye el check de Agent, el archivo de configuración de ejemplo y los artefactos generados durante la creación de la rueda.

Los elementos adicionales, incluidos los archivos de metadatos, no están pensados para la rueda y se utilizan en otros lugares de la plataforma y el ecosistema Datadog.

Para obtener más información sobre el empaquetado de Python, consulta Empaquetado de proyectos de Python.

Una vez que pyproject.toml esté listo, crea una rueda mediante una de las siguientes opciones:

• (Recomendado) Con la herramienta ddev: ddev release build <INTEGRATION_NAME>.
• Sin la herramienta ddev: cd <INTEGRATION_DIR> && pip wheel . --no-deps --wheel-dir dist.

Instalar la rueda

La rueda se instala mediante el comando de Agent integration, disponible en Agent v6.10.0 o versiones posteriores. Dependiendo de tu entorno, puede que necesites ejecutar este comando como un usuario específico o con privilegios específicos:

Linux (como dd-agent):

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

OSX (como administrador):

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

Windows PowerShell (Asegúrate de que tu sesión de shell tenga privilegios de administrador):

& "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

Rellenar el cuadro y publicar la integración

Una vez que hayas creado tu integración basada en Agent, consulta la documentación Crear un cuadro para obtener información sobre cómo rellenar el resto de activos requeridos que aparecen en el cuadro de la integración y abrir una solicitud de extracción.

Actualizar la integración

Para actualizar tu integración, edita los archivos relevantes y abre una nueva solicitud de extracción en el directorio de la integración, ya sea en el repositorio integrations-extras o marketplace.

• Si estás editando o añadiendo código a la integración, se requiere un cambio de versión.

• Si estás editando o añadiendo contenido README, información de manifiesto o activos como dashboards y monitores recomendados, no es necesario un cambio de versión.

Tras realizar actualizaciones en activos como dashboards y monitores recomendados, o en archivos que no son de código como README.md y manifest.json, no es necesario que el desarrollador realice ninguna otra acción después de que se hayan fusionado las solicitudes de extracción correspondientes. Estos cambios se mostrarán al cliente sin ninguna acción por su parte.

Cambio de versión de una integración

Además de cualquier cambio en el código, se requiere lo siguiente cuando se actualiza la versión de una integración:

1. Actualiza __about__.py para reflejar el nuevo número de versión. Este archivo se encuentra en el directorio de la integración en /datadog_checks/<your_check_name>/__about__.py.
2. Añade una entrada al archivo CHANGELOG.md que siga el siguiente formato:

   ## Version Number / Date
   
   ***Added***: 
   
   * New feature
   * New feature
   
   ***Fixed***:
   
   * Bug fix
   * Bug fix
   

3. Actualiza todas las referencias al número de versión mencionado en README.md y en otros sitios. Las instrucciones de instalación de README.md suelen incluir el número de versión, que debe actualizarse.

Referencias adicionales

Additional helpful documentation, links, and articles:

Crear un cuadroDOCUMENTACIÓN Python para el desarrollo con la integración basada en AgentDOCUMENTACIÓN Aprende a desarrollar en la plataforma DatadogDOCUMENTACIÓN