跳至內容

Elixir 建置洞察

Tuist 的 Hex 套件可將建置分析資料傳送至 Tuist。建置時間、檔案間的相依圖,以及兩者隨時間的演變,能讓你最佳化建置圖,並充分利用編譯環境中可用的所有核心。

必要條件

回報你的建置#

共用設定會安裝編譯整合元件。繼續使用你慣用的指令:

bash
mix compile

此整合涵蓋 mix compile 以及其他任務觸发的每次編譯,例如 mix test 或 mix phx.server。若編譯發現無需執行任何工作,則不會回報,因此儀表板只會列出實際執行的建置。

回報參與者宣告#

只有在你明確設定標籤時,Mix 建置與測試回報請求才會包含可選的 x-tuist-actor-id 標頭。將 TUIST_ACTOR_ID 設為組織範圍的標籤,或在專案的 tuist 設定中加入 actor_id: "developer-label"。解析順序優先採用環境變數,其次是執行階段的 :actor_id 選項,最後才是專案設定。預設不會傳送任何標籤,且套件不會偵測作業系統的使用者名稱。固定的專案標籤適用於所有使用該設定的使用者。空白或無效的覆寫會省略該宣告,而不會退回預設值;這不會移除基於憑證的已驗證身分。若自訂 Proxy 拒絕不熟悉的標頭,請使用 TUIST_ACTOR_ID="" 選擇退出。

識別碼必須是 1–128 位元組的非空格可列印 ASCII 字元。無效的覆寫會被省略,且不會退回預設值。已驗證的個人憑證具有優先權;其他由用戶端回報的識別碼會顯示為 未驗證,永遠不會授權存取,也不會自動連結至使用者。任何能檢視專案報告的人都能看到這些識別碼,包括專案公開時的公開檢視者,且它們會包含在資料匯出中,因此請勿納入機密資訊。舊版伺服器會忽略此可選標頭,而新版伺服器會接受不含此標頭的舊版用戶端。沒有識別碼的新版共用權杖回報會顯示 未知,而非發布組織;歷史報告則保留其先前的歸屬。建置與測試回報預設需要驗證。自行託管的安裝可以如下所述明確啟用免憑證回報。

在私有網路上進行免憑證回報#

當營運者在實例上設定 TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true 並依照 自行託管指南 所述重新啟動後,請設定你的目標位置。SDK 會在缺少憑證時自動偵測實例是否允許免憑證回報。此實例設定涵蓋所有支援的專案,且儀表板上沒有切換開關:

elixir
tuist: [
url: "https://tuist.internal.example",
project: "account/project"
]

當確實缺少憑證且偵測確認伺服器允許時,mix tuist.compile 與 mix tuist.test 會在無需登入的情況下發布結構化報告。不需要用戶端旗標或專案選擇加入。現有的憑證(包括提供的 CI OIDC 身分)會被使用或拒絕,絕不會被忽略以降級為未簽署回報。僅含空白的 TUIST_TOKEN 會導致錯誤。空的 TUIST_TOKEN 可以退回至有效的儲存憑證或提供的 OIDC,而过期的儲存憑證也可以退回至提供的 OIDC;這兩種路徑都保持驗證狀態,且絕不會啟用未簽署回報。無法使用的憑證會被保留,並在沒有驗證退回成功時失敗。在升級免憑證用戶端之前,請將每個伺服器副本升級至支援偵測的版本;不支援偵測的舊版伺服器、已停用的實例以及偵測失敗的情況仍然需要驗證。

未簽署的執行屬於遙測資料,並非受信任的不穩定性、隔離、涵蓋率或選擇性執行證據。分片規劃、建置封存以及涵蓋率/產物端點仍然需要憑證。獨立設定 TUIST_ACTOR_ID="" 以省略已設定的參與者宣告;已驗證的憑證身分不受影響。

追蹤內容#

針對每次建置,套件會收集:

  • 其持續時間、是否成功,以及執行時的 Elixir、Erlang/OTP 和 Mix 環境
  • 每個警告與錯誤,及其所在的檔案與行號
  • 每個檔案的編譯時間,以及其定義的模組
  • 每個檔案所依賴的檔案,以及是在編譯時期還是僅在執行時期需要它們
  • 除了編譯檔案之外,建置還執行了哪些動作,例如類型檢查、寫入磁碟以及其他 Mix 編譯器
  • 建置期間機器的處理器、記憶體、網路和磁碟使用情況
  • 分支與提交,以及在持續整合中的提供者與執行

找出拖慢建置的因素#

在儀表板上從 Builds → Build Runs 開啟建置。建置、其診斷數量以及相依快取摘要也可透過 tuist build mix list 與 tuist build mix show、GET /api/projects/{account_handle}/{project_handle}/mix/builds,以及 list_mix_builds 和 get_mix_build MCP 工具 取得。

概覽 頁籤列出建置所編譯的檔案。你可以依模組群組、搜尋它們,並依以下方式排序:

  • 編譯持續時間,以找出本身耗時較長的檔案。
  • 編譯時期依賴者,即必須等待此檔案編譯完成才能編譯的檔案數量。耗時較長且擁有許多依賴者的檔案會拖慢其餘建置,且變更它會導致重新編譯所有依賴者。
  • 編譯時期相依性,即此檔案等待的檔案數量。

Phoenix 應用程式的 Mix 建置概覽

時間軸 頁籤顯示同一建置隨時間的狀況:哪些檔案平行編譯、建置在何處進行類型檢查與寫入磁碟,以及機器在每個時刻的狀態。單一長條的區段表示建置無法使用其可用的核心。

Phoenix 應用程式完整 Mix 建置的時間軸

警告 與 錯誤 頁籤列出建置的診斷資訊。

自訂中繼資料#

為 Mix 建置附加標籤與鍵值資料,以區分來自不同團隊、硬體或工作流程的執行。兩者都會出現在每個建置的詳細頁面中。

使用環境變數設定中繼資料:

bash
export TUIST_TAGS="nightly,release"
export TUIST_VALUES="ticket=TUIST-123,runner=linux-arm64"

你也可以在 mix.exs 中設定中繼資料:

elixir
tuist: [
project: "account/project",
tags: ["nightly", "release"],
values: %{"ticket" => "TUIST-123", "runner" => "linux-arm64"}
]

兩處的標籤會合併。若兩處設定了相同的鍵,環境變數中的值優先。

標籤只能包含字母、數字、連字號與底線。一個建置最多可有 50 個標籤,每個標籤最多 50 個字元。一個建置最多可有 20 筆鍵值項目,每個鍵最多 50 個字元,每個值最多 500 個字元。這些限制與 Xcode 建置中繼資料的伺服器端限制相同。套件在傳送報告前會略過無效標籤以及過大或空白的中繼資料項目,因此無效設定不會阻止其餘建置洞察報告被儲存。對於不符合標籤限制的値,請使用鍵值中繼資料。

自訂中繼資料會附加至建置,而非測試執行。

專案成員可在儀表板上查看自訂中繼資料。請勿將其用於憑證、存取權杖或其他敏感資料。Tuist 會保留 Mix 建置資料(包含此中繼資料)90 天。詳情請參閱 資料保留政策。

疑難排解#

回報絕不會改變你的建置結果:若無法傳送報告,建置仍會照常完成,且不會印出任何訊息。若要查看報告未傳送的原因,請設定 TUIST_DEBUG=1:

bash
TUIST_DEBUG=1 mix compile --force