Überprüfen von Protokollen zum Diagnostizieren von Pipelineproblemen

  • Artikel

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

Pipelineprotokolle bieten ein leistungsfähiges Tool zur Ermittlung der Ursache von Pipelinefehlern. Ausführliche Protokolle können für die Bereitstellung erweiterter Diagnoseinformationen konfiguriert werden.

Ein typischer Ausgangspunkt ist die Überprüfung der Protokolle in Ihrem abgeschlossenen Build oder Release. Sie können Protokolle anzeigen, indem Sie zur Zusammenfassung der Pipelineausführung navigieren und dann den Auftrag und die Aufgabe auswählen. Wenn eine bestimmte Aufgabe fehlschlägt, überprüfen Sie die Protokolle dafür. Konfigurieren Sie ausführliche Protokolle, um weitere Diagnoseinformationen einzuschließen.

Ausführliche Protokolle konfigurieren

Um die Problembehandlung zu vereinfachen, können Sie die Ausgabe Ihre Protokolle ausführlicher machen.

  • Um ausführliche Protokolle für eine einzelne Ausführung zu konfigurieren, können Sie einen neuen Build starten, indem Sie Pipeline ausführen und System Diagnose aktivieren, Ausführen auswählen.

    Systemdiagnose aktivieren

  • Um ausführliche Protokolle für alle Ausführungen zu konfigurieren, können Sie eine Variable mit dem Namen system.debug hinzufügen und ihren Wert auf truefestlegen.

  • Um ausführliche Protokolle für eine einzelne Ausführung zu konfigurieren, können Sie einen neuen Build starten, indem Sie Warteschlangenbuild auswählen und den Wert für die system.debug Variable auf truefestlegen.

  • Um ausführliche Protokolle für alle Ausführungen zu konfigurieren, bearbeiten Sie den Build, navigieren Sie zur Registerkarte Variablen , und fügen Sie eine Variable mit dem Namen system.debughinzu, legen Sie ihren Wert auf truefest, und wählen Sie Zur Warteschlangenzeit zulassen aus.

  • Um ausführliche Protokolle für eine YAML-Pipeline zu konfigurieren, fügen Sie die system.debug Variable im variables Abschnitt hinzu:

    variables:
  system.debug: true

Azure-Pipelineprotokolle können jetzt Metriken zu Ressourcen erfassen, z. B. zur Arbeitsspeicherauslastung, CPU-Auslastung und zum verfügbaren Speicherplatz. Die Protokolle enthalten auch Ressourcen, die vom Pipeline-Agent und untergeordneten Prozessen verwendet werden, einschließlich Tasks, die in einem Auftrag ausgeführt werden. Wenn Sie vermuten, dass Ihr Pipelineauftrag zu Ressourceneinschränkungen führt, aktivieren Sie ausführliche Protokolle, um Ressourcennutzungsinformationen in Pipelineprotokolle aufzunehmen. Metriken zur Ressourcenauslastung sind für jeden Agent verfügbar, unabhängig vom Hostingmodell.

Um die erfassten Ressourcenauslastungsmetriken anzuzeigen, durchsuchen Sie die Protokolle nach Agent environment resources Einträgen für jeden Schritt.

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%

Anzeigen und Herunterladen von Protokollen

Um einzelne Protokolle für jeden Schritt anzuzeigen, navigieren Sie zu den Buildergebnissen für die Ausführung, und wählen Sie den Auftrag und den Schritt aus.

Taskprotokoll

Navigieren Sie zum Herunterladen aller Protokolle zu den Buildergebnissen für die Ausführung, wählen Sie ... und dann Protokolle herunterladen aus.

Herunterladen von Protokollen

Navigieren Sie zum Herunterladen aller Protokolle zu den Buildergebnissen für die Ausführung, wählen Sie Download all logs as zip (alle Protokolle als zip herunterladen) aus.

Zusätzlich zu den Pipelinediagnoseprotokollen sind die folgenden spezialisierten Protokolltypen verfügbar und enthalten möglicherweise Informationen zur Problembehandlung.

Workerdiagnoseprotokolle

Sie können das Diagnoseprotokoll des abgeschlossenen Builds abrufen, das vom Workerprozess auf dem Build-Agent generiert wurde. Suchen Sie nach der worker Protokolldatei, die den Datums- und Zeitstempel Ihres abgeschlossenen Builds enthält. Beispiel: worker_20160623-192022-utc_6172.log.

Agent-Diagnoseprotokolle

Die Diagnoseprotokolle des Agents enthalten einen Datensatz darüber, wie der Agent konfiguriert wurde und was bei der Ausführung passiert ist. Suchen Sie nach den agent-Protokolldateien. Beispiel: agent_20160624-144630-utc.log. Es gibt zwei Arten von Agent-Protokolldateien:

  • Die Protokolldatei, die beim Ausführen config.cmdvon generiert wurde. Dieses Protokoll:

    • Enthält diese Zeile am oberen Rand: Adding Command: configure

    • Zeigt die getroffenen Konfigurationsoptionen an.

  • Die Protokolldatei, die beim Ausführen run.cmdvon generiert wurde. Dieses Protokoll:

    • Kann erst geöffnet werden, wenn der Prozess beendet wird.

    • Versucht, eine Verbindung mit Ihrem Azure DevOps-organization oder Team Foundation Server herzustellen.

    • Zeigt an, wann jeder Auftrag ausgeführt wurde und wie er abgeschlossen wurde

