Kubernetes 1.29 的情境記錄：更佳的疑難排解與強化的記錄功能

作者：Mengjiao Liu (DaoCloud), Patrick Ohly (Intel) |

我們謹代表 結構化日誌工作組 和 SIG Instrumentation，在此欣然宣布 Kubernetes v1.24 中引入的關聯式日誌功能已成功遷移至兩個元件 (kube-scheduler 和 kube-controller-manager) 以及部分目錄。此功能旨在提供更有用的日誌，以便更佳地疑難排解 Kubernetes 問題，並讓開發人員能夠增強 Kubernetes。

何謂關聯式日誌？

關聯式日誌 以 go-logr API 為基礎。其主要概念是，程式庫由其呼叫者傳遞記錄器執行個體，並使用該執行個體進行記錄，而非存取全域記錄器。二進位檔決定記錄實作，而非程式庫。go-logr API 圍繞結構化日誌設計，並支援將額外資訊附加至記錄器。

這啟用了更多使用案例

  • 呼叫者可以將額外資訊附加至記錄器

    • WithName 新增「logger」金鑰，其值為以點號串連的名稱
    • WithValues 新增金鑰/值組

    當將此擴充記錄器傳遞至函式，且函式使用它而非全域記錄器時，額外資訊接著會包含在所有日誌項目中，而無需修改產生日誌項目的程式碼。這在高度平行的應用程式中非常有用，因為在這些應用程式中，辨識特定作業的所有日誌項目可能會變得困難，因為來自不同作業的輸出會交錯。

  • 執行單元測試時，日誌輸出可以與目前測試建立關聯。接著，當測試失敗時，go test 只會顯示失敗測試的日誌輸出。該輸出預設也可以更詳細，因為它不會顯示成功測試的輸出。測試可以平行執行，而不會交錯其輸出。

關聯式日誌的設計決策之一是允許將記錄器作為值附加至 context.Context。由於記錄器封裝了呼叫的預期記錄的所有層面，因此它是內容的一部分，而不僅僅是使用它。實際的優點是，許多 API 已經具有 ctx 參數，或可以新增一個。這提供了額外的優勢，例如能夠擺脫函式內部的 context.TODO() 呼叫。

如何使用它

關聯式日誌功能從 Kubernetes v1.24 開始為 Alpha 階段，因此需要啟用 ContextualLogging 功能閘道。如果您想在 Alpha 階段測試此功能，您需要在 kube-controller-manager 和 kube-scheduler 上啟用此功能閘道。

對於 kube-scheduler，除了啟用 ContextualLogging 功能閘道之外，還有一點需要注意，檢測也取決於日誌詳細程度。為了避免因 1.29 版新增的關聯式日誌檢測而減慢排程器的速度，仔細選擇何時新增額外資訊非常重要

  • 在 -v3 或更低版本中，每個排程週期僅使用一次 WithValues("pod")。這具有預期的效果，即週期的所有日誌訊息都包含 Pod 資訊。一旦關聯式日誌達到 GA，就可以從所有日誌呼叫中移除「pod」金鑰/值組。
  • 在 -v4 或更高版本中，會產生更豐富的日誌項目，其中 WithValues 也用於節點 (在適用的情況下)，而 WithName 用於目前作業和外掛程式。

以下範例示範了效果

I1113 08:43:37.029524 87144 default_binder.go:53] "嘗試將 Pod 繫結至節點" logger="Bind.DefaultBinder" pod="kube-system/coredns-69cbfb9798-ms4pq" node="127.0.0.1"

直接的好處是，作業和外掛程式名稱在 logger 中可見。pod 和 node 已在 kube-scheduler 程式碼中的個別日誌呼叫中記錄為參數。一旦 kube-scheduler 外部的更多套件支援關聯式日誌，它們也將在那裡可見 (例如，client-go)。一旦達到 GA，就可以簡化日誌呼叫，以避免重複這些值。

在 kube-controller-manager 中，WithName 用於將使用者可見的控制器名稱新增至日誌輸出，例如

I1113 08:43:29.284360 87141 graph_builder.go:285] "垃圾收集器監控程式未同步：沒有監控程式" logger="garbage-collector-controller"

logger=”garbage-collector-controller” 是由 kube-controller-manager 核心在例項化該控制器時新增的，並出現在其所有日誌項目中 - 至少只要它呼叫的程式碼支援關聯式日誌。需要進一步的工作來轉換 client-go 等共用套件。

效能影響

在套件中支援關聯式日誌，亦即接受來自呼叫者的記錄器，成本很低。kube-scheduler 未觀察到效能影響。如上所述，新增 WithName 和 WithValues 需要更謹慎地進行。

在 Kubernetes 1.29 中，以生產環境詳細程度 (-v3 或更低版本) 啟用關聯式日誌不會對 kube-scheduler 造成可測量的速度減慢，並且預計 kube-controller-manager 也不會。在偵錯層級，某些測試案例的 28% 速度減慢仍然合理，因為產生的日誌使偵錯更容易。如需詳細資訊，請參閱 關於將此功能升級至 Beta 版的討論。

對下游使用者的影響

日誌輸出不是 Kubernetes API 的一部分，並且在每個版本中都會定期變更，無論是因為開發人員在程式碼上工作，還是因為正在進行的轉換為結構化和關聯式日誌。

如果下游使用者對特定日誌有相依性，他們需要注意此變更如何影響他們。

延伸閱讀

參與其中

如果您有興趣參與，我們隨時歡迎新的貢獻者加入我們。關聯式日誌為您提供絕佳的機會來貢獻 Kubernetes 開發並產生有意義的影響。透過加入 結構化日誌 WG，您可以積極參與 Kubernetes 的開發並做出您的首次貢獻。這是學習和與社群互動，同時獲得寶貴經驗的好方法。

我們鼓勵您瀏覽儲存庫並熟悉目前的討論和專案。這是一個協作環境，您可以在其中交流想法、提出問題並與其他貢獻者協同工作。

如果您有任何問題或需要指導，請隨時與我們聯繫，您可以在我們的 公開 Slack 頻道 上執行此操作。如果您還不是該 Slack 工作區的成員，您可以造訪 https://slack.k8s.io/ 以取得邀請。

我們謹此感謝所有提供出色評論、分享寶貴見解並協助實作此功能的貢獻者 (依字母順序排列)