Rever registos para diagnosticar problemas do pipeline

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

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 é revisar os logs em sua compilação ou versão concluída. Você pode visualizar os logs navegando até o resumo de execução do pipeline e selecionando o trabalho e a tarefa. Se uma determinada tarefa estiver falhando, verifique os logs dessa tarefa. Configure logs detalhados para incluir mais informações de diagnóstico.

Configurar logs detalhados

Para ajudar na resolução de problemas, pode configurar os registos para serem mais verbosos.

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

    Ativar o diagnóstico do sistema

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

  • Para configurar logs detalhados para uma única execução, você pode iniciar uma nova compilação escolhendo Queue build e definindo o valor da system.debug variável como true.

  • Para configurar logs detalhados para todas as execuções, edite a compilação, navegue até a guia Variáveis e adicione uma variável chamada system.debug, defina seu valor como truee selecione Permitir no Tempo da Fila.

  • Para configurar logs detalhados para um pipeline YAML, adicione a system.debugvariables variável na seção :

    variables:
  system.debug: 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. Os logs também incluem recursos usados pelo agente de pipeline e processos filho, incluindo tarefas executadas em um trabalho. Se você suspeitar que seu trabalho de pipeline pode ter restrições de recursos, habilite logs detalhados para que as informações de utilização de recursos sejam injetadas nos logs de pipeline. As métricas de utilização de recursos estão disponíveis em qualquer agente, independentemente do modelo de hospedagem.

Para exibir as métricas de utilização de recursos capturadas, pesquise os logs por Agent environment resources entradas 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%

Ver e transferir registos

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

Registo de tarefas

Para baixar todos os logs, navegue até os resultados da compilação para a execução, selecione ..., e escolha Baixar logs.

Registos de transferências

Para baixar todos os logs, navegue até os resultados da compilação para a execução, escolha Baixar todos os logs como zip.

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 do trabalhador

Você pode obter o log de diagnóstico da compilação concluída gerada pelo processo de trabalho no agente de compilação. Procure o worker arquivo de log que tem o carimbo de data e hora de sua compilação concluída. 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 ficheiros de agent registo. 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.cmdo . Este registo:

    • Inclui esta linha perto do topo: Adding Command: configure

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

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

    • Não pode ser aberto até que o processo seja encerrado.

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

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

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

Diagnósticos de rede para agentes autoalojados

Defina o valor de Agent.Diagnostic como true para recolher registos adicionais que podem ser utilizados para resolver problemas de rede de agentes autoalojados.

Ficheiro Informação Aplica-se a
cloudinit.* Cloud-init concluído com êxito (se usado) Linux
BrokenPackages.* Os pacotes estão em um estado consistente Linux
Agent.* Variáveis de ambiente Linux, Janelas
waagentConf.txt Agente de VM do Azure (waagent.conf) Azure: Linux, Windows
environment.txt / agent.* Lista de membros do grupo de contas Windows

Nota

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

A variável e os logs descritos nesta seção estão disponíveis com o Agent.Diagnostic Agent v2.200.0 e superior.

Para obter mais informações, consulte Solução de problemas do agente no repositório de agente de código aberto do agente microsoft/azure-pipelines-agent Azure Pipelines.

Outros registos

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

O environment.txt arquivo tem várias informações sobre o ambiente no qual sua compilação foi executada. 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 na máquina de compilação que executou sua compilação.

Logs de rastreamento HTTP

Importante

Rastreamentos HTTP e arquivos de rastreamento podem conter senhas e outros segredos. Não os publique 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 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 apenas o tráfego do agente. Tráfego de captura de arquivos > desativado (F12)

  3. Habilite a descriptografia do tráfego HTTPS. Ferramentas > Fiddler Options > guia HTTPS. Descriptografar 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 para a conta como o serviço está sendo executado.

  6. Reinicie o agente.

Use o rastreamento HTTP completo - macOS e Linux

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

  1. Inicie o Charles Proxy.

  2. Charles: Proxy > Proxy Settings > SSL Tab. Enable. Adicionar URL.

  3. Charles: Proxy > Mac OSX Proxy. Recomende desativar 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 sendo executado como um serviço, você pode definir no arquivo .env. Veja 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 estiver a trabalhar com suporte ao cliente, poderá ser-lhe pedido que capture registos como estes.

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 ambas as maneiras de carregar logs personalizados.

Carregar um registo como parte dos registos 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 visualizado 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: carregar 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 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, consulte Publicar artefatos de pipeline.

Capturar detalhes de utilização de recursos

Ao usar os Serviços de DevOps do Azure, você pode ver a utilização de recursos nos logs, incluindo uso de disco, uso de memória e utilização de CPU, habilitando logs detalhados. Quando o pipeline for concluído, procure entradas nos logs para Agent environment resources 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 de DevOps do Azure ou se quiser coletar métricas adicionais, poderá usar o PowerShell para capturar a utilização de recursos e carregá-los nos logs de pipeline. Quando a execução do pipeline for concluída, você poderá baixar os logs do 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 de processo dotnet usando ProcDump

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

Capturar perfview rastreamentos para compilação do Visual Studio

Se o suporte ao cliente solicitar que você crie um perfview rastreamento de sua compilação do Visual Studio, adicione as seguintes tarefas ao seu 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 o suporte ao cliente desse 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 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