Beide Protokolle zeigen, wie die Agentfunktionen erkannt und festgelegt wurden.

Netzwerkdiagnose für selbstgehostete Agents

Legen Sie den Wert von Agent.Diagnostic auf fest true, um zusätzliche Protokolle zu sammeln, die zur Behandlung von Netzwerkproblemen für selbstgehostete Agents verwendet werden können.

Datei Information Gilt für:
cloudinit.* cloud-init erfolgreich abgeschlossen (falls verwendet) Linux
BrokenPackages.* Pakete weisen einen einheitlichen Zustand auf. Linux
Agent.* Umgebungsvariablen Linux, Windows
waagentConf.txt Azure-VM-Agent (waagent.conf) Azure: Linux, Windows
environment.txt / agent.* Mitgliederliste der Kontogruppe Windows

Hinweis

Agent.Diagnostic wird automatisch auf true festgelegt, wenn System.Debug auf truefestgelegt ist.

Die in diesem Abschnitt beschriebene Agent.Diagnostic-Variable und die Protokolle sind in Agent 2.200.0 und höher verfügbar.

Weitere Informationen finden Sie unter Agent-Problembehandlung im Open-Source-Repository für den Azure Pipelines-Agent unter microsoft/azure-pipelines-agent.

Weitere Protokolle

In den Diagnoseprotokollen finden environment.txt Sie und capabilities.txt.

Die environment.txt Datei enthält verschiedene Informationen über die Umgebung, in der Ihr Build ausgeführt wurde. Dies umfasst Informationen wie die Ausgeführten Aufgaben, ob die Firewall aktiviert ist oder nicht, PowerShell-Versionsinformationen und einige andere Elemente. Wir fügen diese Daten kontinuierlich hinzu, um sie nützlicher zu machen.

Die capabilities.txt Datei bietet eine sauber Möglichkeit, alle Funktionen anzuzeigen, die auf dem Buildcomputer installiert sind, auf dem Ihr Build ausgeführt wurde.

HTTP-Ablaufverfolgungsprotokolle

Wichtig

HTTP-Ablaufverfolgungs- und Ablaufverfolgungsdateien können Kennwörter und andere Geheimnisse enthalten. Posten Sie sie nicht auf öffentlichen Websites.

Verwenden der integrierten HTTP-Ablaufverfolgung

Wenn Ihr Agent version 2.114.0 oder höher ist, können Sie die HTTP-Datenverkehrsheader nachverfolgen und in das Diagnoseprotokoll schreiben. Legen Sie die Umgebungsvariable VSTS_AGENT_HTTPTRACE fest, bevor Sie agent.listener starten.

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

Verwenden der vollständigen HTTP-Ablaufverfolgung – Windows

  1. Starten Sie Fiddler.

  2. Es wird empfohlen, nur den Agentdatenverkehr zu überwachen. Datenverkehr für Dateierfassung > deaktiviert (F12)

  3. Aktivieren Sie die Entschlüsselung von HTTPS-Datenverkehr. Extras > Registerkarte "Fiddler-Optionen > HTTPS". Entschlüsseln des HTTPS-Datenverkehrs

  4. Informieren Sie den Agent über die Verwendung des Proxys:

    set VSTS_HTTP_PROXY=http://127.0.0.1:8888

  5. Interaktive Ausführung des Agents. Wenn Sie als Dienst ausgeführt werden, können Sie in der Systemsteuerung als Umgebungsvariable für das Konto festlegen, unter dem der Dienst ausgeführt wird.

  6. Starten Sie den Agent neu.

Verwenden der vollständigen HTTP-Ablaufverfolgung – macOS und Linux

Verwenden Sie Charles Proxy (ähnlich wie Fiddler unter Windows), um die HTTP-Ablaufverfolgung des Agents zu erfassen.

  1. Starten Sie Charles Proxy.

  2. Charles: Ssl-Registerkarte >Proxyproxyeinstellungen>. Aktivieren. URL hinzufügen.

  3. Charles: Proxy > Mac OSX Proxy. Empfehlen Sie die Deaktivierung, um nur Agentdatenverkehr anzuzeigen.

    export VSTS_HTTP_PROXY=http://127.0.0.1:8888

  4. Interaktive Ausführung des Agents. Wenn er als Dienst ausgeführt wird, können Sie in der ENV-Datei festlegen. Informationen finden Sie unter nix service.

  5. Starten Sie den Agent neu.

Erfassen benutzerdefinierter Protokolle

