Ce plug-in Jenkins transmet automatiquement des métriques, des événements et des checks de service à un compte Datadog.

Remarque : la page du plug-in d’intégration continue Jenkins (disponible en anglais) reprend les informations de cette page.

Configuration

Installation

Ce plug-in nécessite Jenkins 2.346.1.

Pour les anciennes versions de Jenkins (c’est-à-dire 1.632+), vous trouverez la version 1.2.0 du plug-in ici.

Installez le plug-in depuis l’Update Center (disponible en accédant à Manage Jenkins -> Manage Plugins) dans votre installation Jenkins :

1. Sélectionnez l’onglet Available, cherchez Datadog, puis cochez la case en regard de l’option Datadog Plugin.
2. Installez le plug-in en cliquant sur l’un des deux boutons en bas de l’écran.
3. Pour vérifier que le plug-in est installé, cherchez Datadog Plugin dans l’onglet Installed.

Poursuivez votre lecture pour découvrir comment configurer le plug-in.

Remarque : si une version inattendue de Datadog Plugin s’affiche, accédez à Manage Jenkins, puis exécutez la commande Check Now depuis l’écran Manage Plugins.

Configuration

Vous pouvez configurer votre plug-in de deux façons différentes pour transmettre des données à Datadog :

• En utilisant un Agent Datadog en tant que redirecteur entre Jenkins et Datadog (méthode recommandée).
  • Si vous utilisez un serveur DogStatsD à la place d’un Agent Datadog complet, seuls les événements et les métriques sont pris en charge.
  • Pour les données envoyées depuis un host externe, l’Agent Datadog exige la configuration suivante : dogstatsd_non_local_traffic: true et apm_non_local_traffic: true. Ces paramètres peuvent être configurés à l’aide du fichier de configuration datadog.yaml.
• En envoyant directement les données à Datadog via HTTP.
  • L’implémentation du client HTTP utilisée dispose d’un délai d’expiration d’une minute. En cas de problème de connexion avec Datadog, cela peut ralentir votre instance Jenkins.

Cette configuration peut être effectuée depuis l’interface utilisateur du plug-in avec un script Groovy ou à l’aide de variables d’environnement.

Interface utilisateur du plug-in

Pour configurer votre plug-in Datadog, accédez à Manage Jenkins -> Configure System depuis votre installation Jenkins. Faites ensuite défiler l’écran jusqu’à atteindre la section Datadog Plugin :

Transmission HTTP

1. Cliquez sur le bouton radio en regard de l’option Use Datadog API URL and Key to report to Datadog (sélectionnée par défaut).
2. Collez votre clé d’API Datadog dans le champ API Key de l’écran de configuration de Jenkins. Si vous souhaitez stocker votre clé d’API dans le gestionnaire d’identifiants, créez un identifiant pour la clé d’API et sélectionnez-le dans la liste déroulante Datadog API Key (Select from Credentials).
3. Testez votre clé d’API Datadog à l’aide du bouton Test Key situé en dessous, sur ce même écran.
4. (Facultatif) Saisissez le hostname du serveur Jenkins dans l’onglet Advanced afin de l’inclure dans les événements.
5. (Facultatif) Saisissez votre URL d’admission des logs Datadog et sélectionnez Enable Log Collection dans l’onglet Advanced.
6. (Facultatif) Sélectionnez l’option Enable CI Visibility. Vous avez également la possibilité de définir le nom de votre instance CI.
7. Enregistrez votre configuration.

Transmission de données par l’Agent Datadog

1. Cliquez sur le bouton radio correspondant à l’option Use the Datadog Agent to report to Datadog.
2. Indiquez le hostname et le port de votre Agent Datadog.
3. (Facultatif) Saisissez le hostname du serveur Jenkins dans l’onglet Advanced afin de l’inclure dans les événements.
4. (Facultatif) Spécifiez votre port de collecte des logs, configurez la collecte de logs pour l’Agent Datadog, puis sélectionnez Enable Log Collection.
5. (Facultatif) Saisissez votre port de collecte de traces et sélectionnez Enable Ci Visibility. Vous avez également la possibilité de définir le nom de votre instance CI.
6. Enregistrez votre configuration.

Script Groovy

