Revisar os logs para diagnosticar os problemas do pipeline

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

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

Um ponto de partida típico é examinar os logs em seu build ou versão concluídos. Você pode exibir os logs navegando até o resumo de execução de pipeline e selecionando o trabalho e a tarefa. Se uma determinada tarefa estiver falhando, verifique os logs dessa tarefa. Configurar os 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.

• Para configurar logs detalhados de uma única execução, você pode iniciar um novo build escolhendo Executar pipeline e selecionando Habilitar diagnóstico do sistema, Executar.

  

• Para configurar logs detalhados para todas as execuções, você pode adicionar uma variável chamada system.debug e definir seu valor como true.

Os logs de pipeline do Azure agora podem capturar métricas de utilização de recursos, como memória, uso da CPU e espaço em disco disponível. Esses logs também incluem recursos usados pelo agente do pipeline e processos filho, incluindo tarefas executadas em um trabalho. Se você suspeitar que seu trabalho de pipeline pode enfrentar restrições de recursos, habilite logs detalhados para injetar informações de utilização de recursos nos logs do pipeline. As métricas de uso de recursos estão disponíveis em qualquer agente, independentemente do modelo de hosting.

Para exibir as métricas capturadas de uso de recursos, pesquise os logs para entradas Agent environment resources de 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%

Exibir e baixar logs

Para exibir logs individuais de cada etapa, navegue até os resultados do build da execução e selecione o trabalho e a etapa.

Para baixar todos os logs, navegue até os resultados do build para a execução, selecione ... e escolha 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 ajudar você 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 receber o log de diagnóstico da compilação concluída gerada pelo processo de trabalho no agente de compilação. Procure o arquivo de log worker 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 log agent. 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. O log:

  • Inclui esta 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. O log:

  • Não pode ser aberto 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.

Diagnóstico de rede para agentes auto-hospedados

Defina o valor de Agent.Diagnostic para true coletar logs adicionais que podem ser usados para solucionar problemas de rede para agentes auto-hospedados.

Arquivo	Informações	Aplicável ao
cloudinit.*	Cloud-init concluída com sucesso (se usada)	Linux
BrokenPackages.*	Os pacotes estão em um estado consistente	Linux
Agent.*	Variáveis de ambiente	Linux, Windows
waagentConf.txt	Agente de VM do Azure (waagent.conf)	Azure: Linux, Windows
environment.txt / agent.*	Lista de associação de grupos de contas	Windows

Observação

Agent.Diagnostic é definido como true automaticamente quando System.Debug é definido como true.

A variável Agent.Diagnostic e os logs descritos nesta seção estão disponíveis com o Agent v2.200.0 ou versões superiores.

Para mais informações, confira a solução de problemas do agente no repositório de agentes de código aberto do Azure Pipelines em microsoft/azure-pipelines-agent.

Outros logs

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

O arquivo environment.txt 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. Expandimos continuamente esses dados para torná-los mais úteis.

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

Logs de rastreamento HTTP

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

Importante

Rastreamentos HTTP e arquivos de rastreamento podem conter senhas e outros segredos. Não poste-os em sites públicos.

Usar 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 variável de ambiente VSTS_AGENT_HTTPTRACE 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. Arquivo > Capturar tráfego desativado (F12)

3. Habilite a descriptografia do tráfego HTTPS. Ferramentas > Opções do Fiddler > guia HTTPS. Descriptografa 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 Charles Proxy (semelhante ao Fiddler no Windows) para capturar o rastreamento HTTP do agente.

1. Inicie o Charles Proxy.

2. Charles: Proxy > Configurações de Proxy > guia SSL. Habilitar. Adicione 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. Confira nix service

5. Reinicie o agente.

Capturar os logs personalizados

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

• Capturar detalhes de uso de recursos
• Capturar um despejo de memória de processo dotnet usando o ProcDump
• Capturar rastreamentos de ETW para um agente hospedado
• Capture perfview traces for Visual Studio build

Recuperar os logs personalizados

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

Carregar um log como parte dos logs padrão

Para carregar o log personalizado como sendo parte dos logs de pipeline padrão, use ##vso[task.uploadfile] para carregar o arquivo desejado. Para usar este comando, especifique-o como parte de um comando de script, como mostra o exemplo a seguir. O arquivo pode ser baixado e visualizado como parte dos logs do pipeline padrão. O método ##vso[task.uploadfile] é bom para carregar um único arquivo de log. Se tiver mais de um arquivo de log, você 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 do registro em log e UploadFile: carregar um arquivo que pode ser baixado com logs de tarefas.

Carregar um log como artefato de pipeline

Para carregar um log personalizado como artefato de pipeline, use a tarefa PublishPipelineArtifact@1. PublishPipelineArtifact@1 pode carregar um único arquivo ou os arquivos em um caminho de diretório, e é ú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, confira Publicar Artefatos de Pipeline.

Capturar detalhes de uso de recursos

Ao usar o Azure DevOps Services, você pode ver o uso dos 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 logs Agent 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 estiver usando o Azure DevOps Server ou se quiser coletar outras métricas, você poderá usar o PowerShell para capturar o uso de recursos e carregá-los nos logs de pipeline. Quando a execução do pipeline for concluída, você poderá fazer o download dos logs do pipeline e exibir os dados capturados. Se a etapa Upload resource usage from pipeline run 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 de processo dotnet usando o ProcDump

Se você tiver uma execução de teste que está travando, o suporte ao cliente pode solicitar que você capture um despejo de memória do processo dotnet após a execução do teste com falha. Adicione a seguinte tarefa após a tarefa de teste do Visual Studio com o condition: always(). Quando a execução do pipeline for concluída, você poderá fazer o download dos logs do 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 de 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 os rastreamentos ETW. Quando a execução do pipeline for concluída, você poderá fazer o download dos logs do pipeline, incluindo os rastreamentos do ETW.

Agente do Windows

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

Agente do Linux

- 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 rastreamentos perfview para compilação do Visual Studio

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

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

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