查看日志以诊断管道问题

项目
04/02/2024

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

管道日志为确定管道故障原因提供了一个强大的工具，而且可以配置详尽的日志以提供更多的诊断信息。

一个典型的起点是查看已完成的生成或发布中的日志。可导航到管道运行摘要并选择作业和任务来查看日志。如果某个任务失败，请检查该任务的日志。配置详细日志以包含更多诊断信息。

配置详细日志

为了帮助进行故障排除，你可以将日志配置得更详细一些。

若要为单个运行配置详细日志，可以通过依次选择“运行管道”、“启用系统诊断”、“运行”来启动新的生成。
若要为所有运行配置详细日志，可以添加名为 system.debug 的变量，并将其值设置为 true。

若要为单个运行配置详细日志，可以通过选择“将生成排队”，然后将 system.debug 变量的值设置为 true，来启动新的生成。
若要为所有运行配置详细日志，请编辑生成，导航到“变量”选项卡，添加名为 system.debug 的变量并将其值设置为 true，然后选择“排队时允许”。
若要为 YAML 管道配置详细日志，请在 variables 节中添加 system.debug 变量：
```
variables:
  system.debug: true
```

Azure 管道日志现在可以捕获资源利用率指标，例如内存、CPU 使用率和可用磁盘空间。这些日志还包括管道代理使用的资源和子进程（包括作业中运行的任务）。如果怀疑管道作业可能遇到资源限制，请启用详细日志以将资源利用率信息注入管道日志。不管托管模型如何，在任何代理上都能获取资源利用率指标。

要查看捕获的资源利用率指标，请搜索日志以查找每个步骤的 Agent environment resources 条目。

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%

查看和下载日志

若要查看每个步骤的单独日志，请导航到运行的生成结果，然后选择作业和步骤。

任务日志

若要下载所有日志，请导航到运行的生成结果，选择“...”，然后选择“下载日志”。

下载日志

若要下载所有日志，请导航到运行的生成结果，然后选择“以 zip 格式下载所有日志”。

除了管道诊断日志外，还可以使用以下专用日志类型，其中可能包含有助于故障排除的信息。

工作进程诊断日志
代理诊断日志
其他日志

工作进程诊断日志

可以获取由生成代理上的工作进程生成的已完成生成的诊断日志。查找包含已完成生成的日期和时间戳的 worker 日志文件。例如，worker_20160623-192022-utc_6172.log。

代理诊断日志

代理诊断日志记录了代理的配置方式以及运行代理时发生的情况。查找 agent 日志文件。例如，agent_20160624-144630-utc.log。有两种代理日志文件：

运行 config.cmd 时生成的日志文件。此日志：
- 在顶部附近包含此行：Adding Command: configure
- 显示做出的配置选择。
运行 run.cmd 时生成的日志文件。此日志：
- 在进程终止之前无法打开。
- 尝试连接到 Azure DevOps 组织或 Team Foundation Server。
- 显示每个作业的运行时间及其完成方式

这两个日志都会显示代理功能的检测和设置方式。

自托管代理的网络诊断

将 Agent.Diagnostic 的值设置为 true 以收集其他日志，这些日志可用于排查自托管代理的网络问题。

文件	信息	适用于
`cloudinit.*`	Cloud-init 成功完成（如果使用）	Linux
`BrokenPackages.*`	包处于一致状态	Linux
`Agent.*`	环境变量	Linux、Windows
`waagentConf.txt`	Azure VM 代理 (waagent.conf)	Azure：Linux、Windows
`environment.txt` / `agent.*`	帐户组成员身份列表	Windows

注意

当 System.Debug 设置为 true 时，Agent.Diagnostic 会自动设置为 true。

本部分中介绍的 Agent.Diagnostic 变量和日志可用于代理 v2.200.0 及更高版本。

有关详细信息，请参阅 microsoft/azure-pipelines-agent Azure Pipelines 代理开源代理存储库中的代理故障排除。

其他日志

在诊断日志中，可以找到 environment.txt 和 capabilities.txt。

environment.txt 文件包含有关运行生成的环境的各种信息。这些信息包括运行了哪些任务、是否启用了防火墙、PowerShell 版本信息和其他一些项。我们会不断地补充这些数据，以使此文件更有用。

capabilities.txt 文件提供了一种简洁方式用于查看运行生成的生成计算机上安装的所有功能。

重要

HTTP 跟踪和跟踪文件可以包含密码和其他机密。不要在公共站点上发布这些机密。

使用内置 HTTP 跟踪

