前言

對於開發人員來說，Azure DevOps 引入最大影響在於 Pipeline 部分。過去擔任現場工程師時，無論公家機關、金融證卷、醫療機構或博弈娛樂，經常遇到開發者反應程式碼在我的電腦是可以成功執行的，但在 Pipeline 卻建置失敗的情況，影響到他們的生產力甚至因此無法部署。理論上，Pipeline 每個建置與測試步驟應該與開發者端所執行流程是相同的，在相同的程式碼情況下，不應該發生此問題。但實務上，下列情境皆可能讓 Pipeline 發生錯誤：

1. 程式碼不一致或 Pipeline 修改
2. Pipeline 內 Task 升級
3. 因為套件相依不同 (經常遇到缺少 package-lock.json 發生問題)
4. Image 名稱相同，但內容與原先不一致
5. 外部引用公開網站 Library 因官方某些因素修改，在內部沒有暫存情況下導致建置錯誤
6. 代理程式執行環境設定混亂
   ...

看完上述可能的情境，沒有相關經驗的的 IT 人員可能感覺無所適從，在發現事件發生的根本原因前已經耗盡心力。今天這篇文章將簡單說明一些基本診斷技巧，無論你是開發、維運或平台管理人員，在錯誤發生時快速找到可能的根本原因，將影響降至最低。

介紹與說明

在本地端重現問題

正常情況下，應優先在本地開發環境，盡可能以 Pipeline 上執行方式嘗試重現問題。舉個例子，如果 Pipeline是使用 .NET CLI(.NET Core CLI)或 Maven 指令執行 Restore, Build 與 Test，你應該在本地開發環境使用相同 .NET CLI 或 Maven 指令進行測試，而非 IDE (Visual Studio 或 Eclipse)。這也是建立 Pipeline 過程中一個思考方式，盡可能簡單並貼近開發環境執行方式。

在過去沒有這麼多方便 Task 可以使用時，建置 Pipeline 需要理解程式碼建置與編譯流程，完整地將開發者執行的流程重現在 Pipeline 上。理所當然，這包含測試與安全掃描。當廠商提供越來越多方便的 Task 可以使用時，也提升在 Pipeline 找根本原因的難度。

1. 本地端能重現的問題，其修復成本較低
2. 不是任何 Pipeline 皆可以在本地端重現問題。盡可能執行最小限度的 Task，也有快速釐清問題的效果

檢視日誌(Pipeline Log)或下載原始(Raw Log)進行詳細比對

詳細閱讀錯誤訊息是一件非常重要的事情，儘管它不容易被發現或難以正確的理解。在 Pipeline 執行過程中皆有日誌產生，無論安全掃描、建置、測試或發布成品，會列出基本的資訊提供參考。

在某些情況下，綠色通過不代表成功執行，謹慎檢視日誌資訊才是正確的

啟用系統診斷(Enable system diagnostics)

若檢視既有 Pipeline 日誌仍無法看出端倪，您可以啟用 Azure Pipeline 系統診斷以檢視更多詳細資訊，透過變數內容與額外資訊，可以進步發現錯誤根本原因。 (不僅止於 Azure DevOps，許多相似的產品也有提供相同的功能，如: GitHub Action 與 GitLab)

啟用方式相當簡單，第一種方式，您可以在 Azure DevOps Portal 上執行 Pipeline 時勾選 Enable system diagnostics，執行過程中即會顯示系統診斷資訊

第二種方式則是在 Pipeline YAML 檔案內加入變數 system.debug: 'true'

variables:
  system.debug: 'true'

建議不一定要每次皆開啟系統診斷，有時過多資訊可能會造成日誌難以閱讀與比段，執行效能也會稍微受影響

啟用 Self-hosted agent 網路診斷

在企業內部使用 Self-hosted agent 最麻煩的即是網路問題 (如: Proxy 或 Firewall 設定)，當想取得代理程式執行時網路診斷資訊，你可以在 Pipeline YAML 檔案內加入變數 Agent.Diagnostic: 'true'

variables:
  Agent.Diagnostic: 'true'

此 Agent.Diagnostic 變數適用于 Agent v2.200.0 和更新版本。

與前次成功執行的 Pipeline，比對提交內容

比較有經驗的 IT 人員會先比對前一次執行成功的提交資訊與這一次有什麼不同來發現問題。如下圖所示，你可以在過往歷史紀錄找到前一次成功紀錄，點選 Commit 來比對修改了那些內容可能導致 Pipeline 錯誤發生。

另一種測試方式為選擇前次成功執行的 Commit 或 Tag，以釐清是程式修改還是 Pipeline 設定問題，藉此縮小範圍

啟用內建 HTTP 追蹤

若您的 Pipeline 有 HTTP 請求相關工作，可以考慮啟用內建的 HTTP 追蹤。在 Pipeline YAML 檔案內加入變數 VSTS_AGENT_HTTPTRACE=true 即可。

Windows:
    set VSTS_AGENT_HTTPTRACE=true

macOS/Linux:
    export VSTS_AGENT_HTTPTRACE=true

HTTP 追蹤 可能包含敏感資訊 (如:密碼)，請勿隨意公開

其他最佳實踐

在故障期間，診斷與追蹤設定可以讓平台管理者取得更多資訊，提高找到根本原因的速度，降低對於產品的影響。但多餘的資訊可能讓 Agent (代理程式)增加負擔，若問題排除後忘記關閉，可能因為過多的資訊造成使者困擾。請盡可能依據情況啟用適合的的診斷，並在問題解決後記得關閉相關設定。