Passer en revue les journaux pour diagnostiquer des problèmes de pipeline

Article
04/02/2024

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Les journaux de pipeline sont un outil puissant pour déterminer la cause des échecs de pipeline, et les journaux détaillés peuvent être configurés pour fournir plus d'informations de diagnostic.

Un point de départ classique consiste à passer en revue les journaux dans votre build ou version terminée. Vous pouvez afficher les journaux en accédant au résumé de l’exécution du pipeline et en sélectionnant le travail et la tâche. Si une tâche donnée échoue, vérifiez les journaux de cette tâche. Configurez les journaux détaillés pour inclure davantage d'informations de diagnostic.

Configurer des journaux détaillés

Pour faciliter la résolution des problèmes, vous pouvez configurer vos journaux pour qu’ils soient plus détaillés.

Pour configurer des journaux détaillés pour une seule exécution, vous pouvez démarrer une nouvelle build en choisissant Exécuter le pipeline et en sélectionnant Activer les diagnostics système, Exécuter.
Pour configurer des journaux détaillés pour toutes les exécutions, vous pouvez ajouter une variable nommée system.debug et définir sa valeur sur true.

Pour configurer des journaux détaillés pour une seule exécution, vous pouvez démarrer une nouvelle build en choisissant Mettre la build en file d’attente et en définissant la valeur de la variable system.debug sur true.
Pour configurer les journaux détaillés pour toutes les exécutions, modifiez la build, accédez à l’onglet Variables et ajoutez une variable nommée system.debug, définissez sa valeur sur true, puis sélectionnez Autoriser au moment de la mise en file d’attente.
Pour configurer des journaux détaillés pour un pipeline YAML, ajoutez la variable system.debug dans la section variables :
```
variables:
  system.debug: true
```

Les journaux de pipeline Azure peuvent maintenant capturer les métriques d’utilisation des ressources, telles que la mémoire, l’utilisation du processeur et l’espace disque disponible. Les journaux incluent également les ressources utilisées par l’agent de pipeline et les processus enfants, notamment les tâches exécutées dans un travail. Si vous pensez que votre travail de pipeline se heurte à des contraintes de ressources, activez les journaux détaillés pour que les informations d’utilisation des ressources soient injectées dans les journaux de pipeline. Les métriques d'utilisation des ressources sont disponibles sur n'importe quel agent, indépendamment du modèle d'hébergement.

Pour afficher les métriques d'utilisation des ressources capturées, recherchez les journaux pour les entrées Agent environment resources pour chaque étape.

2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23%

Afficher et télécharger les journaux

Pour afficher les journaux d’activité individuels pour chaque phase, accédez aux résultats de la génération pour l’exécution, puis sélectionnez le travail et la phase.

Journal de la tâche

Pour télécharger tous les journaux, accédez aux résultats de build de l’exécution, sélectionnez ..., puis choisissez Télécharger les journaux.

Télécharger les journaux

Pour télécharger tous les journaux, accédez aux résultats de build de l’exécution, choisissez Télécharger tous les journaux sous forme de fichier zip.

Outre les journaux de diagnostic de pipeline, les types de journaux spécialisés suivants sont disponibles et peuvent contenir des informations pour vous aider à résoudre les problèmes.

Journaux de diagnostic Worker
Journaux de diagnostic de l’agent
Autres journaux

Journaux de diagnostic Worker

Vous pouvez obtenir le journal de diagnostic de la build terminée générée par le processus worker sur l'agent de build. Recherchez le fichier journal worker qui a la date et l’heure de votre build terminée. Par exemple : worker_20160623-192022-utc_6172.log.

Journaux de diagnostic de l’agent

Les journaux de diagnostic de l’agent fournissent un enregistrement de la façon dont l’agent a été configuré et ce qui s’est passé lors de son exécution. Recherchez les fichiers journaux agent. Par exemple : agent_20160624-144630-utc.log. Il existe deux types de fichiers journaux d’agent :

Le fichier journal généré lors de l’exécution de config.cmd. Ce journal :
- Inclut cette ligne près du haut : Adding Command: configure
- Affiche les choix de configuration effectués.
Le fichier journal généré lors de l’exécution de run.cmd. Ce journal :
- Ne peut pas être ouvert tant que le processus n’est pas terminé.
- Tente de se connecter à votre organisation Azure DevOps ou Team Foundation Server.
- Indique quand chaque travail a été exécuté et comment il s’est terminé

