Configuration de GitLab pour CI Visibility

Documentation > Continuous Integration Visibility > CI Pipeline Visibility dans Datadog > Configuration de GitLab pour CI Visibility

Présentation

GitLab est une plateforme DevOps qui automatise le cycle de vie du développement logiciel avec des fonctionnalités CI/CD intégrées, permettant le déploiement automatisé et continu d’applications avec des contrôles de sécurité intégrés.

Configurez CI Visibility pour GitLab afin de collecter des données sur vos exécutions de pipeline, d’analyser les goulots d’étranglement de performance, de résoudre les problèmes opérationnels et d’optimiser vos workflows de déploiement.

Compatibilité

Pipeline Visibility	Plateforme	Définition
Pipelines en cours d’exécution	Pipelines en cours d’exécution	Affichez les exécutions de pipeline en cours d’exécution. Les pipelines en file d’attente ou en attente s’affichent avec le statut « Running » sur Datadog.
Jobs en cours d’exécution	Jobs en cours d’exécution	Affichez les exécutions de jobs actuellement en cours d’exécution.
Analyse des logs	Analyse des logs	Utilise des modèles LLM sur les logs pertinents pour analyser la cause racine des jobs CI ayant échoué.
Corrélation des logs	Corrélation des logs	Corréler les spans de pipeline aux logs. Nécessite le Stockage des logs.
Filtrer les jobs CI sur le chemin critique	Filtrer les jobs CI sur le chemin critique	Filtrez par jobs sur le chemin critique.
Réessais partiels	Pipelines partiels	Affichez les exécutions de pipeline ayant fait l’objet de réessais partiels.
Réessais automatiques de jobs	Réessais automatiques de jobs	Datadog réessaie les jobs ayant échoué classés comme transitoires par son modèle d’erreur IA.
Étapes manuelles	Étapes manuelles	Affichez les pipelines déclenchés manuellement.
Temps de file d’attente	Temps de file d’attente	Affichez la durée pendant laquelle les jobs de pipeline restent dans la file d’attente avant d’être traités.
Corrélation des métriques d’infrastructure	Corrélation des métriques d’infrastructure	Corrélez les jobs aux métriques de host d’infrastructure pour les runners GitLab auto-hébergés.
Tags prédéfinis personnalisés	Tags prédéfinis personnalisés	Définissez des tags personnalisés pour tous les spans générés de pipeline, de phase et de job.
Tags personnalisés et mesures au moment de l’exécution	Tags et mesures personnalisés au moment de l’exécution	Configurez des tags et mesures personnalisés au moment de l’exécution.
Paramètres	Paramètres	Définissez des paramètres `env` ou `service` personnalisés lorsqu’un pipeline est déclenché.
Raisons d’échec du pipeline	Raisons d’échec du pipeline	Identifiez les raisons d’échec du pipeline à partir des messages d’erreur.
Temps d’attente d’approbation	Temps d’attente d’approbation	Affichez la durée pendant laquelle les jobs et les pipelines attendent des approbations manuelles.
Temps d’exécution	Temps d’exécution	Affichez la durée pendant laquelle les pipelines ont exécuté des jobs. Gitlab désigne cette métrique sous le nom de `duration`. La durée dans Gitlab et le temps d’exécution peuvent afficher des valeurs différentes. Gitlab ne prend pas en considération les jobs qui ont échoué en raison de certains types de défaillances (telles que les défaillances du système de runner).
Spans personnalisés	Spans personnalisés	Configurez des spans personnalisés pour vos pipelines.

Les versions de GitLab suivantes sont prises en charge :

GitLab.com (SaaS)
GitLab >= 14.1 (auto-hébergé)
GitLab >= 13.7.0 (auto-hébergé) avec le feature flag datadog_ci_integration activé

Terminologie

Ce tableau présente la correspondance des concepts entre Datadog CI Visibility et GitLab :

Datadog	GitLab
Pipeline	Pipeline
Phase	Étape
Job	Job
Non disponible dans Datadog	Script

Configurer l’intégration Datadog

