Simple Log Service：Kubernetes叢集容器日誌採集須知

功能特點

Log Service在Kubernetes容器日誌採集中提供以下核心能力：

• 多源日誌支援

  • 日誌類型：標準輸出資訊（stdout）、標準錯誤資訊（stderr）與容器文字檔日誌。

• 精細化容器過濾

  • 通過Namespace名稱、Pod名稱、容器名稱、容器Label或環境變數來指定/排除採集的容器。

• 複雜Tlog能力

  • 採集多行日誌：允許將跨越多行的日誌條目（如Java異常堆棧資訊）識別為單個完整日誌事件進行採集，避免因分行符號導致日誌被錯誤分割。

  • 日誌預先處理：例如使用過濾外掛程式在採集端過濾無效資料，使用日誌脫敏、欄位提取外掛程式避免原始日誌流出。

  • 結構化解析欄位：通過正則、JSON、分隔字元等解析外掛程式解析原始日誌後儲存。

• 智能中繼資料關聯

  • 上報容器日誌時自動關聯Meta資訊（例如容器名、鏡像、Pod、Namespace、環境變數等）。

• 可靠性保障

  • checkpoint機制通過記錄當前採集位置確保日誌完整性。

  • 容器停止時的Tlog：對不同運行時提供不同的容器停止處理策略。

使用限制

• 容器運行時：僅支援Docker與Containerd。

  Docker：

  • 需具備訪問docker.sock的許可權。

  • 目前標準輸出採集僅支援JSON類型的日誌驅動。

  • 只支援overlay、overlay2兩種儲存驅動，其他儲存驅動需將日誌所在目錄通過資料卷掛載為臨時目錄。

  Containerd：

  • 需具備訪問containerd.sock的許可權。

• 多行日誌限制：

  為保證多行組成的一條日誌不因輸出延遲而被分割成多條，採集的最後一條日誌預設都會緩衝一段時間。預設緩衝時間為3秒，可通過BeginLineTimeoutMs參數修改，但不能低於1000（毫秒），否則容易出現誤判。

• 標準輸出：

  單條日誌最大值：預設值為524288（512 KB），最大值為8388608（8 MB）。 如果您的單條日誌超過524288 Byte，可給LoongCollecor容器添加環境變數 max_read_buffer_size進行修改。

  重要

  建議不要同時開啟標準輸出和標準錯誤，可能會導致採集日誌出現混亂。

採集流程總覽

1. 登入叢集並準備日誌源：準備標準輸出日誌或文字檔日誌用於後續採集。

2. 安裝Loongcollector採集器：Log Service通過Loongcollector採集並傳輸日誌。

3. 採集配置與解析外掛程式配置 ：用於定義採集的規則。

4. 查詢與分析日誌：查詢採集到的日誌進行業務狀況的分析。

關鍵流程說明

日誌源與掛載點要求（重要）

• 對於標準輸出類型的日誌，LoongCollector會根據容器元資訊自動識別擷取檔案所在路徑。

• 對於容器文字檔類型的日誌，LoongCollector預設將宿主機根目錄掛載到自身的/logtail_host目錄下，一般來說無須再手動掛載。如果需要自訂掛載點需滿足：

  自訂掛載點要求

  記錄檔路徑：

  • 禁止使用軟連結：

    • 錯誤配置：/var/log -> /mnt/logs。

    • 正確配置：直接使用實體路徑 /mnt/logs。

  • 掛載路徑匹配規則：若業務容器的資料目錄通過資料卷（Volume）掛載， 採集路徑必須≥掛載點路徑。

    1掛載點：/var/log/service
    2✅ 有效採集路徑：/var/log/service 或 /var/log/service/subdir
    3❌ 無效採集路徑：/var/log （路徑過短）

安裝採集器

根據適用情境選擇部署模式：

部署模式：Log Service支援Daemonset與Sidecar兩種模式安裝LoongCollector。

• Daemonset 部署模式：一次配置，自動在叢集的每個Node節點上部署一個 LoongCollector，大多數情況下使用該模式。

  • 當使用Daemonset時，需要根據叢集與Log Service的關係選擇合適的部署方式。

    • 當使用ACK叢集時，ACK中已整合loongcollector-ds組件，只需在ACK控制台選擇開啟組件使用即完成安裝，此方式預設與ACK叢集所屬阿里雲帳號綁定，即後續日誌會儲存在該阿里雲帳號的Log Service中。具體操作可參考安裝配置。

    • 當使用ACK叢集，但因為組織架構、許可權隔離或統一監控等原因，需將該ACK的日誌資料擷取到另一個獨立的阿里雲帳號的Log ServiceProject時，需要手動安裝LoongCollector組件，並為其配置目標帳號的主帳號ID或訪問憑證（AccessKey）來實.現關聯。具體操作可參考安裝配置。

    • 當使用自建叢集時，需要手動安裝LoongCollector組件，為其配置目標帳號的主帳號ID或訪問憑證（AccessKey）來實現關聯。具體操作可參考安裝配置。

    安裝LoongCollector是採集日誌的前提，您也可以直接參考通過Kubernetes CRD採集叢集容器日誌（標準輸出/檔案）進行完整的採集流程操作，其中包含了安裝LoongCollector的步驟。