Configurez votre plug-in Datadog à l’aide des scripts Groovy ci-dessous pour transmettre des données via HTTP ou à l’aide de DogStatsD. Ce type de configuration s’avère particulièrement utile si vous exécutez votre Master Jenkins dans un conteneur Docker à l’aide de l’image Docker Jenkins officielle ou de toute autre solution alternative prenant en charge plugins.txt et les scripts init Groovy.

Transmission HTTP avec 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 vous souhaitez utiliser l'URL et la clé de l'API Datadog pour transmettre vos données à Datadog
d.setReportWith('HTTP')
d.setTargetApiURL('https://api.datadoghq.com/api/')
d.setTargetApiKey('<CLÉ_API_DATADOG>')

// Personnalisation, voir la section dédiée ci-dessous
d.setExcluded('job1,job2')

// Si vous souhaitez recueillir les logs
d.setLogIntakeUrl('https://http-intake.logs.datadoghq.com/v1/input/')

// Enregistrer la configuration
d.save()

Transmission de données par l’Agent Datadog avec 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)

// Pour recueillir des logs
d.setTargetLogCollectionPort(10518)
d.setCollectBuildLogs(true)

// Pour activer CI Visibility
d.setTargetTraceCollectionPort(8126)
d.setEnableCiVisibility(true)
d.setCiInstanceName("jenkins")

// Personnalisation, voir la section dédiée ci-dessous
d.setExcluded('job1,job2')

// Enregistrer la configuration
d.save()

Variables d’environnement

Configurez votre plug-in Datadog avec des variables d’environnement à l’aide de la variable DATADOG_JENKINS_PLUGIN_REPORT_WITH, qui indique le processus de transmission à utiliser.

Transmission HTTP avec des variables d’environnement

1. Définissez la variable DATADOG_JENKINS_PLUGIN_REPORT_WITH sur HTTP.
2. Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_API_URL, qui indique l’endpoint de l’API Datadog (valeur par défaut : https://api.datadoghq.com/api/).
3. Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_API_KEY, qui indique votre clé d’API Datadog.
4. (Facultatif) Collecte de logs :

• Définissez la variable DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS sur true pour activer la collecte de logs (désactivée par défaut).
• Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_LOG_INTAKE_URL, qui indique l’URL d’admission des logs Datadog (valeur par défaut : https://http-intake.logs.datadoghq.com/v1/input/).

5. (Facultatif) CI Visibility (collecte de traces) :

• Définissez la variable DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY sur true pour activer CI Visibility (désactivé par défaut).
• Définissez la variable DATADOG_JENKINS_TARGET_WEBHOOK_INTAKE_URL, qui spécifie l’URL d’admission du Webhook Datadog (valeur par défaut : https://webhook-intake.datadoghq.com/api/v2/webhook/).
• Définissez la variable DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME, qui spécifie le nom de l’instance Jenkins pour CI Visibility (jenkins par défaut).

Transmission de données par l’Agent Datadog avec des variables d’environnement

1. Définissez la variable DATADOG_JENKINS_PLUGIN_REPORT_WITH sur DSD.
2. Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_HOST, qui indique le host du serveur DogStatsD (valeur par défaut : localhost).
3. Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_PORT, qui indique le port du serveur DogStatsD (valeur par défaut : 8125).
4. (Facultatif) Collecte de logs :
   • Activez la collecte de log pour l’Agent Datadog.
   • Définissez la variable DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS sur true pour activer la collecte de logs (désactivée par défaut).
   • Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT, qui indique le port de collecte de logs de l’Agent Datadog.
5. (Facultatif) CI Visibility (collecte de traces) :
   • Définissez la variable DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY sur true pour activer CI Visibility (désactivé par défaut).
   • Définissez la variable DATADOG_JENKINS_PLUGIN_TARGET_TRACE_COLLECTION_PORT, qui indique le port de collecte de traces de l’Agent Datadog (8126 par défaut).
   • Définissez la variable DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME, qui spécifie le nom de l’instance Jenkins pour CI Visibility (jenkins par défaut).

Vous avez également la possibilité d’utiliser les variables d’environnement Datadog standard :

• Définissez la variable DD_AGENT_HOST, qui indique le host de l’Agent Datadog.
• Définissez la variable DD_AGENT_PORT, qui indique le port du serveur DogStatsD.
• Définissez la variable DD_TRACE_AGENT_PORT, qui indique le port de collecte de traces de l’Agent Datadog.
• Définissez la variable DD_TRACE_AGENT_URL, qui indique l’URL de l’Agent Datadog vers laquelle les traces doivent être envoyées. Lorsque cette variable est définie, elle a la priorité sur DD_AGENT_HOST et DD_TRACE_AGENT_PORT.

Les variables d’environnement avec l’espace de nommage DATADOG_JENKINS_PLUGIN ont la priorité sur les variables d’environnement Datadog standard.

Journalisation

La journalisation repose sur l’utilisation de java.util.Logger, un logger qui respecte les meilleures pratiques en matière de journalisation de Jenkins. Pour obtenir des logs, suivez les instructions de la documentation sur la journalisation de Jenkins (en anglais). Lorsque vous ajoutez le logger, le préfixe org.datadog.jenkins.plugins.datadog. est ajouté au nom de toutes les fonctions du plug-in Datadog. Au moment de la rédaction de cette page, seule la fonction org.datadog.jenkins.plugins.datadog.listeners.DatadogBuildListener était disponible.

Personnalisation

Personnalisation des pipelines

Le plug-in Datadog ajoute une étape datadog qui permet de personnaliser vos tâches basées sur des pipelines.

Dans les pipelines déclaratifs, ajoutez l’étape dans un bloc options de premier niveau, comme suit :

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

Dans un pipeline scripté, incorporez la section concernée dans l’étape Datadog comme suit :

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

Remarque : les personnalisations de pipeline entrent uniquement en compte après le début d’une tâche. Les tags indiqués dans la personnalisation ne seront pas associés à jenkins.job.started.

Personnalisation globale

Pour personnaliser votre configuration globale, dans Jenkins, accédez à Manage Jenkins -> Configure System, puis cliquez sur le bouton Advanced. Voici la liste des options disponibles :

Personnalisation des tâches

Depuis la page de configuration d’une tâche spécifique :

Données collectées

Ce plug-in recueille les événements, métriques et checks de service suivants :

Events

Type d’événement par défaut

REMARQUE : event_type est toujours défini sur default pour les métriques et événements ci-dessus.

Type des événements système

REMARQUE : event_type est toujours défini sur system pour les métriques et événements ci-dessus.

Type des événements de sécurité

REMARQUE : event_type est toujours défini sur security pour les métriques et événements ci-dessus.

Métriques

Collecte de logs avec l’Agent

Remarque : cette configuration est uniquement valable si vous utilisez l’Agent Datadog.

1. La collecte de logs est désactivée par défaut dans l’Agent Datadog. Vous devez l’activer dans datadog.yaml :

   logs_enabled: true
   

2. Pour recueillir vos logs Jenkins, créez un fichier source de collecte de logs personnalisé pour votre Agent. Pour ce faire, créez un fichier conf.yaml au sein de conf.d/jenkins.d avec le contenu suivant :

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

3. Dans Jenkins, transmettez le port défini lors des étapes précédentes en tant que Log Collection Port. Vous pouvez définir ce port à l’aide de variables d’environnement, d’un script Groovy ou de l’interface Jenkins.

4. Redémarrez l’Agent.

Checks de service

Le statut du build jenkins.job.status avec les tags par défaut : jenkins_url, job, node et user_id.

Suivi des problèmes

Le système de suivi des problèmes intégré à GitHub vous permet de surveiller tous les problèmes liés à ce plug-in : jenkinsci/datadog-plugin/issues. Cependant, compte tenu du processus d’hébergement des plug-ins Jenkins, certains problèmes peuvent également être publiés sur JIRA. Vous pouvez consulter ce problème Jenkins pour vérifier comment les problèmes sont publiés.

Remarque : voici les bugs non résolus sur JIRA traitant de Datadog.

Changements

Consultez le fichier CHANGELOG.md.

Comment contribuer au code

Tout d’abord, merci de contribuer à ce projet.

Lisez les règles de contribution (en anglais) avant d’envoyer un problème ou une pull request. Consultez le document relatif au développement (en anglais) pour obtenir des conseils et faire tourner un environnement de développement local rapide.