Configurez l’intégration sur un projet ou un groupe en accédant à Settings > Integrations > Datadog pour chaque projet ou groupe que vous souhaitez instrumenter.

Remplissez les paramètres de configuration de l’intégration :

Active: Active l’intégration.
Datadog site: Spécifie le site Datadog vers lequel envoyer les données.
Par défaut : datadoghq.com
Site sélectionné :
API URL (facultatif): Permet de remplacer l’URL de l’API utilisée pour l’envoi direct de données, uniquement utilisé dans des scénarios avancés.
Par défaut: (vide, aucun remplacement)
API key: Spécifie la clé d’API Datadog à utiliser lors de l’envoi de données.
Enable CI Visibility: Contrôle l’activation des fonctionnalités de CI Visibility, y compris le traçage des pipelines, le calcul du chemin critique et la surveillance des performances. Assurez-vous que cette case est cochée pour activer ces fonctionnalités.
Service (facultatif): Spécifie le nom de service à associer à chaque span généré par l’intégration. Utilisez ceci pour différencier les instances GitLab.
Par défaut: gitlab-ci
Env (facultatif): Spécifie l’environnement (tag env) à associer à chaque span généré par l’intégration. Utilisez ceci pour différencier les groupes d’instances GitLab (par exemple, pré-production ou production).
Par défaut : none
Tags (facultatif): Spécifie tous les tags personnalisés à associer à chaque span généré par l’intégration. Fournissez un tag par ligne au format : key:value.
Par défaut : (vide, aucun tag supplémentaire)
Remarque : Disponible uniquement sur GitLab.com et GitLab >= 14.8 auto-hébergé.

Vous pouvez tester l’intégration avec le bouton Test settings (disponible uniquement lors de la configuration de l’intégration sur un projet). Une fois l’opération réussie, cliquez sur Save changes pour terminer la configuration de l’intégration. Si le bouton échoue, cliquez sur Save changes et vérifiez que les premiers webhooks envoyés sont réussis en consultant l’historique dans la section « Événements récents » ci-dessous.

Configurez l’intégration sur un projet ou un groupe en accédant à Settings > Integrations > Datadog pour chaque projet ou groupe que vous souhaitez instrumenter. Vous pouvez également activer l’intégration au niveau de l’instance GitLab en allant dans Admin > Settings > Integrations > Datadog.

Remplissez les paramètres de configuration de l’intégration :

Active: Active l’intégration.
Datadog site: Spécifie le site Datadog vers lequel envoyer les données.
Par défaut : datadoghq.com
Site sélectionné :
API URL (facultatif): Permet de remplacer l’URL de l’API utilisée pour l’envoi direct de données, uniquement utilisé dans des scénarios avancés.
Par défaut: (vide, aucun remplacement)
API key: Spécifie quelle clé d’API Datadog utiliser lors de l’envoi de données.
Enable CI Visibility: Contrôle l’activation des fonctionnalités de CI Visibility, y compris le traçage des pipelines, le calcul du chemin critique et la surveillance des performances. Assurez-vous que cette case est cochée pour activer ces fonctionnalités. Elle n’est présente qu’à partir de GitLab 17.7 et n’est pas requise dans les versions antérieures.
Service (facultatif): Spécifie le nom de service à associer à chaque span généré par l’intégration. Utilisez ceci pour différencier les instances GitLab.
Par défaut: gitlab-ci
Env (facultatif): Spécifie l’environnement (tag env) à associer à chaque span généré par l’intégration. Utilisez ceci pour différencier les groupes d’instances GitLab (par exemple, pré-production ou production).
Par défaut : none
Tags (facultatif): Spécifie tous les tags personnalisés à associer à chaque span généré par l’intégration. Fournissez un tag par ligne au format : key:value.
Par défaut : (vide, aucun tag supplémentaire)
Remarque : Disponible uniquement sur GitLab.com et GitLab >= 14.8 auto-hébergé.

Activez le datadog_ci_integration feature flag 101 pour activer l’intégration.

Exécutez l’une des commandes suivantes, qui utilisent le Rails Runner de GitLab, selon votre type d’installation :

Depuis les installations Omnibus :

