ログを確認してパイプラインの問題を診断する

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

パイプライン ログは、パイプラインエラーの原因を特定するための強力なツールを提供します。詳細ログは、より多くの診断情報を提供するように構成できます。

一般的な開始点は、完了したビルドまたはリリースのログを確認することです。 ログを表示するには、パイプライン実行の概要に移動し、ジョブとタスクを選択します。 特定のタスクが失敗した場合は、そのタスクのログを確認します。 詳細ログを構成 して、より多くの診断情報を含めます。

詳細ログを構成する

トラブルシューティングを支援するために、ログをより詳細に構成できます。

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 診断ログ

ビルド エージェントでワーカー プロセスによって生成された完了したビルドの診断ログを取得できます。 完了したビルドの日付と時刻のスタンプを持つ worker ログ ファイルを探します。 たとえば、「 worker_20160623-192022-utc_6172.log 」のように入力します。

エージェント診断ログ

エージェント診断ログには、エージェントの構成方法と、エージェントの実行時の変更点の記録が表示されます。 agentログ ファイルを探します。 たとえば、「 agent_20160624-144630-utc.log 」のように入力します。 エージェント ログ ファイルには、次の 2 種類があります。

• config.cmdの実行時に生成されたログ ファイル。 このログ:

  • 上部付近に次の行が含まれます。 Adding Command: configure

  • 行われた構成の選択を示します。

• run.cmdの実行時に生成されたログ ファイル。 このログ:

  • プロセスが終了するまで開くことができません。

  • Azure DevOps 組織または Team Foundation Server への接続を試みます。

  • 各ジョブが実行された日時と完了した方法を示します

どちらのログも、エージェントの機能が検出され、設定された方法を示しています。

その他のログ

診断ログ内には、 environment.txt と capabilities.txtがあります。

environment.txt ファイルには、ビルドを実行した環境に関するさまざまな情報が含まれています。 これには、実行されるタスク、ファイアウォールが有効かどうか、PowerShell のバージョン情報、その他の項目などの情報が含まれます。 このデータは、役に立つよう継続的に追加されます。

capabilities.txt ファイルは、ビルドを実行したビルド マシンにインストールされているすべての機能を表示するクリーンな方法を提供します。

HTTP トレース ログ

• 組み込みの HTTP トレースを使用する
• 完全な HTTP トレースを使用する - Windows
• 完全な HTTP トレースを使用する - macOS と Linux

組み込みの 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

1. Fiddler を起動します。

2. エージェント トラフィックのみをリッスンすることをお勧めします。 ファイル > キャプチャ トラフィックオフ (F12)

3. HTTPS トラフィックの暗号化解除を有効にします。 [ツール] > [Fiddler オプション] > [HTTPS] タブ。HTTPS トラフィックの暗号化を解除する

4. プロキシの使用をエージェントに通知します。

   set VSTS_HTTP_PROXY=http://127.0.0.1:8888
   

5. エージェントを対話形式で実行します。 サービスとして実行している場合は、サービスが実行されているアカウントのコントロール パネルで環境変数として設定できます。

6. エージェントを再起動します。

完全な HTTP トレースを使用する - macOS と Linux

Charles プロキシ (Windows の Fiddler と同様) を使用して、エージェントの HTTP トレースをキャプチャします。

1. Charles Proxy を起動します。

2. Charles: プロキシ > プロキシ設定 > SSL タブ。有効にします。 URL を追加します。

3. Charles: Proxy > Mac OSX Proxy. エージェント トラフィックのみを表示するには、無効にすることをお勧めします。

   export VSTS_HTTP_PROXY=http://127.0.0.1:8888
   

4. エージェントを対話形式で実行します。 サービスとして実行されている場合は、.env ファイルで設定できます。 nix service を参照してください

5. エージェントを再起動します。

カスタム ログをキャプチャする

組み込みのログに加えて、タスクとスクリプトを使用して、パイプライン内のカスタム ログをキャプチャできます。 次の例では、リソース使用率、ネットワーク トレース、メモリ ダンプ、および perfview トレースをキャプチャする方法を示します。 カスタマー サポートを使用している場合は、次のようなログをキャプチャするように求められる場合があります。

• リソース使用率の詳細をキャプチャする
• ProcDump を使用して dotnet プロセス メモリ ダンプをキャプチャする
• ホストされるエージェントの ETW トレースをキャプチャする
• Capture perfview traces for Visual Studio build

カスタム ログを取得する

パイプラインでカスタム ログをキャプチャした後、それをアップロードしてレビュー用に取得できるようにする必要があります。 カスタム ログは、標準パイプライン ログの一部としてアップロードすることも、成果物としてアップロードすることもできます。 次のセクションの例では、カスタム ログをアップロードする両方の方法を示します。

標準ログの一部としてログをアップロードする

標準パイプライン ログの一部としてカスタム ログをアップロードするには、 ##vso[task.uploadfile] を使用して目的のファイルをアップロードします。 このコマンドを使用するには、次の例に示すようにスクリプト コマンドの一部として指定します。 ファイルは、標準のパイプライン ログの一部として ダウンロードして表示 できます。 ##vso[task.uploadfile]メソッドは、1 つのログ ファイルをアップロードする場合に適しています。 複数のログ ファイルがある場合は、ファイルごとに個別の ##vso[task.uploadfile] 行を使用する必要があります。

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

詳細については、「 ログ 記録コマンド 」および「 UploadFile: タスク ログと共にダウンロードできるファイルをアップロードする」を参照してください。

パイプライン成果物としてログをアップロードする

カスタム ログをパイプライン成果物としてアップロードするには、 PublishPipelineArtifact@1 タスクを使用します。 PublishPipelineArtifact@1 は、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 番目のステップである場合、ログ内のファイル名が 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 プロセスのメモリ ダンプをキャプチャするようカスタマー サポートから求められる場合があります。 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 トレースを含むパイプライン ログをダウンロードできます。

# 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