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的位置等規則，詳情可參考什麼是LoongCollector採集配置。

• 解析外掛程式：在採集配置的處理外掛程式配置中使用，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

容器元資訊擷取原理

在容器元資訊擷取方面，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 路徑和其他重要中繼資料。