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:
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.
Solicita una cuenta de prueba de Datadog para el desarrollo a través del portal de la Red de socios de Datadog.
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).
Prueba la integración en tu cuenta de prueba de Datadog.
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.
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.
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:
Selecciona una pestaña para obtener instrucciones sobre cómo crear una integración lista para usar basada en Agent en la página de Integraciones o una integración basada en Agent en la página de Marketplace.
Para crear una integración lista para usar:
Crea un directorio dd:
mkdir $HOME/dd &&cd$HOME/dd
El kit de herramientas de desarrollo de Datadog espera que trabajes en el directorio $HOME/dd/. Esto no es obligatorio, pero se requieren pasos de configuración adicionales para trabajar en un directorio diferente.
La herramienta de desarrollo para la integración de Agent te permite crear un andamiaje durante el desarrollo de una integración mediante la generación de una estructura de los activos y metadatos del cuadro de la integración. Para obtener instrucciones sobre la instalación de la herramienta, consulta Instalar la herramienta de desarrollo para la integración de Datadog Agent.
Para configurar la herramienta para el repositorio integrations-extras:
Opcionalmente, si el repositorio integrations-extras está en un lugar distinto de $HOME/dd/, ajusta el archivo de configuración ddev:
ddev config set extras "/path/to/integrations-extras"
Establece integrations-extras como repositorio de trabajo por defecto:
mkdir $HOME/dd```El comando del kit de herramientas de desarrollo de Datadog espera que trabajes en el directorio `$HOME/dd/`. Esto no es obligatorio, pero se requieren pasos de configuración adicionales para trabajar en un directorio diferente.
Una vez que se te haya concedido acceso al repositorio de Marketplace, crea el directorio dd y clona el repositorio marketplace:
Instalar y configurar el kit de herramientas de desarrollo de Datadog
La herramienta de desarrollo para la integración de Agent te permite crear un andamiaje durante el desarrollo de una integración mediante la generación de una estructura de los activos y metadatos del cuadro de la integración. Para obtener instrucciones sobre la instalación de la herramienta, consulta Instalar la herramienta de desarrollo para la integración de Datadog Agent.
Una vez que hayas instalado la herramienta de desarrollo para la integración de Agent, configúrala para el repositorio de Marketplace.
Establece marketplace como repositorio de trabajo por defecto:
ddev config set marketplace $HOME/dd/marketplace
ddev config set repo marketplace
Si usaste un directorio distinto de $HOME/dd para clonar el directorio marketplace, utiliza el siguiente comando para establecer el repositorio de trabajo:
ddev config set marketplace <PATH/TO/MARKETPLACE>
ddev config set repo marketplace
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.
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.
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.
El código contenido en awesome/datadog_checks/awesome/check.py tiene el siguiente aspecto:
check.py
importrequestsfromdatadog_checks.baseimportAgentCheck,ConfigurationErrorclassAwesomeCheck(AgentCheck):"""AwesomeCheck derives from AgentCheck, and provides the required check method."""defcheck(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.ifnoturlornotsearch_string:raiseConfigurationError('Configuration error, please fix awesome.yaml')try:response=requests.get(url)response.raise_for_status()# Something went horribly wrongexceptExceptionase:# Ideally we'd use a more specific message...self.service_check('awesome.search',self.CRITICAL,message=str(e))# Page is accessibleelse:# search_string is presentifsearch_stringinresponse.text:self.service_check('awesome.search',self.OK)# search_string was not foundelse:self.service_check('awesome.search',self.WARNING)
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:
test_awesome.py
importpytest# Don't forget to import your integrationfromdatadog_checks.awesomeimportAwesomeCheckfromdatadog_checks.baseimportConfigurationError@pytest.mark.unitdeftest_config():instance={}c=AwesomeCheck('awesome',{},[instance])# empty instancewithpytest.raises(ConfigurationError):c.check(instance)# only the urlwithpytest.raises(ConfigurationError):c.check({'url':'http://foobar'})# only the search stringwithpytest.raises(ConfigurationError):c.check({'search_string':'foo'})# this should not failc.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:
A continuación, abre el archivo en awesome/tests/conftest.py y sustituye el contenido por lo siguiente:
conftest.py
importosimportpytestfromdatadog_checks.devimportdocker_run,get_docker_hostname,get_hereURL='http://{}:8000'.format(get_docker_hostname())SEARCH_STRING='Thank you for using nginx.'INSTANCE={'url':URL,'search_string':SEARCH_STRING}@pytest.fixture(scope='session')defdd_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 finishedwithdocker_run(compose_file,endpoints=[URL]):yieldINSTANCE@pytest.fixturedefinstance():returnINSTANCE.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:
test_awesome.py
@pytest.mark.integration@pytest.mark.usefixtures('dd_environment')deftest_service_check(aggregator,instance):c=AwesomeCheck('awesome',{},[instance])# the check should send OKc.check(instance)aggregator.assert_service_check('awesome.search',AwesomeCheck.OK)# the check should send WARNINGinstance['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 ddevdebe 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.
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.
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:
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:
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.
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
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.