Esaminare i log per eseguire la diagnostica dei problemi della pipeline

  • Articolo

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

I log della pipeline offrono uno strumento potente per determinare la causa degli errori della pipeline e i log dettagliati possono essere configurati per fornire altre informazioni di diagnostica.

Un punto di partenza tipico consiste nell'esaminare i log nella build o nella versione completata. È possibile visualizzare i log passando al riepilogo dell'esecuzione della pipeline e selezionando il processo e l'attività. Se una determinata attività ha esito negativo, controllare i log per l'attività. Configurare i log dettagliati per includere altre informazioni di diagnostica.

Configurare i log dettagliati

Per facilitare la risoluzione dei problemi, è possibile configurare i log in modo più dettagliato.

  • Per configurare i log dettagliati per una singola esecuzione, è possibile avviare una nuova compilazione scegliendo Esegui pipeline e selezionando Abilita diagnostica di sistema, Esegui.

    Abilita diagnostica di sistema

  • Per configurare i log dettagliati per tutte le esecuzioni, è possibile aggiungere una variabile denominata system.debug e impostarne il valore su true.

  • Per configurare i log dettagliati per una singola esecuzione, è possibile avviare una nuova compilazione scegliendo Compilazione coda e impostando il valore per la system.debug variabile su true.

  • Per configurare i log dettagliati per tutte le esecuzioni, modificare la compilazione, passare alla scheda Variabili e aggiungere una variabile denominata system.debug, impostarne il valore su truee selezionare Consenti in fase di coda.

  • Per configurare i log dettagliati per una pipeline YAML, aggiungere la system.debug variabile nella variables sezione :

    variables:
  system.debug: true

I log della pipeline di Azure possono ora acquisire le metriche di utilizzo delle risorse, ad esempio memoria, utilizzo della CPU e spazio disponibile su disco. I log includono anche le risorse usate dall'agente della pipeline e dai processi figlio, incluse le attività eseguite in un processo. Se si sospetta che il processo della pipeline possa verificarsi in vincoli di risorse, abilitare i log dettagliati in modo che le informazioni sull'utilizzo delle risorse vengano inserite nei log della pipeline. Le metriche di utilizzo delle risorse sono disponibili in qualsiasi agente, indipendentemente dal modello di hosting.

Per visualizzare le metriche di utilizzo delle risorse acquisite, cercare i log per Agent environment resources ogni passaggio.

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%

Visualizzare e scaricare i log

Per visualizzare i singoli log per ogni passaggio, passare ai risultati della compilazione per l'esecuzione e selezionare il processo e il passaggio.

Log attività

Per scaricare tutti i log, passare ai risultati della compilazione per l'esecuzione, selezionare ...e scegliere Scarica log.

Download dei log

Per scaricare tutti i log, passare ai risultati della compilazione per l'esecuzione, scegliere Scarica tutti i log come ZIP.

Oltre ai log di diagnostica della pipeline, sono disponibili i tipi di log specializzati seguenti e possono contenere informazioni utili per la risoluzione dei problemi.

Log di diagnostica del ruolo di lavoro

È possibile ottenere il log di diagnostica della compilazione completata generata dal processo di lavoro nell'agente di compilazione. Cercare il worker file di log con data e ora della compilazione completata. Ad esempio: worker_20160623-192022-utc_6172.log.

Log di diagnostica dell’agente

I log di diagnostica dell'agente forniscono un record del modo in cui l'agente è stato configurato e cosa è successo quando è stato eseguito. Cercare i file di agent log. Ad esempio: agent_20160624-144630-utc.log. Esistono due tipi di file di log dell'agente:

  • File di log generato durante l'esecuzione di config.cmd. Questo log:

    • Include questa riga vicino alla parte superiore: Adding Command: configure

    • Mostra le scelte di configurazione effettuate.

  • File di log generato durante l'esecuzione di run.cmd. Questo log:

    • Impossibile aprire fino a quando il processo non viene terminato.

    • Tenta di connettersi all'organizzazione di Azure DevOps o Team Foundation Server .

    • Mostra quando è stato eseguito ogni processo e come è stato completato

Entrambi i log mostrano come sono state rilevate e impostate le funzionalità dell'agente.

Diagnostica di rete per gli agenti self-hosted

Impostare il valore di Agent.Diagnostic su true per raccogliere log aggiuntivi che possono essere usati per la risoluzione dei problemi di rete per gli agenti self-hosted.

file Informazioni Si applica a
cloudinit.* Cloud-init completato correttamente (se usato) Linux
BrokenPackages.* I pacchetti sono in uno stato coerente Linux
Agent.* Variabili di ambiente Linux, Windows
waagentConf.txt Agente di macchine virtuali di Azure (waagent.conf) Azure: Linux, Windows
environment.txt / agent.* Elenco di appartenenze ai gruppi di account Windows

Nota

Agent.Diagnostic viene impostato automaticamente su true quando System.Debug è impostato su true.

La Agent.Diagnostic variabile e i log descritti in questa sezione sono disponibili con Agent v2.200.0 e versioni successive.

Per altre informazioni, vedere Risoluzione dei problemi dell'agente nel repository dell'agente open source microsoft/azure-pipelines-agent di Azure Pipelines.

Altri log

All'interno dei log di diagnostica sono disponibili environment.txt e capabilities.txt.

Il environment.txt file contiene varie informazioni sull'ambiente in cui è stata eseguita la compilazione. Sono incluse informazioni come le attività eseguite, se il firewall è abilitato o meno, le informazioni sulla versione di PowerShell e altri elementi. Aggiungiamo continuamente a questi dati per renderli più utili.

Il capabilities.txt file offre un modo pulito per visualizzare tutte le funzionalità installate nel computer di compilazione che ha eseguito la compilazione.