Les deux journaux montrent comment les fonctionnalités de l’agent ont été détectées et définies.

Diagnostics réseau pour les agents autohébergés

Définissez la valeur de Agent.Diagnostic à true pour collecter des journaux supplémentaires qui peuvent être utilisés pour résoudre les problèmes réseau pour les agents auto-hébergés.

File	Information	S’applique à
`cloudinit.*`	Cloud-init s’est correctement terminé (si utilisé)	Linux
`BrokenPackages.*`	Les packages sont dans un état cohérent	Linux
`Agent.*`	Variables d'environnement	Linux, Windows
`waagentConf.txt`	Agent de machine virtuelle Azure (waagent.conf)	Azure : Linux, Windows
`environment.txt` / `agent.*`	Liste d’appartenance au groupe du compte	Windows

Remarque

Agent.Diagnostic est défini sur true automatiquement quand System.Debug est défini sur true.

La variable Agent.Diagnostic et les journaux décrits dans cette section sont disponibles avec Agent v2.200.0 et versions ultérieures.

Pour obtenir plus d’informations, consultez la résolution des problèmes de l’agent dans le référentiel d’agent open source Azure Pipelines microsoft/azure-pipelines-agent.

Autres journaux

Dans les journaux de diagnostic, vous trouverez environment.txt et capabilities.txt.

Le fichier environment.txt contient différentes informations sur l’environnement dans lequel votre build s’est exécutée. Cela inclut des informations telles que les tâches exécutées, si le pare-feu est activé ou non, les informations de version de PowerShell et d’autres éléments. Nous complétons continuellement ces données pour les rendre plus utiles.

Le fichier capabilities.txt fournit un moyen adéquat de voir toutes les fonctionnalités installées sur l’ordinateur de build qui a exécuté votre build.

Journaux de suivi HTTP

Utiliser le suivi HTTP intégré
Utiliser le suivi HTTP complet - Windows
Utiliser le suivi HTTP complet - macOS et Linux

Important

Les suivis HTTP et les fichiers de suivis peuvent contenir des mots de passe et d’autres secrets. Ne les publiez pas sur des sites publics.

Utiliser le suivi HTTP intégré

Si votre agent est en version 2.114.0 ou plus récente, vous pouvez effectuer le suivi des en-têtes du trafic HTTP et les écrire dans le journal de diagnostic. Définissez la variable d’environnement VSTS_AGENT_HTTPTRACE avant de lancer agent.listener.

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

Utiliser le suivi HTTP complet - Windows

Démarrez Fiddler.
Nous vous recommandons d’écouter uniquement le trafic de l’agent. Fichier > Capturer le trafic désactivé (F12)
Activez le déchiffrement du trafic HTTPS. Outils > Options de Fiddler > Onglet HTTPS. Déchiffrer le trafic HTTPS
Indiquez à l’agent d’utiliser le proxy :
```
set VSTS_HTTP_PROXY=http://127.0.0.1:8888
```
Exécutez l’agent de manière interactive. Si vous exécutez en tant que service, vous pouvez le définir comme variable d’environnement dans le panneau de configuration pour le compte sur lequel le service s’exécute.
Redémarrez l’agent.

Utiliser le suivi HTTP complet - macOS et Linux

Utilisez Charles Proxy (similaire à Fiddler sur Windows) pour capturer le suivi HTTP de l’agent.

Démarrez Charles Proxy.
Charles: Proxy > Paramètres du proxy> Onglet SSL. Activer. Ajoutez l'URL.
Charles : Proxy > Proxy Mac OSX. Il est recommandé de le désactiver pour ne voir que le trafic des agents.
```
export VSTS_HTTP_PROXY=http://127.0.0.1:8888
```
Exécutez l’agent de manière interactive. S’il s’exécute en tant que service, vous pouvez définir dans le fichier .env. Consultez nix service
Redémarrez l’agent.

Capturez des journaux personnalisés

En plus des journaux intégrés, vous pouvez utiliser des tâches et des scripts pour capturer des journaux personnalisés dans votre pipeline. Les exemples suivants montrent comment capturer l'utilisation des ressources, les traces réseau, les vidages de mémoire, et les traces perfview. Si vous travaillez avec le support client, il se peut que l'on vous demande de capturer des journaux comme ceux-ci.

Capturer les détails de l'utilisation des ressources
Capturer une image mémoire du processus dotnet en utilisant ProcDump
Capturer les traces ETW pour un agent hébergé
Capture perfview traces for Visual Studio build

Récupérer des journaux personnalisés