sudo gitlab-rails runner "Feature.enable(:datadog_ci_integration)"

Depuis les installations à partir des sources :

sudo -u git -H bundle exec rails runner \
  -e production \
  "Feature.enable(:datadog_ci_integration)"

Depuis Installations Kubernetes :

kubectl exec -it <task-runner-pod-name> -- \
  /srv/gitlab/bin/rails runner "Feature.enable(:datadog_ci_integration)"

Ensuite, configurez l’intégration sur un project en allant dans Settings > Integrations > Datadog pour chaque projet que vous souhaitez instrumenter.

En raison d'un bug dans les premières versions de GitLab, l'intégration Datadog ne peut pas être activée au niveau groupe ou instance sur les versions de GitLab < 14.1, même si l'option est disponible dans l'interface utilisateur de GitLab.

Remplissez les paramètres de configuration de l’intégration :

Active: Active l’intégration.
Datadog site: Spécifie le site Datadog vers lequel envoyer les données.
Par défaut : datadoghq.com
Site sélectionné :
API URL (facultatif): Permet de remplacer l’URL de l’API utilisée pour l’envoi direct de données, uniquement utilisé dans des scénarios avancés.
Par défaut: (vide, aucun remplacement)
API key: Spécifie quelle clé d’API Datadog utiliser lors de l’envoi de données.
Service (facultatif): Spécifie le nom de service à associer à chaque span généré par l’intégration. Utilisez ceci pour différencier les instances GitLab.
Par défaut: gitlab-ci
Env (facultatif): Spécifie l’environnement (tag env) à associer à chaque span généré par l’intégration. Utilisez ceci pour différencier les groupes d’instances GitLab (par exemple, pré-production ou production).
Par défaut : none
Tags (facultatif): Spécifie tous les tags personnalisés à associer à chaque span généré par l’intégration. Fournissez un tag par ligne au format : key:value.
Par défaut : (vide, aucun tag supplémentaire)
Remarque : Disponible uniquement sur GitLab.com et GitLab >= 14.8 auto-hébergé.

Le support direct avec les webhooks n'est pas en cours de développement. Des problèmes inattendus pourraient survenir. Datadog vous recommande de mettre à jour GitLab.

Pour les versions plus anciennes de GitLab, vous pouvez utiliser webhooks pour envoyer des données de pipeline à Datadog.

Allez dans Settings > Webhooks dans votre dépôt (ou les paramètres de l’instance GitLab), et ajoutez un nouveau webhook :

URL : https://webhook-intake./api/v2/webhook/?dd-api-key=<API_KEY> où <API_KEY> est votre clé d’API Datadog.
Secret Token : Laissez ce champ vide.
Trigger : Sélectionnez Job events et Pipeline events.

Pour définir des paramètres env ou service personnalisés, ajoutez d’autres paramètres de requête dans l’URL des webhooks. Par exemple, &env=<YOUR_ENV>&service=<YOUR_SERVICE_NAME>.

Définir des tags personnalisés

Pour définir des tags personnalisés pour tous les spans de pipeline et de job générés par l’intégration, ajoutez un paramètre de requête encodé en URL tags avec des paires key:value séparées par des virgules à l’URL.

Si une paire clé:valeur contient des virgules, entourez-la de guillemets : Par exemple, pour ajouter key1:value1,"key2: value with , comma",key3:value3, la chaîne suivante devrait être ajoutée au Webhook URL : ?tags=key1%3Avalue1%2C%22key2%3A+value+with+%2C+comma%22%2Ckey3%3Avalue3.

Configuration avancée

Définir un nom de pipeline

Par défaut, Datadog utilise le chemin de votre projet GitLab comme nom de pipeline. Par conséquent, chaque pipeline en aval (enfant) déclenché avec le mot-clé trigger depuis le même projet apparaît sous le même nom dans Datadog.

Pour donner un nom plus significatif à un pipeline, utilisez le mot-clé workflow:name de GitLab dans votre .gitlab-ci.yml. Par exemple, pour nommer un pipeline en aval d’après le job qui l’a déclenché :

