Revisión de registros para diagnosticar problemas de canalización

Artículo
04/02/2024

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

Los registros de canalizaciones son una herramienta poderosa para determinar la causa de los fallos en las canalizaciones, y los registros detallados pueden configurarse para proporcionar más información de diagnóstico.

Un punto de partida habitual consiste en revisar los registros de una versión o compilación completada. Para ver los registros, vaya al resumen de ejecución de canalización y seleccione el trabajo y la tarea. Si se ha generado un error en una tarea determinada, compruebe los registros de esa tarea. Configure los registros detallados para incluir más información de diagnóstico.

Configuración de registros detallados

Para ayudar con la solución de problemas, puede configurar los registros para que sean más detallados.

Para configurar registros detallados para una sola ejecución, puede iniciar una nueva compilación; para ello, elija Ejecutar canalización y seleccione Habilitar el diagnóstico del sistema, Ejecutar.
Para configurar registros detallados para todas las ejecuciones, puede agregar una variable denominada system.debug y establecer su valor en true.

Para configurar registros detallados para una sola ejecución, puede iniciar una nueva compilación; para ello, seleccione Poner compilación en cola y establezca el valor de la variable system.debug en true.
Para configurar registros detallados para todas las ejecuciones, edite la compilación, vaya a la pestaña Variables y agregue una variable denominada system.debug, establezca su valor en true y seleccione Permitir durante el tiempo en cola.
Para configurar registros detallados para una canalización de YAML, agregue la variable system.debug en la sección variables:
```
variables:
  system.debug: true
```

Los registros de canalización de Azure ahora pueden capturar métricas de uso de recursos, como memoria, uso de CPU y espacio en disco disponible. Los registros también incluyen recursos usados por el agente de canalización y los procesos secundarios, incluidas las tareas que se ejecutan en un trabajo. Si sospecha que el trabajo de canalización puede encontrarse con restricciones de recursos, habilite los registros detallados para que se inserte la información de uso de los recursos en los registros de canalización. Las métricas de utilización de recursos están disponibles en cualquier agente, independientemente del modelo de alojamiento.

Para ver las métricas de utilización de recursos capturadas, busque en los registros entradas de Agent environment resources en cada paso.

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%

Visualización y descarga de registros

Para ver registros individuales de cada paso, vaya a los resultados de compilación de la ejecución y seleccione el trabajo y el paso.

Registro de tareas

Para descargar todos los registros, vaya a los resultados de compilación de la ejecución, seleccione ... y elija Descargar registros.

Descarga de registros

Para descargar todos los registros, vaya a los resultados de compilación de la ejecución y elija Descargar todos los registros como zip.

Además de los registros de diagnóstico de las canalizaciones, están disponibles los siguientes tipos de registros especializados, que pueden contener información de ayuda para la solución de problemas.

Registros de diagnóstico de trabajo
Registros de diagnóstico del agente
Otros registros

Registros de diagnóstico de trabajo

Puede obtener el registro de diagnóstico de la compilación finalizada generado por el proceso del trabajador en el agente de compilación. Busque el archivo de registro worker que tenga la marca de fecha y hora de la compilación completada. Por ejemplo, worker_20160623-192022-utc_6172.log.

Registros de diagnóstico del agente

Los registros de diagnóstico del agente proporcionan un registro de cómo se configuró el agente y qué ocurrió cuando se ejecutó. Busque los archivos de registro agent. Por ejemplo, agent_20160624-144630-utc.log. Hay dos tipos de archivos de registro del agente:

El archivo de registro generado al ejecutar config.cmd. Este registro:
- Incluye esta línea cerca de la parte superior: Adding Command: configure
- Muestra las opciones de configuración realizadas.
El archivo de registro generado al ejecutar run.cmd. Este registro:
- No se puede abrir hasta que finalice el proceso.
- Intenta conectarse a la organización de Azure DevOps o Team Foundation Server.
- Muestra cuándo se ejecutó cada trabajo y cómo se completó