如果代理版本为 2.114.0 或更高，你可以跟踪 HTTP 流量标头并将其写入诊断日志。在启动 agent.listener 之前设置 VSTS_AGENT_HTTPTRACE 环境变量。

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

使用完整 HTTP 跟踪 - Windows

启动 Fiddler。
建议仅侦听代理流量。文件 > 关闭捕获流量 (F12)
启用解密 HTTPS 流量。工具 > Fiddler 选项 > HTTPS 选项卡。解密 HTTPS 流量
告知代理要使用代理服务器 (Proxy)：
```
set VSTS_HTTP_PROXY=http://127.0.0.1:8888
```
以交互方式运行代理。如果作为服务运行，你可以在运行服务的帐户的控制面板中设置为环境变量。
重新启动该代理。

使用完整 HTTP 跟踪 - macOS 和 Linux

使用 Charles Proxy（类似于 Windows 上的 Fiddler）捕获代理的 HTTP 跟踪。

启动 Charles Proxy。
Charles：代理 > 代理设置 > SSL 选项卡。启用。添加 URL。
Charles：代理 > Mac OSX 代理。建议禁用以便仅查看代理流量。
```
export VSTS_HTTP_PROXY=http://127.0.0.1:8888
```
以交互方式运行代理。如果它作为服务运行，你可以在 .env 文件中设置。请参见nix service
重新启动该代理。

捕获自定义日志

除了内置日志之外，还可以使用任务和脚本在管道中捕获自定义日志。以下示例展示了如何捕获资源利用率、网络跟踪、内存转储和 perfview 跟踪。如果是与客户支持部门协作，他们可能会要求捕获类似的日志。

捕获资源利用率详细信息
使用 ProcDump 捕获 dotnet 进程内存转储
捕获托管代理的 ETW 跟踪
Capture perfview traces for Visual Studio build

检索自定义日志

在管道中捕获自定义日志后，必须将其上传以便检索供审查。可以将自定义日志作为标准管道日志的一部分上传，也可以将其作为工件上传。以下各节的示例展示了上传自定义日志的两种方式。

将日志作为标准日志的一部分上传

要将自定义日志作为标准管道日志的一部分上传，请使用 ##vso[task.uploadfile] 上传所需的文件。要使用此命令，请将其指定为脚本命令的一部分，如下例所示。该文件可作为标准管道日志的一部分下载和查看。 ##vso[task.uploadfile] 方法适用于上传单个日志文件。如果有多个日志文件，则必须为每个文件使用单独的 ##vso[task.uploadfile] 行。

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

有关详细信息，请参阅日志记录命令和UploadFile：上传可随任务日志下载的文件。

将日志作为管道工件上传

要将自定义日志作为管道工件上传，请使用 PublishPipelineArtifact@1 任务。 PublishPipelineArtifact@1 可以上传单个文件或目录路径中的文件，如果有许多自定义日志文件需要上传，它将非常有用。

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

有关详细信息，请参阅发布管道工件。

捕获资源利用率详细信息

在使用 Azure DevOps Services 时，启用 verbose logs 可以查看日志中的资源利用率，包括磁盘使用情况、内存使用情况和 CPU 利用率。在管道完成后，请搜索日志以查找每个步骤的 Agent environment resources 条目。

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%

如果使用 Azure DevOps Server，或者想收集其他指标，则可以使用 PowerShell 捕获资源利用率并将其上传到管道日志。在管道运行完成后，可以下载管道日志并查看捕获的数据。如果 Upload resource usage from pipeline run 步骤是作业中的第六步，则日志中的文件名将是 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()

使用 ProcDump 捕获 dotnet 进程内存转储

如果测试执行过程中发生崩溃，则客户支持部门可能会要求在测试执行失败后捕获 dotnet 进程的内存转储。在 Visual Studio 测试任务后通过 condition: always() 添加以下任务。在管道运行完成后，可以下载管道日志，包括内存转储。

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

捕获托管代理的 ETW 跟踪

如果要对 Microsoft 托管代理的网络问题进行故障排除，客户支持可能会要求收集 ETW 跟踪。在管道运行完成后，可以下载管道日志，包括 ETW 跟踪。

Windows 代理
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'

为 Visual Studio 生成捕获 perfview 曲线

如果客户支持要求创建 Visual Studio 生成的 perfview 跟踪，请在 Visual Studio 生成步骤前后将以下任务添加到管道中。

在运行管道后，可以从管道运行详细信息中下载 PerfViewLog 工件，并将该文件发送给客户支持。

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