Le suivi des déploiements APM peut être configuré comme source de données pour les déploiements dans les métriques DORA.

Exigences

• APM Deployment Tracking est activé en tant que source de données d’événements Deployments dans les paramètres DORA.
• Votre service a métadonnées définies dans le catalogue logiciel.
• Votre service a étiquetage de service unifié activé. Les déploiements sont identifiés à l’aide de l’étiquette version.

Pour plus d’informations sur la garantie que les déploiements de service suivis par APM contribuent au délai de changement, voir Enrichir les déploiements avec des informations de commit.

Pour envoyer vos propres événements de déploiement, utilisez l’API des métriques DORA ou la commande datadog-ci dora deployment.

Exigences

• datadog-ci CLI / API est activé en tant que source de données d’événements Deployments dans les paramètres DORA.
• Les attributs suivants sont requis :
• started_at : Le moment où le déploiement a commencé.
• finished_at : Le moment où le déploiement a fini.
• service : Le service qui a été déployé. Si le service fourni est enregistré dans le catalogue logiciel avec des métadonnées configurées (voir Ajout de métadonnées), le team du service est automatiquement récupéré et associé à toutes les métriques.

Vous pouvez ajouter en option les attributs suivants aux événements de déploiement :

• repository_url : Le dépôt de code source du service. Nécessaire pour calculer le délai de changement.
• commit_sha : Le SHA du commit HEAD associé au déploiement. Nécessaire pour calculer le délai de changement.
• team : Associer un déploiement à un team différent de celui trouvé automatiquement pour le service.
• env : Filtrer vos métriques DORA par environnement sur la page Métriques DORA.
• id : Identifier un déploiement. Cet attribut est généré par l’utilisateur ; lorsqu’il n’est pas fourni, le point de terminaison renvoie un UUID généré par Datadog.
• version : La version du déploiement.
• custom_tags : Étiquettes sous la forme key:value qui peuvent être utilisées pour filtrer les événements sur la page Métriques DORA.

Exemple d’API (cURL)

Consultez la documentation de référence dédiée à l’API DORA Metrics pour consulter les spécifications complètes ainsi que d’autres exemples de code.

Pour l’exemple suivant, remplacez <DD_SITE> dans l’URL par et ${DD_API_KEY} par votre Clé API Datadog :

  curl -X POST "https://api.<DD_SITE>/api/v2/dora/deployment" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "service": "shopist",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "team": "backend",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF

Exemple CLI

L’outil CLI datadog-ci fournit un raccourci pour envoyer des événements de déploiement dans votre environnement d’intégration continue.

Pour l’exemple suivant, définissez la variable d’environnement DD_SITE sur et définissez la variable d’environnement DD_API_KEY sur votre Clé API Datadog :

export DD_SITE="<DD_SITE>"
export DD_API_KEY="<DD_API_KEY>"

export deploy_start=`date +%s`
./your-deploy-script.sh
datadog-ci dora deployment --service shopist --env prod \
    --started-at $deploy_start --finished-at `date +%s` \
    --version v1.12.07 --custom-tags department:engineering \
    --custom-tags app_type:backend \
    --git-repository-url "https://github.com/organization/example-repository" \
    --git-commit-sha 66adc9350f2cc9b250b69abddab733dd55e1a588

L’heure de fin du déploiement est automatiquement définie sur maintenant si --finished-at n’est pas fourni.

Si le travail CI de déploiement s’exécute sur la même révision Git que celle qui est déployée, git-repository-url et git-commit-sha peuvent être omis et sont automatiquement déduits du contexte CI.

L’option --skip-git peut être fournie pour désactiver l’envoi de l’URL du dépôt et du SHA du commit. Lorsque cette option est ajoutée, la métrique du délai de changement devient indisponible.

Pour les déploiements identifiés par le suivi des déploiements APM, assurez-vous que la télémétrie de votre application est étiquetée avec des informations Git :

• Activez le balisage Git dans APM ou consultez la documentation d’intégration du code source

Remarque : Pour les déploiements suivis par APM, le délai de changement est calculé depuis la création du commit jusqu’à ce que le commit soit d’abord observé dans une nouvelle version. La métrique Deploy Time n’est pas disponible.

Pour les déploiements suivis par l’API des métriques DORA ou la commande datadog-ci dora deployment, assurez-vous :

• Les attributs repository_url et commit_sha sont inclus dans la charge utile des événements de déploiement

Si l’intégration GitHub n’est pas déjà installée, installez-la sur la tuile d’intégration GitHub.

Lors de la configuration de l’application GitHub :

1. Sélectionnez au moins Read autorisations de dépôt pour Contents et Pull Requests.
2. Abonnez-vous à au moins Push, PullRequest et PullRequestReview événements.

Pour confirmer que la configuration est valide, sélectionnez votre application GitHub dans la tuile d’intégration GitHub et vérifiez que le tableau Datadog Features montre que Pull Request Information répond à toutes les exigences.

Si l’intégration du code source GitLab n’est pas déjà installée, installez-la sur la tuile d’intégration du code source GitLab.