Ambos registros muestran cómo se detectaron y se establecieron las capacidades del agente.

Diagnósticos de red para agentes autohospedados

Establezca el valor de Agent.Diagnostic en true para recopilar registros adicionales que se pueden usar para solucionar problemas de red para agentes autohospedados.

Archivo	Información	Se aplica a
`cloudinit.*`	Cloud-init se completó correctamente (si se usa)	Linux
`BrokenPackages.*`	Los paquetes están en un estado coherente	Linux
`Agent.*`	Variables de entorno	Linux y Windows
`waagentConf.txt`	Agente de máquina virtual de Azure (waagent.conf)	Azure: Linux, Windows
`environment.txt` / `agent.*`	Lista de pertenencia a grupos de cuentas	Windows

Nota:

Agent.Diagnostic cambia a true automáticamente cuando System.Debug cambia a true.

La variable Agent.Diagnostic y los registros descritos en esta sección están disponibles con el Agente v2.200.0 y versiones posteriores.

Para obtener más información, consulte solución de problemas del agente en el repositorio de agentes de código abierto de Azure Pipelines microsoft/azure-pipelines-agent.

Otros registros

Dentro de los registros de diagnóstico encontrará environment.txt y capabilities.txt.

El archivo environment.txt tiene información variada sobre el entorno en el que se ejecutó la compilación. Se incluye información como qué tareas se ejecutan, si el firewall se ha habilitado o no, información de la versión de PowerShell y otros aspectos. Agregamos información continuamente para que los datos sean más útiles.

El archivo capabilities.txt ofrece una forma clara de ver todas las capacidades instaladas en la máquina que ejecutó su compilación.

Registros de seguimiento HTTP

Uso del seguimiento HTTP integrado
Uso del seguimiento HTTP completo: Windows
Uso del seguimiento HTTP completo: macOS y Linux

Importante

Los archivos de seguimiento y los seguimientos HTTP pueden contener contraseñas y otros secretos. No los publique en sitios públicos.

Uso del seguimiento HTTP integrado

Si la versión del agente es 2.114.0 o posteriores, puede realizar un seguimiento de los encabezados de tráfico HTTP y escribirlos en el registro de diagnóstico. Establezca la variable de entorno VSTS_AGENT_HTTPTRACE antes de iniciar agent.listener.

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

Uso del seguimiento HTTP completo: Windows

Inicie Fiddler.
Se recomienda escuchar solo el tráfico del agente. Archivo > Capturar tráfico desactivado (F12)
Habilite el descifrado del tráfico HTTPS. Herramientas > Opciones de Fiddler > pestaña HTTPS. Descifrar tráfico HTTPS

Indique al agente que use el proxy:

set VSTS_HTTP_PROXY=http://127.0.0.1:8888

Ejecute el agente de forma interactiva. Si se está ejecutando como servicio, puede establecerlo como variable de entorno en el panel de control para la cuenta en la que se ejecuta el servicio.
Reinicie el agente.

Uso del seguimiento HTTP completo: macOS y Linux

Use Charles Proxy (similar a Fiddler en Windows) para capturar el seguimiento HTTP del agente.

Inicie Charles Proxy.
Charles: Proxy > Proxy Settings > pestaña SSL. Habilítelo. Agregar dirección URL.
Charles: Proxy > Mac OSX Proxy. Se recomienda deshabilitarlo para ver solo el tráfico del agente.
```
export VSTS_HTTP_PROXY=http://127.0.0.1:8888
```
Ejecute el agente de forma interactiva. Si se ejecuta como servicio, puede establecerlo en el archivo .env. Consulte nix service.
Reinicie el agente.

Captura de registros personalizados