Verwenden Sie zusätzlich zu den integrierten Protokollen Aufgaben und Skripts, um benutzerdefinierte Protokolle in Ihrer Pipeline zu erfassen. Die folgenden Beispiele zeigen, wie Ressourcenauslastung, Netzwerkablaufverfolgungen, Speicherabbilder und perfview Ablaufverfolgungen erfasst werden. Wenn Sie mit dem Kundensupport arbeiten, werden Sie möglicherweise aufgefordert, Protokolle wie diese zu erfassen.

Abrufen benutzerdefinierter Protokolle

Nachdem Sie ein benutzerdefiniertes Protokoll in Ihrer Pipeline erfasst haben, laden Sie es hoch, damit es zur Überprüfung abgerufen werden kann. Sie können das benutzerdefinierte Protokoll als Teil der Standardpipelineprotokolle oder als Artefakt hochladen. Die Beispiele in den folgenden Abschnitten zeigen beide Möglichkeiten zum Hochladen von benutzerdefinierten Protokollen.

Hochladen eines Protokolls als Teil der Standardprotokolle

Um das benutzerdefinierte Protokoll als Teil der Standardpipelineprotokolle hochzuladen, verwenden Sie ##vso[task.uploadfile], um die gewünschte Datei hochzuladen. Um diesen Befehl zu verwenden, geben Sie ihn als Teil eines Skriptbefehls an, wie im folgenden Beispiel gezeigt. Die Datei kann als Teil der Standardpipelineprotokolle heruntergeladen und angezeigt werden. Die Methode ##vso[task.uploadfile] eignet sich gut zum Hochladen einer einzelnen Protokolldatei. Wenn Sie über mehrere Protokolldateien verfügen, müssen Sie für jede Datei eine separate ##vso[task.uploadfile] Zeile verwenden.

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

Weitere Informationen finden Sie unter Protokollierungsbefehle und UploadFile: Hochladen einer Datei, die mit Aufgabenprotokollen.

Hochladen eines Protokolls als Pipelineartefakt

Um ein benutzerdefiniertes Protokoll als Pipelineartefakt hochzuladen, verwenden Sie die Aufgabe PublishPipelineArtifact@1. PublishPipelineArtifact@1 kann eine einzelne Datei oder die Dateien in einem Verzeichnispfad hochladen und ist nützlich, wenn Sie viele benutzerdefinierte Protokolldateien hochladen müssen.

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

Weitere Informationen finden Sie unter Pipelineartefakte veröffentlichen.

Erfassen von Ressourcenauslastungsdetails

Wenn Sie Azure DevOps Services verwenden, können Sie die Ressourcenauslastung in den Protokollen sehen, einschließlich Datenträgernutzung, Speicherauslastung und CPU-Auslastung, indem Sie ausführliche Protokolle aktivieren. Wenn die Pipeline abgeschlossen ist, durchsuchen Sie die Protokolle nach Agent environment resources Einträgen für jeden Schritt.

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%

Wenn Sie Azure DevOps Server nutzen oder zusätzliche Metriken erfassen möchten, können Sie PowerShell verwenden, um die Ressourcenauslastung zu erfassen und in die Pipelineprotokolle hochzuladen. Nach Abschluss der Pipelineausführung können Sie die Pipelineprotokolle herunterladen und die erfassten Daten anzeigen. Wenn es sich bei Upload resource usage from pipeline run um den sechsten Schritt in der Anleitung handelt, wird der Dateiname in den Protokollen 6_resource-usage.txt sein.

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

Erfassen eines Dotnet-Prozessspeicherabbilds mit ProcDump

Wenn Ihre Testausführung nicht erfolgreich verläuft, werden Sie vom Kundensupport möglicherweise aufgefordert, nach der fehlgeschlagenen Testausführung ein Speicherabbild des Dotnet-Prozesses zu erfassen. Fügen Sie die folgende Aufgabe nach der Visual Studio Test-Aufgabe mit condition: always() an. Nach Abschluss der Pipelineausführung können Sie die Pipelineprotokolle einschließlich des Speicherabbilds herunterladen.

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

Erfassen von ETW-Ablaufverfolgungen für einen gehosteten Agent

Wenn Sie Netzwerkprobleme mit von Microsoft gehosteten Agents beheben, werden Sie vom Kundensupport möglicherweise aufgefordert, ETW-Ablaufverfolgungen zu sammeln. Nach Abschluss der Pipelineausführung können Sie die Pipelineprotokolle einschließlich der ETW-Ablaufverfolgungen herunterladen.

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

Erfassen von perfview Ablaufverfolgungen für den Visual Studio-Build

Wenn Sie vom Kundensupport aufgefordert werden, eine perfview Ablaufverfolgung Ihres Visual Studio-Builds zu erstellen, fügen Sie Ihrer Pipeline vor und nach dem Visual Studio-Buildschritt die folgenden Aufgaben hinzu.

Nach der Pipelineausführung können Sie das PerfViewLog-Artefakt aus den Pipelineausführungsdetails herunterladen und diese Datei dem Kundensupport senden.

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