• Sidecar部署模式：每個 Pod 中伴隨業務容器注入一個 LoongCollector Sidecar容器，部署營運較複雜。當需要Serverless 容器日誌採集、單節點 Pod 資料量遠超Daemonset採集上限、K8s + 安全容器運行時的日誌採集時，使用採集Kubernetes Pod文本日誌（Sidecar模式）。

採集規則配置

Log Service提供了如下兩種方式來定義採集配置規則：

核心概念

• Kubernetes：Kubernetes (K8s) 是一個開源的容器編排平台，用於自動化部署、擴充和管理容器化應用程式，是現代化雲原生應用開發和營運的核心基礎設施。

• 標準輸出、標準錯誤與文字檔日誌：標準輸出（stdout）是程式正常運行時列印的資訊（例如：業務日誌、操作記錄），預設輸出到終端並被容器引擎捕獲儲存；標準錯誤（stderr）是程式錯誤或警告資訊（例如：異常堆棧、啟動失敗原因），同樣被容器引擎捕獲儲存，可與stdout混合輸出；文字檔日誌是應用主動寫入檔案的日誌（例如：Nginx的access.log、自訂記錄檔），直接寫入容器內部檔案系統，隨容器銷毀而銷毀，可通過Volumn持久化。

• checkpoint機制：checkpoint用於記錄Log Service當前採集到檔案的具體位置，預設在/tmp/logtail_checkpoint中儲存。用於保障LoongCollector重啟或節點宕機等異常情況下日誌採集的可靠性。

• LoongCollector（Logtail）：阿里雲自研的高效能日誌採集器，支援DaemonSet和Sidecar的Kubernetes部署模式。其中LoongCollector是Logtail的升級版，相容Logtail的所有功能。

• Kubernetes CRD：CRD是Kubernetes 的一種機制，允許使用者自訂資源並建立執行個體進行配置，Log Service提供的自訂資源類型為AliyunPipelineConfig。

• 採集配置：用於定義採集日誌的類型，採集路徑、有效日誌的篩選，日誌內容的解析、儲存到Log Service的位置等規則，詳情可參考什麼是採集配置。

• 解析外掛程式：在採集配置的處理外掛程式配置中使用，Log Service提供了眾多用於結構化、切分、過濾、脫敏日誌內容的處理單元，支援正則、分隔字元、JSON、多行等多種處理模式。

日誌採集原理

1. 使用者通過 kubectl 建立自訂資源 (CR)，定義採集規則。

2. loongcollector-operator 持續監聽叢集中CR資源的變化。

3. 當檢測到 CR 變化時，operator 將其轉換為具體配置，並提交到Log Service。

4. loongcollector定時向Log Service發送心跳擷取配置更新，拉取最新的採集配置並熱載入。

5. loongcollector-ds 根據最新配置採集日誌，並通過配置的存取點發送到 SLS。

DaemonSet模式原理

在叢集的每個Node節點上部署一個 LoongCollector，負責採集該節點上所有容器的日誌；特點：營運簡單、資源佔用少、配置方式靈活；但是隔離性較弱。

Sidecar模式原理

每個 Pod 中伴隨業務容器注入一個 LoongCollector Sidecar容器，並將業務容器的日誌目錄通過K8s的Volume機制（如emptyDir、hostPath、PVC等）掛載為共用卷。這樣，記錄檔會同時出現在業務容器和Sidecar容器的掛載路徑下，LoongCollector就能直接讀取這些記錄檔；特點：多租戶隔離性好、效能好；但資源佔用較多，配置與維護較複雜。

容器發現原理

LoongCollector容器若要採集其他容器的日誌，必鬚髮現和確定哪些容器正在運行，這個過程稱為容器發現。

• 在容器發現階段，LoongCollector容器不與Kubernetes叢集的kube-apiserver進行通訊，而是直接和節點上的容器運行時守護進程（Container Runtime Daemon）進行通訊，從而擷取當前節點上的所有容器資訊，避免容器發現對叢集kube-apiserver產生壓力。

• LoongCollector支援通過訪問位於宿主機上容器運行時（Docker Engine/ContainerD）的 sock 擷取容器的上下文資訊，支援Namespace名稱、Pod名稱、Pod標籤、容器環境變數等條件指定或排除採集相應容器的日誌。

