檢閱記錄以診斷管線問題

發行項
03/26/2025

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

管線記錄提供一個功能強大的工具來判斷管線失敗的原因，而且可以設定詳細信息記錄來提供更多診斷資訊。

典型的起點是檢閱已完成組建或發行中的記錄。您可以藉由瀏覽至管線執行摘要並選擇作業和任務來檢視日誌。如果特定的工作失敗，請檢查該工作的記錄。配置詳細日誌，以包含更多診斷資訊。

設定詳細信息記錄

若要協助進行疑難排解，您可以將記錄設定為更詳細。

若要設定單一執行的詳細信息記錄，您可以選擇 [執行管線]，然後 選取 [啟用系統診斷]，[執行]來啟動新的組建。
若要設定所有執行的詳細資訊記錄，您可以新增名為 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%

檢視和下載記錄

若要檢視每個步驟的個別記錄，請流覽至執行的建置結果，然後選取作業和步驟。

工作記錄檔

若要下載所有記錄，請瀏覽至執行中的組建結果，選取 [...]，然後選擇 [下載記錄。

下載記錄

除了管線診斷記錄之外，還有下列特製化記錄類型可供使用，而且可能包含可協助您進行疑難解答的資訊。

工作者診斷記錄
代理程式診斷記錄
其他記錄

工作者診斷記錄

您可以在建置代理程式上取得工作處理程序所產生的已完成建置診斷記錄。尋找具有已完成組建日期和時間戳的 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.*`	帳戶群組成員資格清單	窗戶

備註

Agent.Diagnostic 如果設定為 true，System.Debug 會自動設定為 true。

本節所述的 Agent.Diagnostic 變數和記錄，適用於 Agent 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：Proxy > Mac OSX Proxy。建議停用以只查看代理流量。
```
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 時，您可以在記錄中看到資源使用率，包括磁碟使用量、記憶體使用量和 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 擷取 .NET 程序記憶體傾印

如果您有當機的測試執行，客戶支援可能會要求您在測試執行失敗之後擷取 dotnet 進程的記憶體轉儲。使用 condition: always()，在 Visual Studio 測試工作之後新增下列工作。當管線執行完成時，您可以下載管線記錄，包括記憶體轉儲。

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

共用方式為

檢閱記錄以診斷管線問題

設定詳細信息記錄

檢視和下載記錄

工作者診斷記錄

代理程式診斷記錄

自行架設代理程式的網路診斷

其他記錄

HTTP 追蹤記錄

使用內建 HTTP 追蹤

使用完整的 HTTP 追蹤 - Windows

使用完整的 HTTP 追蹤 - macOS 和 Linux

擷取自定義記錄

擷取自定義記錄

將日誌上傳為標準日誌的一部分

將日誌作為流水線產物上傳

擷取資源使用率詳細數據

使用 ProcDump 擷取 .NET 程序記憶體傾印

擷取託管代理程式的 ETW 追蹤

擷取 Visual Studio 組建的 perfview 追蹤

意見反應

其他資源