Examinar logs para diagnosticar problemas de pipeline

Azure DevOps Services | Servidor Azure DevOps | Azure DevOps Server 2022 | Azure DevOps Server 2020

Os logs de pipeline fornecem uma ferramenta poderosa para determinar a causa de falhas de pipeline e logs detalhados podem ser configurados para fornecer mais informações de diagnóstico.

Um ponto de partida típico é examinar os logs em sua compilação ou versão concluída. Você pode exibir logs navegando até o resumo da execução do pipeline e selecionando o trabalho e a tarefa. Se uma determinada tarefa estiver falhando, verifique os logs para essa tarefa. Configure logs detalhados para incluir mais informações de diagnóstico.

Configurar logs detalhados

Para ajudar na solução de problemas, você pode configurar seus logs para serem mais detalhados.

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%

Exibir e baixar logs

Além dos logs de diagnóstico de pipeline, os seguintes tipos de log especializados estão disponíveis e podem conter informações para ajudá-lo a solucionar problemas.

• Logs de diagnóstico de trabalho
• Logs de diagnóstico do agente
• Outros logs

Logs de diagnóstico de trabalho

Você pode obter o log de diagnóstico do build concluído gerado pelo processo de trabalho no agente de build. Procure o worker arquivo de log que tem o carimbo de data e hora do build concluído. Por exemplo, worker_20160623-192022-utc_6172.log.

Logs de diagnóstico do agente

Os logs de diagnóstico do agente fornecem um registro de como o agente foi configurado e o que aconteceu quando ele foi executado. Procure os arquivos de agent log. Por exemplo, agent_20160624-144630-utc.log. Há dois tipos de arquivos de log do agente:

• O arquivo de log gerado quando você executou config.cmd. Este log:

  • Inclui essa linha perto da parte superior: Adding Command: configure

  • Mostra as opções de configuração feitas.

• O arquivo de log gerado quando você executou run.cmd. Este log:

  • Não é possível abrir até que o processo seja encerrado.

  • Tenta se conectar à sua organização do Azure DevOps ou ao Team Foundation Server.

  • Mostra quando cada trabalho foi executado e como ele foi concluído

Ambos os logs mostram como os recursos do agente foram detectados e definidos.

Outros logs

Dentro dos logs de diagnóstico que você encontrará environment.txt e capabilities.txt.

O environment.txt arquivo tem várias informações sobre o ambiente no qual o build foi executado. Isso inclui informações como quais tarefas são executadas, se o firewall está habilitado ou não, informações de versão do PowerShell e alguns outros itens. Adicionamos continuamente a esses dados para torná-los mais úteis.

O capabilities.txt arquivo fornece uma maneira limpa de ver todos os recursos instalados no computador de build que executou seu build.

Logs de rastreamento HTTP

• Usar o rastreamento HTTP interno
• Usar rastreamento HTTP completo – Windows
• Usar rastreamento HTTP completo – macOS e Linux

Usar o rastreamento HTTP interno

Se o agente for a versão 2.114.0 ou mais recente, você poderá rastrear os cabeçalhos de tráfego HTTP e gravá-los no log de diagnóstico. Defina a VSTS_AGENT_HTTPTRACE variável de ambiente antes de iniciar o agent.listener.

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

Usar rastreamento HTTP completo – Windows

1. Inicie o Fiddler.

2. Recomendamos que você ouça somente o tráfego do agente. Tráfego de Captura de Arquivo > desativado (F12)

3. Habilite a descriptografia do tráfego HTTPS. Guia HTTPS de Opções > do Fiddler de Ferramentas>. Descriptografar o tráfego HTTPS

4. Informe o agente para usar o proxy:

   set VSTS_HTTP_PROXY=http://127.0.0.1:8888
   

5. Execute o agente interativamente. Se você estiver executando como um serviço, poderá definir como a variável de ambiente no painel de controle da conta em que o serviço está em execução.

6. Reinicie o agente.

Usar rastreamento HTTP completo – macOS e Linux

Use o Proxy charles (semelhante ao Fiddler no Windows) para capturar o rastreamento HTTP do agente.

1. Inicie o Proxy charles.

2. Guia SSL de Configurações > de Proxy de Proxy>. Habilitar. Adicionar URL.