Además de los registros integrados, puede utilizar tareas y scripts para capturar registros personalizados en su canalización. Los siguientes ejemplos muestran cómo capturar la utilización de recursos, seguimientos de red, volcados de memoria y seguimientos de perfview. Si trabaja con el servicio de atención al cliente, es posible que le pidan que capture registros como estos.

Capturar detalles de utilización de recursos
Capturar un volcado de memoria de un proceso dotnet utilizando ProcDump
Capturar seguimientos de ETW para un agente alojado
Capture perfview traces for Visual Studio build

Recuperar registros personalizados

Después de capturar un registro personalizado en su canalización, debe subirlo para que pueda ser recuperado para su revisión. Puede cargar el registro personalizado como parte de los registros estándar de la canalización, o puede cargarlo como un artefacto. Los ejemplos de las siguientes secciones muestran ambas formas de cargar registros personalizados.

Cargar un registro como parte de los registros estándar

Para cargar el registro personalizado como parte de los registros estándar, utilice ##vso[task.uploadfile] para cargar el archivo deseado. Para utilizar este comando, especifíquelo como parte de un comando de script como se muestra en el siguiente ejemplo. El archivo puede descargarse y visualizarse como parte de los registros de canalización estándar. Este método ##vso[task.uploadfile] es adecuado para cargar un único archivo de registro. Si tiene más de un archivo de registro, debe utilizar una línea distinta ##vso[task.uploadfile] para cada archivo.

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

Para obtener más información, consulte Comandos de registro y UploadFile: cargar un archivo que se puede descargar con los registros de tareas.

Cargar un registro como artefacto de canalización

Para cargar un registro personalizado como artefacto de canalización, utilice la tarea PublishPipelineArtifact@1. PublishPipelineArtifact@1 puede cargar un único archivo o los archivos de una ruta de directorio, y resulta útil si tiene que cargar muchos archivos de registro personalizados.

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

Para obtener más información, consulte Publicar artefactos de canalización.

Capturar detalles de utilización de recursos

Cuando utilice Azure DevOps Services, puede ver la utilización de recursos en los registros, incluido el uso del disco, la memoria y la CPU, activando los registros detallados. Cuando finalice la canalización, busque en los registros las entradas de Agent environment resources en cada paso.

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%

Si utiliza Azure DevOps Server, o si desea recopilar métricas adicionales, puede utilizar PowerShell para capturar la utilización de recursos y cargarla en los registros de canalización. Cuando finalice la ejecución de la canalización, puede descargar los registros de la canalización y ver los datos capturados. Si el paso Upload resource usage from pipeline run es el sexto paso en el trabajo, el nombre de archivo en los registros será 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()

Capturar un volcado de memoria de un proceso dotnet utilizando ProcDump

Si la ejecución de una prueba falla, el servicio de atención al cliente puede pedirle que capture un volcado de memoria del proceso dotnet después de la ejecución fallida de la prueba. Añada la siguiente tarea después de la tarea de prueba de Visual Studio con condition: always(). Cuando finalice la ejecución de la canalización, podrá descargar los registros de la canalización, incluido el volcado de memoria.

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

Capturar seguimientos de ETW para un agente alojado

Si el servicio de atención al cliente le pide que cree un seguimiento de la compilación de Visual Studio, añada las siguientes tareas a su canalización antes y después del paso de compilación de Visual Studio. Después de ejecutar la canalización, puede descargar el artefacto PerfViewLog de los detalles de ejecución de la canalización y enviar ese archivo al servicio de atención al cliente.

Agente de Windows
Agente 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'

Capturar seguimientos perfview para la compilación de Visual Studio

Si el servicio de atención al cliente le pide que cree un seguimiento perfview de la compilación de Visual Studio, añada las siguientes tareas a su canalización antes y después del paso de compilación de Visual Studio.

Después de ejecutar la canalización, puede descargar el artefacto PerfViewLog de los detalles de ejecución de la canalización y enviar ese archivo al servicio de atención al cliente.

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