Remarque : La portée du jeton d’accès personnel du compte de service doit être d’au moins read_api.

Gestion des groupes et sous-groupes GitLab

Si vos dépôts sont organisés sous groupes ou sous-groupes GitLab (par exemple, https://gitlab.com/my-org/group(/subgroup)/repo), la détection automatique du chemin de service peut ne pas se résoudre correctement en raison de la structure de groupe imbriquée de GitLab.

Pour garantir que les métriques DORA gèrent correctement les chemins de code source de votre service, vous pouvez utiliser la configuration suivante dans la définition de votre service :

extensions:
  datadoghq.com/dora-metrics:
    source_patterns:
      # All paths relative to the repository URL provided with the deployment
      - **
      # or specific paths related to this service (for monorepos)
      - src/apps/shopist/**
      - src/libs/utils/**

Si l’intégration du code source Azure DevOps n’est pas déjà installée, installez-la sur la tuile d’intégration du code source Azure DevOps.

Pour configurer l’intégration :

1. Ouvrez la tuile d’intégration du code source Azure DevOps dans Datadog.

2. Sélectionnez l’onglet Configuration et cliquez sur Connect Microsoft Entra App.

3. Suivez les instructions de configuration.

4. Cliquez Add Organizations.

5. Suivez les étapes d’installation du dépôt et exécutez le script d’installation. Si le script n’est pas exécuté, les commits effectués avant la création d’une demande de tirage ne seront pas associés à cette demande de tirage.

6. Après l’achèvement du script, vérifiez l’état d’intégration sur la tuile. Les dépôts et projets connectés apparaissent dans la liste.

Vous pouvez télécharger les métadonnées de votre dépôt Git avec la commande datadog-ci git-metadata upload. Lorsque cette commande est exécutée, Datadog reçoit l’URL du dépôt, le SHA du commit de la branche actuelle et une liste des chemins de fichiers suivis.

Exécutez cette commande dans CI pour chaque nouveau commit. Si un déploiement est exécuté pour un SHA de commit spécifique, assurez-vous que la commande datadog-ci git-metadata upload est exécutée pour ce commit avant que l’événement de déploiement soit envoyé.

Vous pouvez valider la configuration correcte de la commande en vérifiant la sortie de la commande. Un exemple de sortie correcte est :

Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git.
180 tracked file paths will be reported.
✅  Handled in 0.077 seconds.

Les métriques DORA peuvent identifier et suivre automatiquement les échecs via Incidents Datadog. Après la déclaration des incidents, DORA les utilise pour mesurer le taux d’échec de changement et le temps de restauration.

Remarque : Le temps de restauration est mesuré comme la durée totale qu’un incident passe dans l’état active. Pour des cas comme active → stable → active → stable, cela inclut toutes les périodes active. Le temps de restauration n’est affiché que lorsqu’un incident est dans un état stable ou resolved. Si un incident resolved est réactivé, la métrique est masquée jusqu’à ce qu’il soit resolved à nouveau.

Exigences

• Incidents est activé en tant que source de données d’événements Failures dans paramètres DORA.

Pour éviter d’avoir des échecs non étiquetés, Datadog recommande fortement d’ajouter les attributs suivants aux incidents :

• Teams
• Services
• Envs : L’attribut Envs peut être ajouté dans les Paramètres d’incidents s’il n’existe pas déjà.

Si des incidents sont fournis, le tag Severity est ajouté aux événements d’échec.

Recommandé : Dans les Paramètres d’incidents, définissez le champ des attributs Prompted sur At Resolution pour vous assurer de ne jamais oublier d’ajouter ces attributs à vos incidents.

Inclure les incidents historiques

Vous pouvez inclure rétroactivement des incidents des deux dernières années en sélectionnant Backfill Data dans les paramètres DORA, ce qui crée des pannes à partir de ces incidents. Le remplissage des données peut prendre jusqu’à une heure pour être complété.

PagerDuty est une plateforme de gestion des incidents qui équipe les équipes informatiques d’une visibilité immédiate des incidents, permettant des réponses proactives et efficaces pour maintenir la stabilité opérationnelle et la résilience.

Pour intégrer votre compte PagerDuty avec DORA Metrics :

1. Activez PagerDuty en tant que source de données d’événements Failures dans paramètres DORA.

2. Accédez à Integrations > Developer Tools dans PagerDuty et cliquez sur Generic Webhooks (v3).

3. Cliquez sur + New Webhook et entrez les détails suivants :

   Variable	Description
   URL du webhook	Ajouter https://webhook-intake./api/v2/webhook/.
   Type de portée	Sélectionnez la portée des incidents que vous souhaitez envoyer. Vous pouvez envoyer des incidents pour un Service ou Team spécifique, ou tous les services PagerDuty dans votre Account. Selon votre environnement et votre niveau d'accès, certains types de portée peuvent ne pas être disponibles.
   Description	Une description aide à distinguer le webhook. Ajoutez quelque chose comme Datadog DORA Metrics integration.
   Abonnement à l'événement	Sélectionnez les événements suivants : -incident.acknowledged -incident.annotated -incident.custom_field_values.updated -incident.delegated -incident.escalated -incident.priority_updated -incident.reassigned -incident.reopened -incident.resolved -incident.triggered -incident.unacknowledged
   En-têtes personnalisés	Cliquez sur Add custom header, entrez DD-API-KEY comme le nom, et saisissez votre clé API Datadog comme valeur. Optionnellement, vous pouvez ajouter un environnement à tous les incidents PagerDuty envoyés depuis le webhook en créant un en-tête personnalisé supplémentaire avec le nom dd_env et l'environnement souhaité comme valeur.

4. Pour enregistrer le webhook, cliquez sur Add Webhook.

La gravité de l’échec dans le produit DORA Metrics est basée sur la priorité de l’incident dans PagerDuty.

Remarque : Lors de la création du webhook, un nouveau secret est créé et utilisé pour signer toutes les charges utiles du webhook. Ce secret n’est pas nécessaire pour que l’intégration fonctionne, car l’authentification est effectuée à l’aide de la clé API à la place.

Associer les services PagerDuty aux services Datadog

Lorsqu’un événement d’incident est reçu pour un service PagerDuty spécifique, Datadog tente de récupérer le service et l’équipe Datadog associés à partir de tout moniteur Datadog déclencheur et du Catalogue de logiciels.

L’algorithme de correspondance fonctionne selon les étapes suivantes :

1. Si l’événement d’incident PagerDuty a été déclenché par un moniteur Datadog :

   • Si le moniteur est en mode Multi Alerte, les métriques et événements d’incident sont émis avec le env, service et team du groupe alerté.
   • Si le moniteur a des tags pour env, service ou team :
     • env : Si le moniteur a un seul tag env, les métriques et événements d’incident sont émis avec l’environnement.
     • service : Si le moniteur a un ou plusieurs tags service, les métriques et événements d’incident sont émis avec les services fournis.
     • team : Si le moniteur a un seul tag team, les métriques et événements d’incident sont émis avec l’équipe.

2. Si l’URL du service de l’incident correspond à l’URL du service PagerDuty pour l’un des services dans le Catalogue de logiciels :

   • Si un seul service Datadog correspond, les métriques et événements d’incident sont émis avec le service et l’équipe.
   • Si plusieurs services Datadog correspondent, les métriques et événements d’incident sont émis avec l’équipe.

   Pour plus d’informations sur la configuration de l’URL du service PagerDuty pour un service Datadog, voir Utiliser les intégrations avec le Catalogue de logiciels.

3. Si le nom du service PagerDuty de l’incident correspond à un nom de service dans le Catalogue de logiciels, les métriques et événements d’incident sont émis avec le service et l’équipe.

4. Si le nom de l’équipe PagerDuty de l’incident correspond à un nom d’équipe dans le Catalogue de logiciels, les métriques et événements d’incident sont émis avec l’équipe.

5. Si le nom du service PagerDuty de l’incident correspond à un nom d’équipe dans le Catalogue de logiciels, les métriques et événements d’incident sont émis avec l’équipe.

6. S’il n’y a eu aucune correspondance jusqu’à présent, les métriques et événements d’incident sont émis avec le service PagerDuty et l’équipe PagerDuty fournis dans l’incident.

Pour envoyer vos propres événements d’échec, utilisez l’API des Métriques DORA. Les événements d’échec sont utilisés pour calculer le taux d’échec de changement et le temps de restauration.

Incluez l’attribut finished_at dans un événement d’échec pour marquer que l’échec est résolu. Vous pouvez envoyer des événements au début de l’échec et après qu’il a été résolu. Les événements d’échec sont associés par les attributs env, service et started_at.

Exigences

• datadog-ci CLI / API est activé en tant que source de données d’événement Failures dans les paramètres DORA.
• Les attributs suivants sont requis :
  • services ou team (au moins un doit être présent)
  • started_at

Vous pouvez ajouter en option les attributs suivants aux événements d’échec :

• finished_at pour * les échecs résolus *. Requis pour calculer le temps de restauration
• id pour identifier les échecs. Cet attribut est généré par l’utilisateur ; lorsqu’il n’est pas fourni, le point de terminaison renvoie un UUID généré par Datadog.
• name pour décrire l’échec.
• severity
• env pour filtrer vos métriques DORA par environnement sur la DORA Metrics page.
• repository_url
• commit_sha
• version
• custom_tags : Étiquettes sous la forme key:value qui peuvent être utilisées pour filtrer les événements sur la page DORA Metrics.

Consultez la documentation de référence dédiée à l’API DORA Metrics pour consulter les spécifications complètes ainsi que d’autres exemples de code.

Exemple d’API (cURL)

Pour la configuration suivante, remplacez <DD_SITE> par :

curl -X POST "https://api.<DD_SITE>/api/v2/dora/failure" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "services": ["shopist"],
        "team": "shopist-devs",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "name": "Web server is down failing all requests",
        "severity": "High",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF