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

[アーティクル]
04/02/2024

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

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

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

詳細ログを構成する

トラブルシューティングに役立つように、ログを詳細に構成することができます。

1 回の実行に対して詳細ログを構成するには、[パイプラインの実行] を選択し、[システムの診断を有効にする]、[実行] の順に選択して、新しいビルドを開始できます。
すべての実行の詳細ログを構成するには、system.debug という名前の変数を追加し、その値を true に設定します。

1 回の実行の詳細ログを構成するには、[ビルドをキューに挿入] を選択し、system.debug 変数の値を true に設定して、新しいビルドを開始できます。
すべての実行の詳細ログを構成するには、ビルドを編集し、[変数] タブに移動して、system.debug という名前の変数を追加し、その値を true に設定して、[キューの時点で許可] を選択します。
YAML パイプラインの詳細ログを構成するには、system.debug セクションに variables 変数を追加します。
```
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 診断ログ

ビルドエージェントのワーカープロセスによって生成された完了したビルドの診断ログを取得できます。完了したビルドの日付と時刻のスタンプを含む 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 への接続を試みます。
- 各ジョブがいつ実行され、どのように完了したかを示します

どちらのログも、エージェントの機能がどのように検出され、設定されたかを示します。

セルフホステッドエージェントのネットワーク診断

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

Note

Agent.Diagnostic が true に設定されている場合、System.Debug は自動的に true に設定されます。

このセクションで説明した Agent.Diagnostic 変数とログは、エージェント v2.200.0 以降で使用できます。

詳しくは、Azure Pipelines エージェントの microsoft/azure-pipelines-agent オープンソースエージェントリポジトリで、エージェントのトラブルシューティングに関する説明をご覧ください。

その他のログ

診断ログ内には、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 を開始します。
エージェントトラフィックのみをリッスンすることをお勧めします。 [File] (ファイル) > [Capture Traffic] (トラフィックのキャプチャ) をオフ (F12)
HTTPS トラフィックの暗号化解除を有効にします。 [Tools] (ツール) > [Fiddler Options] (Fiddler のオプション) > [HTTPS] タブ。[Decrypt HTTPS traffic] (HTTPS トラフィックの暗号化解除)
エージェントにプロキシの使用を通知します。
```
set VSTS_HTTP_PROXY=http://127.0.0.1:8888
```
エージェントを対話的に実行します。サービスとして実行している場合は、サービスが実行されているアカウントのコントロールパネルで環境変数として設定できます。
エージェントを再起動します。

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

Charles Proxy (Windows の場合の Fiddler に類似) を使用して、エージェントの HTTP トレースを取得します。

Charles Proxy を開始します。
Charles: [Proxy] (プロキシ) > [Proxy Settings] (プロキシ設定) > [SSL] タブ。有効。 URL の追加
Charles: [Proxy] (プロキシ) > [Mac OSX Proxy] (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 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プロセスのメモリダンプをキャプチャするように要求されることがあります。 Visual Studio Testタスクの後に、以下のタスクを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 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

次の方法で共有

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

詳細ログを構成する

ログを表示してダウンロードする

worker 診断ログ

エージェント診断ログ

セルフホステッドエージェントのネットワーク診断

その他のログ

HTTP トレースログ

組み込みの HTTP トレースを使用する

完全な HTTP トレースを使用する - Windows

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

カスタムログのキャプチャ

カスタムログの取得

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

ログをパイプラインアーティファクトとしてアップロードする

リソース使用率の詳細をキャプチャする

ProcDumpを使用したdotnetプロセスメモリダンプのキャプチャ

ホストエージェントのETWトレースのキャプチャ

Visual Studioビルドのperfviewトレースをキャプチャする

フィードバック

その他のリソース

次の方法で共有

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

詳細ログを構成する

ログを表示してダウンロードする

worker 診断ログ

エージェント診断ログ

セルフホステッド エージェントのネットワーク 診断

その他のログ

HTTP トレース ログ

組み込みの HTTP トレースを使用する

完全な HTTP トレースを使用する - Windows

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

カスタムログのキャプチャ

カスタムログの取得

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

ログをパイプラインアーティファクトとしてアップロードする

リソース使用率の詳細をキャプチャする

ProcDumpを使用したdotnetプロセスメモリダンプのキャプチャ

ホストエージェントのETWトレースのキャプチャ

Visual Studioビルドのperfviewトレースをキャプチャする

フィードバック

その他のリソース

セルフホステッドエージェントのネットワーク診断

HTTP トレースログ