trigger-job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
  variables:
    CHILD_PIPELINE_NAME: $CI_JOB_NAME

Dans le .gitlab-ci.yml du pipeline enfant (ou un fichier qu’il inclut), utilisez la variable transmise pour définir le nom du pipeline :

workflow:
  name: '$CHILD_PIPELINE_NAME'

Remarque : L’exemple ci-dessus utilise l’expansion de variable dans le nom du pipeline, ce qui nécessite GitLab 16.3 ou une version ultérieure. workflow:name lui-même est disponible à partir de GitLab 15.11 pour les noms sous forme de chaîne de caractères simple. Le nom du pipeline n’est visible dans Datadog qu’à partir de GitLab 16.1, date à laquelle il a été ajouté à la charge utile du webhook de pipeline.

Définir des tags personnalisés

Vous pouvez définir des tags personnalisés pour tous les spans de pipeline et de job à partir de vos projets GitLab afin d’améliorer la traçabilité. Pour plus d’informations, consultez Tags et mesures personnalisés.

Intégration avec Datadog Teams

Pour afficher et filtrer les équipes associées à vos pipelines, ajoutez team:<your-team> comme tag personnalisé. Le nom du tag personnalisé doit correspondre exactement à l’identifiant de votre équipe Datadog Teams.

Corréler les métriques d’infrastructure aux jobs

Si vous utilisez des runners GitLab auto-hébergés, vous pouvez corréler les jobs avec l’infrastructure qui les exécute.

La corrélation d’infrastructure Datadog est possible en utilisant différentes méthodes :

Le runner GitLab doit avoir un tag sous la forme host:<hostname>. Les tags peuvent être ajoutés lors de l’enregistrement d’un nouveau runner. Par conséquent, cette méthode n’est disponible que lorsque le runner exécute directement le job.

Cela exclut les exécuteurs qui mettent à l’échelle l’infrastructure automatiquement afin d’exécuter le job (tels que les exécuteurs Kubernetes, Docker Autoscaler ou Instance), car il n’est pas possible d’ajouter des tags dynamiquement pour ces runners.

Pour les runners existants :

GitLab >= 15.8 : Ajoutez des tags via l’interface utilisateur en allant dans Settings > CI/CD > Runners et en modifiant le runner approprié.
GitLab < 15.8 : Ajoutez des tags en mettant à jour le config.toml du runner. Ou ajoutez des tags via l’interface utilisateur en allant dans Settings > CI/CD > Runners et en modifiant le runner approprié.

Après ces étapes, CI Visibility ajoute le nom de host à chaque job. Pour voir les métriques, cliquez sur un span de job dans la vue des traces. Dans le panneau latéral, un nouvel onglet nommé Infrastructure apparaît, contenant les métriques du host.

CI Visibility prend en charge les métriques d’infrastructure pour les exécuteurs « Docker Autoscaler » via une corrélation basée sur les logs. Pour activer cette fonctionnalité, assurez-vous que les logs de job GitLab sont indexés afin que Datadog puisse lier les jobs aux hosts, et que les logs incluent des messages sous la forme Instance <hostname> connected. Les logs de job GitLab incluent les tags datadog.product:cipipeline et source:gitlab, que vous pouvez utiliser dans les filtres Log Indexes. Les utilisateurs ont également besoin d’un accès en lecture aux logs pour voir les données d’infrastructure dans ce scénario. Pour plus d’informations, consultez le guide de corrélation des métriques d’infrastructure avec les jobs GitLab.

CI Visibility prend en charge les métriques d’infrastructure pour les exécuteurs « Instance » via une corrélation basée sur les logs. Pour activer cette fonctionnalité, assurez-vous que les logs de job GitLab sont indexés afin que Datadog puisse lier les jobs aux hosts, et que les logs incluent des messages sous la forme Instance <hostname> connected. Les logs de job GitLab incluent les tags datadog.product:cipipeline et source:gitlab, que vous pouvez utiliser dans les filtres Log Indexes. Les utilisateurs ont également besoin d’un accès en lecture aux logs pour voir les informations d’infrastructure dans ce scénario. Pour plus d’informations, consultez le guide de corrélation des métriques d’infrastructure avec les jobs GitLab.

CI Visibility prend en charge les métriques d’infrastructure pour l’exécuteur Kubernetes. Pour cela, il est nécessaire que le Datadog Agent surveille l’infrastructure Kubernetes GitLab. Consultez Installer le Datadog Agent sur Kubernetes pour installer le Datadog Agent dans un cluster Kubernetes.

En raison des limitations du Datadog Agent, les jobs plus courts que l’intervalle de collecte minimal du Datadog Agent pourraient ne pas toujours afficher les métriques de corrélation d’infrastructure. Pour ajuster cette valeur, réglez min_collection_interval sur moins de 15 secondes dans votre fichier de configuration de l’Agent.

CI Visibility ne prend pas en charge les métriques d’infrastructure pour les autres exécuteurs.

Afficher les messages d’erreur pour les échecs de pipeline

Pour les exécutions de pipeline GitLab ayant échoué, chaque erreur sous l’onglet Errors au sein d’une exécution de pipeline spécifique affiche un message associé au type d’erreur provenant de GitLab.

Erreurs fournies par GitLab

Les messages d’erreur sont pris en charge pour les versions 15.2.0 ou supérieures de GitLab.

Les informations d’erreur fournies par GitLab sont stockées dans les tags error.provider_message et error.provider_domain.

Le tableau suivant décrit le message et le domaine corrélés à chaque type d’erreur. Tout type d’erreur non répertorié entraîne un message d’erreur Job failed et un domaine d’erreur unknown.

Type d’erreur	Domaine d’erreur	Message d’erreur
`unknown_failure`	inconnu	Échec dû à une raison inconnue.
`config_error`	utilisateur	Échec dû à une erreur dans le fichier de configuration CI/CD.
`external_validation_failure`	inconnu	Échec dû à une validation de pipeline externe.
`user_not_verified`	utilisateur	Le pipeline a échoué car l’utilisateur n’a pas été vérifié.
`activity_limit_exceeded`	fournisseur	La limite d’activité du pipeline a été dépassée.
`size_limit_exceeded`	fournisseur	La limite de taille du pipeline a été dépassée.
`job_activity_limit_exceeded`	fournisseur	La limite d’activité des jobs du pipeline a été dépassée.
`deployments_limit_exceeded`	fournisseur	La limite de déploiements du pipeline a été dépassée.
`project_deleted`	fournisseur	Le projet associé à ce pipeline a été supprimé.
`api_failure`	fournisseur	Échec de l’API.
`stuck_or_timeout_failure`	inconnu	Le pipeline est bloqué ou a expiré.
`runner_system_failure`	fournisseur	Échec dû à une défaillance du système de l’exécuteur.
`missing_dependency_failure`	inconnu	Échec dû à une dépendance manquante.
`runner_unsupported`	fournisseur	Échec dû à un exécuteur non pris en charge.
`stale_schedule`	fournisseur	Échec dû à un planning obsolète.
`job_execution_timeout`	inconnu	Échec dû à un dépassement de délai du job.
`archived_failure`	fournisseur	Échec d’archivage.
`unmet_prerequisites`	inconnu	Échec dû à un prérequis non satisfait.
`scheduler_failure`	fournisseur	Échec dû à une erreur de planning.
`data_integrity_failure`	fournisseur	Échec dû à un problème d’intégrité des données.
`forward_deployment_failure`	inconnu	Échec du déploiement.
`user_blocked`	utilisateur	Bloqué par l’utilisateur.
`ci_quota_exceeded`	fournisseur	Quota CI dépassé.
`pipeline_loop_detected`	utilisateur	Boucle de pipeline détectée.
`builds_disabled`	utilisateur	Build désactivé.
`deployment_rejected`	utilisateur	Déploiement rejeté.
`protected_environment_failure`	fournisseur	Échec de l’environnement.
`secrets_provider_not_found`	utilisateur	Fournisseur de secret introuvable.
`reached_max_descendant_pipelines_depth`	utilisateur	Nombre maximal de pipelines descendants atteint.
`ip_restriction_failure`	fournisseur	Échec de la restriction IP.