3. Charles: Proxy > Mac OSX Proxy. É recomendável desabilitar para ver apenas o tráfego do agente.

   export VSTS_HTTP_PROXY=http://127.0.0.1:8888
   

4. Execute o agente interativamente. Se ele estiver em execução como um serviço, você poderá definir no arquivo .env. Consulte nix service

5. Reinicie o agente.

Capturar logs personalizados

Além dos logs internos, você pode usar tarefas e scripts para capturar logs personalizados em seu pipeline. Os exemplos a seguir mostram como capturar a utilização de recursos, rastreamentos de rede, despejos de memória e perfview rastreamentos. Se você estiver trabalhando com o suporte ao cliente, talvez seja solicitado a capturar logs como esses.

• Capturar detalhes de utilização de recursos
• Capturar um despejo de memória do processo dotnet usando o ProcDump
• Capturar rastreamentos etw para um agente hospedado
• Capture perfview traces for Visual Studio build

Recuperar logs personalizados

Depois de capturar um log personalizado em seu pipeline, você deve carregá-lo para que ele possa ser recuperado para revisão. Você pode carregar o log personalizado como parte dos logs de pipeline padrão ou carregá-lo como um artefato. Os exemplos nas seções a seguir mostram as duas maneiras de carregar logs personalizados.

Carregar um log como parte dos logs padrão

Para carregar o log personalizado como parte dos logs de pipeline padrão, use ##vso[task.uploadfile] para carregar o arquivo desejado. Para usar esse comando, especifique-o como parte de um comando de script, conforme mostrado no exemplo a seguir. O arquivo pode ser baixado e exibido como parte dos logs de pipeline padrão. O ##vso[task.uploadfile] método é bom para carregar um único arquivo de log. Se você tiver mais de um arquivo de log, deverá usar uma linha separada ##vso[task.uploadfile] para cada arquivo.

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

Para obter mais informações, consulte comandos de registro em log e UploadFile: carregue um arquivo que pode ser baixado com logs de tarefas.

Carregar um log como um artefato de pipeline

Para carregar um log personalizado como um artefato de pipeline, use a tarefa PublishPipelineArtifact@1 . PublishPipelineArtifact@1 pode carregar um único arquivo ou arquivos em um caminho de diretório e será útil se você tiver muitos arquivos de log personalizados para carregar.

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

Para obter mais informações, consulte Publicar Artefatos de Pipeline.

Capturar detalhes de utilização de recursos

Ao usar o Azure DevOps Services, você pode ver a utilização de recursos nos logs, incluindo uso de disco, uso de memória e utilização da CPU, habilitando logs detalhados. Quando o pipeline for concluído, pesquise entradas nos logsAgent environment resources para cada etapa.

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 você estiver usando o Servidor do Azure DevOps ou se quiser coletar métricas adicionais, poderá usar o PowerShell para capturar a utilização de recursos e carregá-la nos logs de pipeline. Quando a execução do pipeline for concluída, você poderá baixar os logs de pipeline e exibir os dados capturados. Se a Upload resource usage from pipeline run etapa for a sexta etapa do trabalho, o nome do arquivo nos logs será 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()

Capturar um despejo de memória do processo dotnet usando o ProcDump

Se você tiver uma execução de teste que falha, o suporte ao cliente poderá solicitar que você capture um despejo de memória do processo do dotnet após a execução do teste com falha. Adicione a tarefa a seguir após a tarefa teste do Visual Studio com condition: always(). Quando a execução do pipeline for concluída, você poderá baixar os logs de pipeline, incluindo o despejo de memória.

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

Capturar rastreamentos etw para um agente hospedado

Se você estiver solucionando problemas de rede com agentes hospedados pela Microsoft, o suporte ao cliente poderá solicitar que você colete rastreamentos etw. Quando a execução do pipeline for concluída, você poderá baixar os logs de pipeline, incluindo os rastreamentos de 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'

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

Capturar perfview rastreamentos para o build do Visual Studio

Se o suporte ao cliente solicitar que você crie um perfview rastreamento do seu build do Visual Studio, adicione as seguintes tarefas ao pipeline antes e depois da etapa de build do Visual Studio.

Depois de executar o pipeline, você pode baixar o artefato PerfViewLog nos detalhes da execução do pipeline e enviar o suporte ao cliente do arquivo.

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