Log di traccia HTTP

Importante

Le tracce HTTP e i file di traccia possono contenere password e altri segreti. Non pubblicarli su siti pubblici.

Usare la traccia HTTP predefinita

Se l'agente è versione 2.114.0 o successiva, è possibile tracciare le intestazioni del traffico HTTP e scriverle nel log di diagnostica. Impostare la VSTS_AGENT_HTTPTRACE variabile di ambiente prima di avviare agent.listener.

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

Usare la traccia HTTP completa - Windows

  1. Avviare Fiddler.

  2. È consigliabile ascoltare solo il traffico dell'agente. File > Capture Traffic off (F12)

  3. Abilitare la decrittografia del traffico HTTPS. Scheda Https delle opzioni > di Fiddler degli strumenti>. Decrittografare il traffico HTTPS

  4. Informare l'agente di usare il proxy:

    set VSTS_HTTP_PROXY=http://127.0.0.1:8888

  5. Eseguire l'agente in modo interattivo. Se si esegue come servizio, è possibile impostare come variabile di ambiente nel pannello di controllo per l'account in cui è in esecuzione il servizio.

  6. Riavviare l'agente.

Usare la traccia HTTP completa - macOS e Linux

Usare Charles Proxy (simile a Fiddler in Windows) per acquisire la traccia HTTP dell'agente.

  1. Avviare Charles Proxy.

  2. Charles: Proxy proxy > Impostazioni > scheda SSL. Abilita. Aggiungere l'URL.

  3. Charles: Proxy > Mac OSX Proxy. È consigliabile disabilitare per visualizzare solo il traffico dell'agente.

    export VSTS_HTTP_PROXY=http://127.0.0.1:8888

  4. Eseguire l'agente in modo interattivo. Se è in esecuzione come servizio, è possibile impostare nel file con estensione env. Vedere nix service

  5. Riavviare l'agente.

Acquisire log personalizzati

Oltre ai log predefiniti, è possibile usare attività e script per acquisire log personalizzati nella pipeline. Gli esempi seguenti illustrano come acquisire l'utilizzo delle risorse, le tracce di rete, i dump della memoria e perfview le tracce. Se si lavora con il supporto tecnico clienti, potrebbe essere richiesto di acquisire log come questi.

Recuperare log personalizzati

Dopo aver acquisito un log personalizzato nella pipeline, è necessario caricarlo in modo che possa essere recuperato per la revisione. È possibile caricare il log personalizzato come parte dei log della pipeline standard oppure caricarlo come artefatto. Gli esempi nelle sezioni seguenti illustrano entrambi i modi per caricare log personalizzati.

Caricare un log come parte dei log standard

Per caricare il log personalizzato come parte dei log della pipeline standard, usare ##vso[task.uploadfile] per caricare il file desiderato. Per usare questo comando, specificarlo come parte di un comando script, come illustrato nell'esempio seguente. Il file può essere scaricato e visualizzato come parte dei log della pipeline standard. Il ##vso[task.uploadfile] metodo è utile per caricare un singolo file di log. Se sono presenti più file di log, è necessario usare una riga separata ##vso[task.uploadfile] per ogni file.

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

Per altre informazioni, vedere Comandi di registrazione e UploadFile: Caricare un file che può essere scaricato con i log attività.

Caricare un log come artefatto della pipeline

Per caricare un log personalizzato come artefatto della pipeline, usare l'attività PublishPipelineArtifact@1 . PublishPipelineArtifact@1 può caricare un singolo file o i file in un percorso di directory ed è utile se sono presenti molti file di log personalizzati da caricare.

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

Per altre informazioni, vedere Pubblicare artefatti della pipeline.

Acquisire i dettagli sull'utilizzo delle risorse

Quando si usa Azure DevOps Services, è possibile visualizzare l'utilizzo delle risorse nei log, tra cui l'utilizzo del disco, l'utilizzo della memoria e l'utilizzo della CPU, abilitando i log dettagliati. Al termine della pipeline, cercare nei log le voci per Agent environment resources ogni passaggio.

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%

Se si usa Azure DevOps Server o se si vogliono raccogliere metriche aggiuntive, è possibile usare PowerShell per acquisire l'utilizzo delle risorse e caricarlo nei log della pipeline. Al termine dell'esecuzione della pipeline, è possibile scaricare i log della pipeline e visualizzare i dati acquisiti. Se il Upload resource usage from pipeline run passaggio è il sesto passaggio del processo, il nome file nei log verrà 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()

Acquisire un dump della memoria del processo dotnet usando ProcDump

Se si dispone di un'esecuzione di test che si arresta in modo anomalo, il supporto tecnico potrebbe chiedere di acquisire un dump della memoria del processo dotnet dopo l'esecuzione di test non riuscita. Aggiungere l'attività seguente dopo l'attività test di Visual Studio con condition: always(). Al termine dell'esecuzione della pipeline, è possibile scaricare i log della pipeline, incluso il dump della memoria.

# 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'

Acquisire tracce ETW per un agente ospitato

Se si stanno risolvendo i problemi di rete con gli agenti ospitati da Microsoft, il supporto tecnico potrebbe chiedere di raccogliere tracce ETW. Al termine dell'esecuzione della pipeline, è possibile scaricare i log della pipeline, incluse le tracce ETW.

# 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'

Acquisire perfview tracce per la compilazione di Visual Studio

Se il supporto tecnico chiede di creare una perfview traccia della compilazione di Visual Studio, aggiungere le attività seguenti alla pipeline prima e dopo il passaggio di compilazione di Visual Studio.

Dopo aver eseguito la pipeline, è possibile scaricare l'artefatto PerfViewLog dai dettagli dell'esecuzione della pipeline e inviare il supporto tecnico del file.

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 givet time for required for 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