Après avoir capturé un journal personnalisé dans votre pipeline, vous devez le télécharger afin qu'il puisse être récupéré pour examen. Vous pouvez télécharger le journal personnalisé comme partie des journaux de pipeline standard, ou vous pouvez le télécharger comme un artefact. Les exemples dans les sections suivantes montrent les deux façons de télécharger des journaux personnalisés.

Télécharger un journal dans le cadre des journaux standard

Pour télécharger le journal personnalisé dans le cadre des journaux de pipeline standard, utilisez ##vso[task.uploadfile] pour télécharger le fichier désiré. Pour utiliser cette commande, spécifiez qu'il s'agit d'une partie d'une commande de script comme indiqué dans l'exemple suivant. Le fichier peut être téléchargé et visualisé comme faisant partie des journaux de pipeline standard. La méthode ##vso[task.uploadfile] est adéquate pour télécharger un seul fichier journal. Si vous avez plus d'un fichier journal, vous devez utiliser une ligne ##vso[task.uploadfile] séparée pour chaque fichier.

- pwsh: Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\resource-usage.txt"

Pour plus d'informations, veuillez consulter la rubrique Commandes de journalisation et UploadFile: Télécharger un fichier qui peut être téléchargé avec les journaux de tâche.

Télécharger un journal en tant qu'artefact de pipeline

Pour télécharger un journal personnalisé comme artefact de pipeline, utilisez la tâche PublishPipelineArtifact@1. PublishPipelineArtifact@1 peut télécharger un seul fichier ou les fichiers dans un chemin de répertoire, et est utile si vous avez de nombreux fichiers journaux personnalisés à télécharger.

- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)/s/trace'
    artifact: 'file_result.pcap'
    publishLocation: 'pipeline'

Pour plus d'informations, veuillez consulter la section Publier des artefacts de pipeline.

Capturer les détails de l'utilisation des ressources

Lorsque vous utilisez les services Azure DevOps, vous pouvez voir l'utilisation des ressources dans les journaux, comme l'utilisation du disque, de la mémoire et du processeur, en activant les journaux détaillés. Lorsque le pipeline est terminé, recherchez les journaux pour les entrées Agent environment resources pour chaque étape.

2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23%

Si vous utilisez Azure DevOps Server, ou si vous souhaitez collecter des métriques supplémentaires, vous pouvez utiliser PowerShell pour capturer l'utilisation des ressources et la télécharger dans les journaux de pipeline. Lorsque l'exécution du pipeline est terminée, vous pouvez télécharger les journaux de pipeline et visualiser les données capturées. Si l'étape Upload resource usage from pipeline run est la sixième étape dans le travail, le nom du fichier dans les journaux sera 6_resource-usage.txt.

# Place this task in your pipeline to log the current resource utilization
# of the pipeline. This task appends the specified resource usage to a logfile
# which is uploaded at the end of the current pipeline job.
- pwsh: |
      $logFile = '$(Agent.TempDirectory)\resource-usage.txt'
      if (!(Test-Path $logFile))
      {
        New-Item $logFile
      }
      Get-Date | Out-File -FilePath $logFile -Append
      Get-Volume | Out-File -FilePath $logFile -Append
      Get-Counter '\Memory\Available MBytes' | Out-File -FilePath $logFile -Append
      Get-Counter '\Processor(_Total)\% Processor Time' | Out-File -FilePath $logFile -Append
      sleep 10
  displayName: 'Check resource utilization'

# Other tasks here, and you can repeat the "Check resource utilization"
# step if desired, and the results will be appended to the resource-usage.txt file

- pwsh: Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\resource-usage.txt"
  displayName: 'Upload resource usage from pipeline run'
  condition: always()

Capturer une image mémoire du processus dotnet en utilisant ProcDump

Si une exécution de test plante, le support client peut vous demander de capturer une image mémoire du processus dotnet après l'échec de l'exécution du test. Ajoutez la tâche suivante après votre tâche de test Visual Studio avec condition: always(). Lorsque l'exécution du pipeline est terminée, vous pouvez télécharger les journaux de pipeline, dont l'image mémoire.