Gérer les logs de jobs

Analyse des logs

L’Analyse des logs utilise des modèles LLM pour classer les échecs de jobs par cause racine en fonction des logs pertinents provenant de GitLab.

Pour une explication complète, consultez le guide sur l’utilisation de l’Analyse des logs.

L’Analyse des logs est activée par défaut dans Datadog, mais nécessite que le transfert des logs de jobs soit configuré, comme décrit ci-dessous.

Vous pouvez également ajouter l’Analyse des logs à un commentaire de PR. Consultez le guide sur l’utilisation des commentaires de PR.

L’activation de l’Analyse des logs est également un prérequis pour les réessais automatiques de jobs.

Les versions de GitLab suivantes prennent en charge le transfert des logs de jobs vers Datadog :

GitLab.com (SaaS)
GitLab >= 15.3 (auto-hébergé) uniquement si vous utilisez le stockage d’objets pour stocker les logs des jobs
GitLab >= 14.8 (auto-hébergé) en activant le feature flag datadog_integration_logs_collection

Pour activer le transfert des logs de jobs depuis GitLab :

Cochez la case Enable job logs collection dans l’intégration GitLab Settings > Integrations > Datadog.
Cliquez sur Save changes.

Datadog télécharge les fichiers logs directement depuis votre stockage d'objets de logs GitLab avec des URL temporaires pré-signées. Cela signifie que pour que les serveurs Datadog puissent accéder au stockage, celui-ci ne doit pas avoir de restrictions réseau L'endpoint, s'il est défini, doit pointer vers une URL accessible publiquement.

Cochez la case Enable job logs collection dans l’intégration GitLab sous Settings > Integrations > Datadog.
Cliquez sur Save changes.

Activez le datadog_integration_logs_collection feature flag dans votre GitLab. Cela vous permet de voir la Enable job logs collection case à cocher dans l’intégration GitLab sous Settings > Integrations > Datadog.
Cliquez sur Enable job logs collection.
Cliquez sur Save changes.

Stockage des logs

Une fois les étapes pour votre version de GitLab terminées, accédez aux paramètres du dépôt CI/CD et activez le Stockage des logs au niveau de l’organisation Datadog ou pour les dépôts souhaités.

Logs Storage est facturé séparément de CI Visibility. La rétention, l’exclusion et les index des logs sont configurés dans Log Management. Les logs des jobs GitLab peuvent être identifiés par les tags datadog.product:cipipeline et source:gitlab.

Les logs des jobs sont collectés dans Log Management et sont automatiquement corrélés avec le pipeline GitLab dans CI Visibility. Les fichiers logs de plus d’un Gio sont tronqués.

Pour plus d’informations sur le traitement des logs de jobs collectés via l’intégration GitLab, consultez la documentation des processeurs.

Afficher les pipelines partiels et en aval

Vous pouvez utiliser les filtres suivants pour personnaliser votre requête de recherche dans le CI Visibility Explorer.

La page des exécutions de pipeline avec « Partial Pipeline:retry » saisi dans la requête de recherche.

Nom de la facette	ID de la facette	Valeurs possibles
Pipeline en aval	`@ci.pipeline.downstream`	`true`, `false`
Déclenché manuellement	`@ci.is_manual`	`true`, `false`
Partial Pipeline	`@ci.partial_pipeline`	`retry`, `paused`, `resumed`

Vous pouvez également appliquer ces filtres en utilisant le panneau des facettes sur le côté gauche de la page.

Le panneau des facettes avec la facette « Partial Pipeline » développée et la valeur « Retry » sélectionnée, ainsi que la facette « Partial Retry » développée et la valeur « true » sélectionnée.

Visualisez les données de pipeline dans Datadog

Une fois l’intégration configurée avec succès, les pages CI Pipeline List et Executions sont alimentées en données une fois les pipelines terminés.

La page CI Pipeline List affiche uniquement les données de la branche par défaut de chaque dépôt. Pour plus d’informations, consultez Search and Manage CI Pipelines.