Un complemento de Jenkins para reenviar automáticamente métricas, eventos y checks de servicio a una cuenta de Datadog.

Nota: La página del complemento de CI de Jenkins para este complemento hace referencia a esta documentación.

Configuración

Instalación

Este complemento requiere Jenkins 2.361.4 y Java 11.

Para versiones anteriores de Jenkins (es decir, 1.632+), puedes encontrar la versión 1.2.0 del complemento aquí.

Este complemento puede ser instalado desde el Update Center (que se encuentra en Manage Jenkins -> Manage Plugins) en tu instalación de Jenkins:

1. Selecciona la pestaña Available, busca Datadog y marca la casilla situada junto a Datadog Plugin.
2. Instala el complemento utilizando uno de los dos botones de instalación situados en la parte inferior de la pantalla.
3. Para comprobar que el complemento está instalado, busca Datadog Plugin en la pestaña Installed.

Continúa más abajo para la configuración.

Nota: Si aparece una versión inesperada de Datadog Plugin, ejecuta Check Now desde la pantalla Manage Jenkins -> Manage Plugins.

Configuración

Hay dos maneras de configurar tu complemento para enviar datos a Datadog:

• Con un Datadog Agent que actúa como Forwarder entre Jenkins y Datadog (recomendado).
  • Cuando se utiliza un servidor DogStatsD en lugar de un Datadog Agent completo, sólo se admiten métricas y eventos.
  • Para los datos enviados desde un host externo, el Datadog Agent requiere la siguiente configuración: dogstatsd_non_local_traffic: true y apm_non_local_traffic: true. Esto puede configurarse mediante el archivo de configuración datadog.yaml.
• Envío de datos directamente a Datadog a través de HTTP.
  • La implementación de cliente HTTP utilizada es de bloqueo con un tiempo de espera de 1 minuto. Si hay un problema de conexión con Datadog, puede ralentizar tu instancia de Jenkins.

La configuración se puede hacer desde la interfaz de usuario del complemento con un script Groovy, o a través de variables de entorno.

Interfaz de usuario del complemento

Para configurar tu complemento de Datadog, navega a la página Manage Jenkins -> Configure System en tu instalación Jenkins. Una vez allí, desplázate hacia abajo hasta encontrar la sección Datadog Plugin:

Reenvío HTTP

1. Selecciona el botón de opción situado junto a Use Datadog API URL and Key to report to Datadog (Utilizar la URL y la clave de la API de Datadog para informar a Datadog) (seleccionado por defecto).
2. Pega tu clave de API de Datadog en el cuadro de texto API Key de la pantalla de configuración de Jenkins. Si deseas almacenar tu clave de API con el Gestor de credenciales, crea una credencial para la clave de API y selecciona esa credencial en el menú desplegable Datadog API Key (Select from Credentials).
3. Prueba tu clave de API de Datadog utilizando el botón Test Key en la pantalla de configuración de Jenkins justo debajo del cuadro de texto de la clave de API.
4. (Opcional) Introduce el nombre de host del servidor Jenkins en la pestaña Advanced (Avanzado) para incluirlo con los eventos.
5. (Opcional) Introduce tu URL de entrada de log de Datadog y selecciona “Enable Log Collection” (Activar recopilación de logs) en la pestaña Advanced (Avanzado).
6. (Opcional) Selecciona “Enable CI Visibility” (Activar CI Visibility), configurando opcionalmente el nombre de tu instancia de CI.
7. Guarda tu configuración.

Reenvío de Datadog Agent

1. Selecciona el botón de opción situado junto a Use the Datadog Agent to report to Datadog (Utilizar Datadog Agent para informar a Datadog).
2. Especifica tu Datadog Agent hostname y port.
3. (Opcional) Introduce el nombre de host del servidor Jenkins en la pestaña Advanced (Avanzado) para incluirlo con el eventos.
4. (Opcional) Introduce tu puerto de recopilación de logs, configurar la recopilación de logs en el Datadog Agent y selecciona “Enable Log Collection” (Activar la recopilación de log).
5. (Opcional) Introduce tu puerto de recopilación de trazas (traces) y selecciona “Enable CI Visibility” (Activar CI Visibility), configurando opcionalmente el nombre de tu instancia de CI.
6. Guarda tu configuración.