標準輸出採集

根據容器元資訊自動識別不同容器運行時（如Docker、Containerd）的API或日誌驅動，不需要額外手動設定，直接讀取所有容器的標準輸出資料流，無需訪問容器內的檔案系統。

容器文字檔日誌採集

• K8s容器間檔案系統隔離，採集器無法直接存取其他容器的檔案。但是，容器內的檔案系統都是由宿主機的檔案系統掛載形成，通過將宿主機根目錄所在的檔案系統掛載到Loongcollector容器，就可以訪問宿主機上的任意檔案，從而間接採集業務容器檔案系統的檔案。

• LoongCollector預設將宿主機根目錄所在的檔案系統掛載到自身的/logtail_host目錄下，一般來說無須再手動掛載，例如記錄檔在當前容器內的路徑是/log/app.log，假設在宿主機上映射路徑是/var/lib/docker/containers/<container-id>/log/app.log。則LoongCollector實際採集的檔案路徑為/logtail_host/var/lib/docker/containers/<container-id>/log/app.log。

多行日誌識別原理

通過自訂的行首Regex對每一行日誌進行正則匹配。

• 匹配成功：將該行作為新日誌的起始行，並開始構建一條新日誌。

• 匹配失敗：將該行追加到當前日誌的末尾。

當再次匹配到滿足行首Regex的行時，當前日誌構建完成，並開始下一條日誌的構建。

容器停止時的Tlog

Pod 刪除後，已採集到 SLS LogStore 的日誌不受影響，日誌按LogStore的資料儲存時間保留，在保留期內可正常查詢。資料儲存時間可在 SLS 控制台修改。

Pod 刪除後，基於容器標籤或命名空間的採集配置自動應用於同標籤的建立 Pod。當 Deployment 觸發變換導致舊 Pod 刪除、新 Pod 建立時，Log Service自動採集新 Pod 的日誌，無需重新設定採集規則。

容器元資訊擷取原理

在容器元資訊擷取方面，LoongCollector 基於標準 CRI API 直接與容器運行時進行互動，實現 K8s 下各類別中繼資料資訊擷取，從而無侵入地實現採集時的 K8s 元資訊 AutoTagging 能力。這種直接與運行時互動的機制，不僅增強了資料擷取的即時性，還提高了對於容器狀態的管控能力。

• Docker：利用 Docker Client 與 Docker Daemon 進行通訊，直接擷取容器的元資訊。通過這種方式，可以實現對容器的深入監控和管理。主要使用到的介面包括：

  • ContainerList：擷取當前運行容器的列表，快速瞭解當前節點上有哪些容器在運行。

  • ContainerInspect：提供每個容器的詳細資料，包括配置、狀態等關鍵資訊。

  • Events：即時監聽容器變化事件，允許動態跟蹤容器的生命週期，及時更新相關處理邏輯。

  通過 Docker Client 擷取容器元資訊時，有幾項資訊尤為重要：

  • LogPath：這是容器標準輸出記錄檔在宿主機上的存放路徑，方便使用者進行日誌收集和分析。

  • GraphDriver.Data：提供容器 rootfs 在節點宿主機上的路徑，關鍵於瞭解容器檔案系統的儲存方式，有助於進行故障診斷和效能最佳化。

• Containerd：通過 CRI（Container Runtime Interface），LoongCollector 充分支援在 containerd 和 cri-o 運行時環境下的多種應用情境。無論底層使用的是 runc 還是 Kata Containers，都能夠高效地採集和擷取容器的元資訊。這意味著，無論容器運行在何種環境下，都能保證準確、統一的日誌資料擷取，協助使用者即時監控和分析日誌資料。

  • CRI 所提供的容器元資訊中，僅包含了容器標準輸出記錄檔在節點宿主機上的路徑，而容器的 Rootfs 路徑卻無法直接擷取。為瞭解決這一問題，採取了以下方案：

    • 檔案路徑搜尋：通過對宿主機的檔案系統進行搜尋，定位到容器的 Rootfs 路徑。這種方法包括遍曆宿主機上的檔案目錄，利用容器的唯一識別碼（如容器 ID）進行關聯尋找，從而實現對容器檔案系統的檢索和擷取。這種動態搜尋機制，能夠在一定程度上克服路徑資訊缺失帶來的困擾，為後續的日誌收集和監控提供支援。

    • 繞過 CRI直接與 containerd 進行互動：選擇與 containerd 進行低層次的直接通訊，以擷取更全面和準確的容器資訊。通過這種方式，LoongCollector能夠繞過 CRI 的限制，獲得容器的 Rootfs 路徑和其他重要中繼資料。