# Run this task after your test execution crashes
# with a condition of alway() so that it always runs
- pwsh: |
    Invoke-WebRequest https://download.sysinternals.com/files/Procdump.zip -OutFile $(Agent.TempDirectory)\Procdump.zip
    mkdir $(Agent.TempDirectory)\Procdump
    unzip $(Agent.TempDirectory)\Procdump.zip -d Procdump
    cd $(Agent.TempDirectory)\Procdump
    Get-Process dotnet | % { $(Agent.TempDirectory)\procdump.exe -accepteula -ma $_.Id dotnet-$($_.Id).dmp }
    Compress-Archive *.dmp -DestinationPath $(Agent.TempDirectory)\dump_files.zip
    Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\dump_files.zip"
  condition: always()
  displayName: 'Create and upload a dotnet process memory dump'

Capturer les traces ETW pour un agent hébergé

Si vous dépannez des problèmes réseau avec des agents hébergés par Microsoft, le support client peut vous demander de collecter des traces ETW. Lorsque l'exécution du pipeline est terminée, vous pouvez télécharger les journaux de pipeline, dont les traces ETW.

Agent Windows
Agent Linux

# Add this task to start the ETW trace
- script: netsh trace start scenario=InternetClient capture=yes tracefile=$(Agent.TempDirectory)\networktrace.etl
  displayName: 'Start ETW trace'

# Other tasks here

# Add these 2 tasks to stop the trace and upload
# the trace to the pipeline logs
- script: netsh trace stop
  displayName: 'Stop ETW trace'

- pwsh: |
    Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\networktrace.etl"
    Write-Host "##vso[task.uploadfile]$(Agent.TempDirectory)\networktrace.cab"
  displayName: 'Upload ETW trace logs'

- task: Bash@3
  inputs:
    targetType: 'inline'
    script: |
      sudo rm -f nohup.out
      sudo rm -R trace
      sudo mkdir trace
      sudo nohup tcpdump -i eth0 -s 65535 -w trace/file_result.pcap &
      cd trace
      ls

# Add tasks that perform actions that you want to trace here

# Upload the trace to a pipeline artifact
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Pipeline.Workspace)/s/trace'
    artifact: 'file_result.pcap'
    publishLocation: 'pipeline'

Capturer perfview traces pour la génération Visual Studio

Si le support client vous demande de créer une trace perfview de votre build Visual Studio, ajoutez les tâches suivantes à votre pipeline avant et après votre étape de build Visual Studio.

Après l'exécution du pipeline, vous pouvez télécharger l'artefact PerfViewLog à partir des détails de l'exécution du pipeline et envoyer ce fichier au support client.

steps:
- task: PowerShell@2 # download the perfview exe
  inputs:
    targetType: 'inline'
    script: |
      invoke-webrequest https://github.com/microsoft/perfview/releases/download/v3.1.7/PerfView.exe -OutFile PerfView.exe

- task: PowerShell@2
  inputs:
    targetType: 'inline' # start perfview to capture the traces before build build task
    script: '$(System.DefaultWorkingDirectory)\PerfView.exe "/DataFile:PerfViewData.etl" /accepteula /BufferSizeMB:512 /StackCompression /CircularMB:5000 /Providers:"Microsoft-Windows-IIS" /logfile:"PerfView.log" /zip:true /norundown start'

- task: VSBuild@1
  displayName: '$(solution)' # build of the solution, note the msbuildargs might be different for your scenario
  inputs:
    solution: '$(solution)'
    clean: true
    msbuildArgs: '/p:DeployOnBuild=true /p:PrecompileBeforePublish=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:PackageLocation="$(Build.ArtifactStagingDirectory)" /p:TransformWebConfigEnabled=false /p:AutoParameterizationWebConfigConnectionStrings=false /p:MarkWebConfigAssistFilesAsExclude=false /p:ProfileTransformWebConfigEnabled=false /p:IsTransformWebConfigDisabled=true'
    platform: '$(buildPlatform)'
    configuration: '$(buildConfiguration)'

- task: PowerShell@2 # stop the perfview tracing
  inputs:
    targetType: 'inline' 
    script: |
      $(System.DefaultWorkingDirectory)\perfview.exe /accepteula /logfile:"PerfView.log" stop

- task: PowerShell@2 # abort perfview, it seems required.
  inputs:
    targetType: 'inline'
    script: '$(System.DefaultWorkingDirectory)\perfview.exe /accepteula /logfile:"PerfView.log" abort'

- task: PowerShell@2 # add a sleep of 5 mins, to give it time for required traces to be complete
  inputs:
    targetType: 'inline'
    script: 'Start-Sleep -Seconds 300'

- task: PublishPipelineArtifact@1 # upload the traces
  displayName: 'Publish Pipeline Artifact'
  inputs:
    artifactName: webapp

Partage via