Script Groovy

Configura tu complemento de Datadog para reenviar datos a través de HTTP o DogStatsD usando los scripts Groovy de abajo. Configura el complemento de esta manera podría ser útil si estás ejecutando tu Jenkins Master en un contenedor de Docker usando la imagen oficial de Docker de Jenkins o cualquier derivado compatible con plugins.txt y scripts init Groovy.

Reenvío HTTP usando Groovy

import jenkins.model.*
import org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration

def j = Jenkins.getInstance()
def d = j.getDescriptor("org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration")

// Si deseas utilizar la URL y clave de la API de Datadog para informar a Datadog
d.setReportWith('HTTP')
d.setTargetApiURL('https://api.datadoghq.com/api/')
d.setTargetApiKey('<DATADOG_API_KEY>')

// Personalización, consulta la sección específica a continuación
d.setExcluded('job1,job2')

// Si deseas recopilar logs
d.setLogIntakeUrl('https://http-intake.logs.datadoghq.com/v1/input/')

// Guardar configuración
d.save()

Reenvío de Datadog Agent utilizando Groovy

import jenkins.model.*
import org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration

def j = Jenkins.getInstance()
def d = j.getDescriptor("org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration")

d.setReportWith('DSD')
d.setTargetHost('localhost')
d.setTargetPort(8125)

// Si deseas recopilar logs
d.setTargetLogCollectionPort(10518)
d.setCollectBuildLogs(true)

// Si deseas activar CI Visibility
d.setTargetTraceCollectionPort(8126)
d.setEnableCiVisibility(true)
d.setCiInstanceName("jenkins")

// Personalización, consulta la sección específica a continuación
d.setExcluded('job1,job2')

// Guardar configuración
d.save()

Variables de entorno

Configura tu complemento de Datadog utilizando las variables de entorno con la variable DATADOG_JENKINS_PLUGIN_REPORT_WITH, que especifica el mecanismo de informe a utilizar.

Reenvío HTTP mediante variables de entorno

1. Establece la variable DATADOG_JENKINS_PLUGIN_REPORT_WITH en HTTP.
2. Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_API_URL, que especifica el endpoint de la API de Datadog (por defecto es https://api.datadoghq.com/api/).
3. Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_API_KEY, que especifica tu clave de API de Datadog.
4. (Opcional) Recopilación de logs

• Establece la variable DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS en true para activar la recopilación de logs (desactivada por defecto).
• Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_LOG_INTAKE_URL, que especifica la URL de entrada de logs de Datadog (por defecto https://http-intake.logs.datadoghq.com/v1/input/).

5. (Opcional) CI Visibility (recopilación de trazas):

• Establece la variable DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY en true para activar la CI Visibility (desactivada por defecto).
• Establece la variable DATADOG_JENKINS_TARGET_WEBHOOK_INTAKE_URL, que especifica la URL de entrada del Webhook de Datadog (por defecto es https://webhook-intake.datadoghq.com/api/v2/webhook/).
• Establece la variable DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME, que especifica el nombre de la instancia de Jenkins para CI Visibility (por defecto es jenkins).

Reenvío de Datadog Agent mediante variables de entorno

1. Establece la variable DATADOG_JENKINS_PLUGIN_REPORT_WITH en DSD.
2. Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_HOST, que especifica el host de servidor de DogStatsD (por defecto localhost).
3. Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_PORT, que especifica el puerto del servidor de DogStatsD (por defecto es 8125).
4. (Opcional) Recopilación de logs
   • Habilita recopilación de logs en el Datadog Agent.
   • Establece la variable DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS en true para activar la recopilación de logs (desactivada por defecto).
   • Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT, que especifica el puerto de recopilación de logs de Datadog Agent.
5. (Opcional) CI Visibility (recopilación de trazas):
   • Establece la variable DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY en true para activar la CI Visibility (desactivada por defecto).
   • Establece la variable DATADOG_JENKINS_PLUGIN_TARGET_TRACE_COLLECTION_PORT, que especifica el puerto de recopilación de trazas de Datadog Agent (por defecto 8126).
   • Establece la variable DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME, que especifica el nombre de la instancia de Jenkins para CI Visibility (por defecto es jenkins).

Además, puede utilizar las variables de entorno estándar de Datadog:

• Establece la variable DD_AGENT_HOST, que especifica el host del Datadog Agent.
• Establece la variable DD_AGENT_PORT, que especifica el puerto del servidor de DogStatsD.
• Establece la variable DD_TRACE_AGENT_PORT, que especifica el puerto de recopilación de trazas de Datadog Agent.
• Establece la variable DD_TRACE_AGENT_URL, que especifica la URL de Datadog Agent para enviar trazas. Cuando se establece, tiene prioridad sobre DD_AGENT_HOST y DD_TRACE_AGENT_PORT.

Las variables de entorno con el espacio de nombres DATADOG_JENKINS_PLUGIN tienen prioridad sobre las variables de entorno estándar de Datadog.

Registro

El registro se realiza utilizando java.util.Logger, que sigue las prácticas recomendadas de registro para Jenkins. Para obtener logs, sigue las instrucciones de la documentación de registro de Jenkins. Cuando agregues un registrador, todas las funciones del complemento de Datadog comienzan con org.datadog.jenkins.plugins.datadog. y el nombre de la función que estás buscando debería autocompletarse. En el momento de escribir esto, la única función disponible era org.datadog.jenkins.plugins.datadog.listeners.DatadogBuildListener.

Personalización

Personalización de pipeline

El complemento de Datadog añade un paso datadog que proporciona alguna opción de configuración para tus trabajos basados en pipelines.

En los pipelines declarativos, añade el paso a un bloque de nivel superior de options del siguiente modo:

pipeline {
    agent any
    options {
        datadog(collectLogs: true, tags: ["foo:bar", "bar:baz"])
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello world."
            }
        }
    }
}

En el proceso guiado, envuelve la sección correspondiente con el paso de Datadog de la siguiente manera:

datadog(collectLogs: true, tags: ["foo:bar", "bar:baz"]) {
  node {
    stage('Example') {
      echo "Hello world."
    }
  }
}

Nota: Las personalizaciones de pipeline sólo se registran después de que se haya iniciado un trabajo. Las etiquetas especificadas en la personalización del pipeline no se asociarán con jenkins.job.started.

Personalización global

Para personalizar tu configuración global, en Jenkins ve a Manage Jenkins -> Configure System y haz clic en el botón Advanced (Advanzado). Están disponibles las siguientes opciones:

Personalización del trabajo

Desde una página de configuración específica del trabajo:

Configuración de Test Visibility

El complemento puede automáticamente configurar Datadog Test Visibility para un trabajo o un pipeline (ve la documentación para tu lenguaje de Test Visibility para asegurarte de que el marco de tests que utilizas es compatible; también ten en cuenta que la configuración automática no es compatible para tests que se ejecutan dentro de contenedores; sigue los pasos de instrumentación manual para habilitar Test Visibility para ejecuciones de tests en contenedores).

Antes de activar Test Visibility, asegúrate de configurar el complemento para enviar datos a Datadog.

Hay dos opciones para activar la configuración automática de Test Visibility:

1. Con la interfaz de usuario de Jenkins (disponible en el complemento v5.6.0 o más reciente): ve a la página Configure (Configurar) del trabajo o pipeline cuyos tests necesitan ser rastreados, marca la casilla Enable Datadog Test Visibility (Activar Datadog Test Visibility) en la sección General, y guarda los cambios. Esta opción no está disponible si estás utilizando pipelines de múltiples ramas, carpetas de organización u otros tipos de pipelines que se configuran completamente con Jenkinsfile.
2. Con el paso de pipeline de datadog (disponible en el complemento v5.6.2 o posterior):

En los pipelines declarativos, añade el paso a un bloque de nivel superior de options del siguiente modo:

pipeline {
    agent any
    options {
        datadog(testVisibility: [ 
            enabled: true, 
            serviceName: "my-service", // el nombre de servicio o biblioteca que se está probando
            languages: ["JAVA"], // lenguajes que deben ser instrumentados (las opciones disponibles son "JAVA", "JAVASCRIPT", "PYTHON", "DOTNET")
            additionalVariables: ["my-var": "value"]  // configuración adicional del rastreador (opcional)
        ])
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello world."
            }
        }
    }
}

En los pipelines con script, envuelve la sección correspondiente con el paso datadog de la siguiente manera:

datadog(testVisibility: [ enabled: true, serviceName: "my-service", languages: ["JAVA"], additionalVariables: [:] ]) {
  node {
    stage('Example') {
      echo "Hello world."
    }
  }
}

Los demás ajustes de datadog, como collectLogs o tags, pueden añadirse junto al bloque testVisibility.

Ten en cuenta que Test Visibility es un producto independiente de Datadog que se factura por separado.

Datos recopilados

Este complemento recopila los siguientes eventos, métricas y checks de servicio:

Eventos

Tipo de eventos por defecto

NOTA: event_type está siempre ajustado en default para los eventos y métricas mencionados.

Tipo de eventos de sistemas

NOTA: event_type se establece siempre en system para los anteriores eventos y métricas.

Tipo de eventos de seguridad

NOTA: event_type siempre se establece en security para los anteriores eventos y métricas.

Filtrado de eventos

Este complemento permite filtrar eventos por el tipo de evento así como por los nombres específicos de evento enumerados arriba. Para incluir/excluir todos los eventos del tipo de sistema o de seguridad:

• En la interfaz de usuario: desactiva las casillas de verificación de estos eventos.
• En un script groovy: obtén el descriptor global de Datadog y llama a d.setEmitSystemEvents() o d.setEmitSecurityEvents().
• En la sección variables de entorno: establece las variables de entorno para los eventos de seguridad y de sistema emitidos.

Para obtener un control más específico sobre qué eventos se envían, se proporcionan tres opciones de configuración para permitir una lista de include/exclude (incluir/excluir) separada por comas de cadenas de nombres de evento. La lista include/exclude (incluir/excluir) tiene prioridad sobre el filtrado por tipo de evento. Por ejemplo, los eventos de security pueden desactivarse, pero la inclusión de UserAuthenticated tiene prioridad, por lo que sólo se enviarán eventos de UserAuthenticated del tipo security. En la interfaz de usuario, se proporcionan cuadros de texto para las listas incluir/excluir. En un script groovy, los métodos d.setIncludeEvents() y d.setExcludeEvents() aceptan como entrada una lista de nombres de evento separada por comas, que es otro método válido de configuración. Por último, se proporcionan variables de entorno para configurar manualmente las listas de incluir/excluir.

NOTA: Como se menciona en la sección personalización del trabajo, existen conmutadores específicos de trabajo para enviar eventos SCMCheckout. Si el evento SCMCheckout se excluye globalmente, este conmutador no tendrá ningún efecto.

Métricas

Recopilación de logs para Agents

Nota: Esta configuración sólo se aplica a aquellos que utilizan la configuración del Datadog Agent.

1. La recopilación de logs está desactivada por defecto en el Datadog Agent , actívala en tu archivo datadog.yaml:

   logs_enabled: true
   

2. Para recopilar logs de Jenkins, crea un archivo fuente personalizado de logs para tu Agent creando un conf.yaml dentro de conf.d/jenkins.d con lo siguiente:

   logs:
     - type: tcp
       port: <PORT>
       service: <SERVICE>
       source: jenkins
   

3. En Jenkins, envía el puerto que especificaste anteriormente como Log Collection Port. Puedes establecerlo utilizando variables de entorno, un script Groovy, o la interfaz de usuario de Jenkins.

4. Reinicia el Agent.

Checks de servicio

Crea el estado jenkins.job.status con las siguientes etiquetas predeterminadas: jenkins_url, job, node, user_id

Rastreo de problemas

El sistema de rastreo de problemas integrado en GitHub se utiliza para realizar un rastreo de todos los problemas relacionados con este complemento: jenkinsci/datadog-plugin/issues. Sin embargo, dado cómo se alojan los complementos de Jenkins, pueden haber problemas que también se publiquen en JIRA. Puedes consultar este problema de Jenkins para esas publicaciones de problemas.

Nota: Problemas sin resolver en JIRA que mencionan a Datadog.

Cambios

Consulta el CHANGELOG.md.

Cómo contribuir con código

En primer lugar y lo más importante, gracias por compartir.

Consulta las directrices de contribución antes de enviar un problema o una solicitud pull. Consulta el documento de desarrollo para obtener consejos sobre cómo poner en marcha un entorno de desarrollo local de forma rápida.