在 Kubernetes 环境中,容器日志分散、难以集中管理,导致问题排查效率低、运维成本高。通过以DaemonSet模式部署LoongCollector采集器,并在日志服务控制台创建采集配置,即可实现日志的统一收集与结构化处理,提升日志检索、问题定位及可观测性分析的效率。
适用范围
运行环境:
支持阿里云容器服务ACK(托管与专有版)和自建Kubernetes 集群。
Kubernetes为1.10.0及以上版本且支持
Mount propagation: HostToContainer
。容器运行时(仅支持Docker与Containerd)
Docker:
需具备访问docker.sock的权限。
标准输出采集仅支持JSON类型的日志驱动。
存储驱动仅支持overlay、overlay2两种存储驱动(其他类型需手动挂载日志目录)。
Containerd:需具备访问containerd.sock的权限。
资源要求:LoongCollector(Logtail)以system-cluster-critical高优先级运行,集群资源不足时请勿部署,否则可能驱逐节点上原有的Pod。
CPU:至少预留0.1 Core。
内存:采集组件至少150MB,控制器组件至少100MB。
实际使用量与采集速率、监控目录和文件数量、发送阻塞程度有关,请保证实际使用率低于限制值的80%。
权限要求:部署使用的阿里云主账号或子账号需具备
AliyunLogFullAccess
权限。如需自定义权限策略,请参考AliyunCSManagedLogRolePolicy系统策略,将其包含的权限内容复制并赋予目标 RAM 用户或角色,以实现精细化的权限配置。
采集配置创建流程
安装LoongCollector:通过DaemonSet模式部署LoongCollector,确保集群中每个节点均运行一个采集容器,统一采集该节点上所有容器的日志。
Sidecar模式请参考采集集群文本日志(Sidecar)。
创建Logstore:Logstore是日志数据的存储单元,用于存储日志。一个 Project 内可创建多个 Logstore。
创建采集配置:
本文仅介绍常用的配置参数,涵盖典型使用场景下的核心选项。如需了解完整的配置参数列表及详细说明,请参考更多信息。
极简配置(必选):构建从集群到日志服务Project的数据通道。
常用处理配置(可选):配置常用数据处理插件,对采集到的原始日志进行结构化解析(如正则解析、分隔符解析)或脱敏、过滤处理等。
本文仅介绍原生处理插件,覆盖常见日志处理场景,如需更多功能,请参考扩展处理插件。
其他高级配置(可选):实现多行文本日志的采集、日志标签富化等,满足更精细化的采集需求。
安装LoongCollector(Logtail)
LoongCollector 是阿里云日志服务(SLS)推出的新一代日志采集 Agent,是 Logtail 的升级版,二者不能同时存在,如需安装Logtail,请参考安装、运行、升级、卸载Logtail。
本文仅介绍LoongCollector的基础安装步骤,如需了解详细参数请参考LoongCollector安装(Kubernetes)。如果您已安装LoongCollector或Logtail,可跳过此步骤,直接创建存储采集日志的Logstore。
ACK集群
通过容器服务控制台安装LoongCollector,默认将日志发送到当前阿里云账号的日志服务Project中。
登录容器服务管理控制台,在左侧导航栏选择集群列表。
在集群列表页面,单击目标集群名称,进入集群详情页。
在左侧导航栏,单击组件管理。
在日志与监控页签中,找到loongcollector,单击安装。
说明对于新建集群,在组件配置页面,勾选使用日志服务,支持创建新Project或使用已有Project。
安装完成后,日志服务会自动在ACK所属地域下创建相关资源,您可登录日志服务控制台查看。
资源类型
资源名称
作用
Project
k8s-log-${cluster_id}
资源管理单元,隔离不同业务日志。
如需自行创建Project以实现更灵活的日志资源管理,请参考创建Project。
机器组
k8s-group-${cluster_id}
日志采集节点集合。
Logstore
config-operation-log
重要请不要删除该Logstore。
用于存储loongcollector-operator组件的日志,其计费方式与普通Logstore相同,详见按写入数据量计费模式计费项。建议不要在此Logstore下创建采集配置。
自建集群
连接Kubernetes集群,根据地域选择对应命令,下载LoongCollector及其依赖组件:
中国地域:
wget https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongcollector/k8s-custom-pkg/3.0.12/loongcollector-custom-k8s-package.tgz; tar xvf loongcollector-custom-k8s-package.tgz; chmod 744 ./loongcollector-custom-k8s-package/k8s-custom-install.sh
海外地域:
wget https://aliyun-observability-release-ap-southeast-1.oss-ap-southeast-1.aliyuncs.com/loongcollector/k8s-custom-pkg/3.0.12/loongcollector-custom-k8s-package.tgz; tar xvf loongcollector-custom-k8s-package.tgz; chmod 744 ./loongcollector-custom-k8s-package/k8s-custom-install.sh
进入
loongcollector-custom-k8s-package
目录,修改配置文件./loongcollector/values.yaml
。# ===================== 必需要补充的内容 ===================== # 本集群要采集的Project名,例如 k8s-log-custom-sd89ehdq projectName: "" # Project所属地域,例如上海:cn-shanghai region: "" # Project所属主账号uid,请用引号包围,例如"123456789" aliUid: "" # 使用网络,可选参数:公网Internet,内网Intranet,默认使用公网 net: Internet # 主账号或者子账号的AK,SK,需具备AliyunLogFullAccess系统策略权限 accessKeyID: "" accessKeySecret: "" # 自定义集群ID,命名只支持大小写,数字,短划线(-)。 clusterID: ""
在
loongcollector-custom-k8s-package
目录,执行如下命令,安装LoongCollector及其他依赖组件:bash k8s-custom-install.sh install
安装完成后,查看组件运行状态。
若Pod未成功启动,请确认values.yaml配置是否正确,相关镜像拉取是否成功。
# 检查Pod状态 kubectl get po -n kube-system | grep loongcollector-ds
同时,日志服务会自动创建如下资源,可登录日志服务控制台查看。
资源类型
资源名称
作用
Project
values.yaml文件中自定义的
projectName
的值资源管理单元,隔离不同业务日志。
如需自行创建Project以实现更灵活的日志资源管理,请参考创建Project。
机器组
k8s-group-${cluster_id}
日志采集节点集合。
Logstore
config-operation-log
重要请不要删除该Logstore。
用于存储loongcollector-operator组件的日志,其收费标准与普通Logstore完全相同,具体请参见按写入数据量计费模式计费项。建议不要在此Logstore下创建采集配置。
创建Logstore
若您已提前创建好Logstore,可直接跳过此步骤,进行采集配置。
SLS 支持按写入数据量和按使用功能两种计费模式,您可在创建Logstore时根据实际使用场景选择合适的计费模式。
登录日志服务控制台,单击目标Project名称。
在左侧导航栏,选择
,单击+。
在创建Logstore页面,完成以下核心配置:
Logstore名称:设置一个在Project内唯一的名称。该名称创建后不可修改。
Logstore类型:根据规格对比选择标准型或查询型。
计费模式:
按使用功能计费:按存储、索引、读写次数等各项资源独立计费。适合小规模或功能使用不确定的场景。
按写入数据量计费:仅按原始写入数据量计费,并提供30天的免费存储周期及免费的数据加工、投递等功能。成本模型简单,适合存储周期接近30天或数据处理链路复杂的场景。
数据保存时间:设置日志的保留天数,取值范围为1~3650天(3650天表示永久保存)。默认为30天。
其他配置保持默认,单击确定。如需了解其他配置信息,请参考管理Logstore。
极简配置
在完成 LoongCollector 安装并创建Logstore后,即可开始创建采集配置。本节介绍两种极简采集场景——容器标准输出和集群文本日志,仅将原始日志上传至 Logstore,不涉及任何解析或处理,适用于快速建立数据通道。
在日志库(Logstore)
|
采集容器标准输出(Stdout)
| 原始日志:
|
采集原始标准输出(Stdout):
|
采集集群文本日志
| 原始日志:
|
原始日志整行存储至content:
|
常用处理配置
在完成极简配置后,您可以通过添加处理插件,对原始日志进行结构化解析或脱敏、过滤处理。
此处仅介绍原生处理插件,覆盖常见日志处理场景,如需更多功能,请参考扩展处理插件。
对于Logtail 2.0及以上版本以及LoongCollector组件,推荐遵循以下插件组合规则:
优先使用原生插件。
当原生插件无法满足需求时,可在原生插件后配置扩展插件。
原生插件只能在扩展插件之前使用。
您可以在新建/更新采集配置时添加处理插件:
更新采集配置:
在左侧导航栏,选择
日志库,找到目标Logstore。
单击其名称前的
展开Logstore。
单击Logtail配置,在配置列表中,找到目标Logtail配置,单击操作列的管理Logtail配置。
在Logtail配置页面,单击编辑,下滑至
区域,配置解析插件。
新建采集配置:在
区域,配置解析插件。
结构化配置
正则解析
通过正则表达式提取日志字段,并将日志解析为键值对形式。
| 原始日志:
|
自定义正则解析:正则表达式
|
分隔符解析
通过分隔符将日志内容结构化,解析为多个键值对形式,支持单字符分隔符和多字符分隔符。
单击添加处理插件,选择 :
| 原始日志:
|
按指定字符
|
标准JSON解析
将Object类型的JSON日志结构化,解析为键值对形式。
单击添加处理插件,选择 :
| 原始日志:
|
标准JSON键值自动提取:
|
嵌套JSON解析
通过指定展开深度,将嵌套的JSON日志解析为键值对形式。
单击添加处理插件,选择 :
| 原始日志:
|
展开深度:0,并使用展开深度作为前缀。
| |
展开深度:1,并使用展开深度作为前缀。
|
JSON数组解析
使用json_extract
函数,从JSON数组中提取JSON对象。
将处理模式切换为SPL:
| 原始日志:
|
提取JSON数组结构:
|
Nginx日志解析
根据log_format中的定义将日志内容结构化,解析为多个键值对形式。如默认内容不符合您的需求,可使用自定义格式。
单击添加处理插件,选择 :
| 原始日志:
|
根据
|
Apache日志解析
根据Apache日志配置文件中的定义将日志内容结构化,解析为多个键值对形式。
单击添加处理插件,选择 :
| 原始日志:
|
Apache通用日志格式
|
数据脱敏
对日志中的敏感数据进行脱敏处理。
在处理配置区域,单击添加处理插件,选择 : | 原始日志:
|
脱敏结果:
|
内容过滤
基于正则表达式匹配日志字段值,仅采集符合白名单条件的日志。
在处理配置区域,单击添加处理插件,选择 :
| 原始日志:
|
过滤日志:设置字段名为
|
时间解析
对日志中的时间字段进行解析,并将解析结果设置为日志的__time__
字段。
在处理配置区域,单击添加处理插件,选择 :
| 原始日志:
|
时间解析: |
其他高级配置
在完成极简配置或常用处理配置后,您可以参考下述操作采集多行日志、配置日志主题类型等,以满足更精细化的日志采集需求。
无论是创建采集配置还是更新采集配置,都需要在
页面完成。以下为如何修改已有配置的操作流程:在左侧导航选择
日志库,找到目标Logstore。
单击其名称前的
展开Logstore。
单击Logtail配置,在配置列表中,找到目标Logtail配置,单击操作列的管理Logtail配置。
在Logtail配置页面,单击编辑。
功能 | 用途 |
多行日志采集 | 处理 Java 堆栈等跨行日志 |
容器过滤 | 按容器名、标签、环境变量筛选 |
黑名单过滤 | 忽略敏感或无关日志文件 |
日志标签富化 | 添加环境变量、容器信息作为元字段 |
传输压缩 | 启用 |
多行日志采集
默认情况下,日志服务以单行模式工作,会将每一行文本都视为一条独立的日志。这会导致包含堆栈跟踪、JSON 等内容的多行日志被错误地拆分,从而丢失上下文。
针对上述问题,可以开启多行模式,定义一个行首正则表达式,让日志服务能够准确识别一条完整日志的起始行,从而将多行内容合并为一条日志。
处理配置:
| 原始日志:
|
单行模式:每行作为独立日志,堆栈信息被拆散,丢失上下文。 | |
多行模式:通过行首正则识别完整日志,保留完整语义结构。
|
配置日志主题类型
:选择Topic生成方式。
机器组Topic:日志服务支持将一个采集配置应用到多个机器组。LoongCollector上报数据时,会将服务器所在机器组的Topic作为日志主题上传至Logstore,您可以根据Topic区分来自不同机器组的日志。
文件路径提取:若不同的用户或应用将日志写入不同的顶级目录,但下级路径和文件名相同,导致无法从文件名区分日志来源。此时您可以配置文件路径提取,通过正则表达式来匹配完整的文件路径,并将匹配结果(用户名或应用名)作为日志主题(Topic)上传至Logstore。
说明文件路径的正则表达式中,需要对正斜线(/)进行转义。
通过文件路径正则提取
场景描述:不同用户将日志记录在不同目录下,但是日志文件名称相同,目录路径如下所示。
/data/logs ├── userA │ └── serviceA │ └── service.log ├── userB │ └── serviceA │ └── service.log └── userC └── serviceA └── service.log
如果在Logtail配置中仅配置文件路径为
/data/logs
且文件名称为service.log
,LoongCollector(Logtail)会将三个service.log
文件中的内容采集至同一个Logstore中,因此无法区分日志具体由哪个用户产生。此时您可以使用正则表达式提取文件路径中的值,生成不同的日志主题。正则表达式
提取结果
\/data\/logs\/(.*)\/serviceA\/.*
__topic__: userA __topic__: userB __topic__: userC
通过多捕获组提取
场景描述:如果单个日志主题不足以区分日志的来源,可以在日志文件路径中配置多个正则捕获组来提取关键信息。其中捕获组包括命名捕获组(?P<name>)和非命名捕获组两类。
命名捕获组:生成的tag字段为
__tag__:{name}
;非命名捕获组:生成的tag字段为
__tag__:__topic_{i}__
,其中{i}
为捕获组的序号。
说明当正则表达式中存在多个捕获组时,不会生成
__topic__
字段。例如,文件路径为
/data/logs/userA/serviceA/service.log
,可通过以下方式提取文件路径中的多个值:示例
正则表达式
提取结果
使用非命名捕获组进行正则提取。
\/data\/logs\/(.*?)\/(.*?)\/service.log
__tag__:__topic_1__: userA __tag__:__topic_2__: serviceA
使用命名捕获组进行正则提取。
\/data\/logs\/(?P<user>.*?)\/(?P<service>.*?)\/service.log
__tag__:user: userA __tag__:service: serviceA
验证:配置完成后,可以根据日志主题查询日志。
在日志查询分析页面,输入对应生成的日志主题,例如
__topic__: userA
、__tag__:__topic_1__: userA
查询相应主题的日志。自定义:输入
customized:// + 自定义主题名
,使用自定义的静态日志主题。
容器过滤与黑名单
容器过滤
输入配置:
开启容器过滤,单击添加,选择过滤方式并配置,多个条件之间为“且”的关系。
环境变量黑/白名单:指定待采集容器的环境变量条件。
K8s Pod标签黑/白名单:指定待采集容器所在 pod 的标签条件。
K8s Pod 名称正则匹配:通过Pod名称指定待采集的容器
K8s Namespace 正则匹配:通过Namespace名称指定待采集的容器。
K8s 容器名称正则匹配:通过容器名称指定待采集的容器。
容器label黑/白名单:采集容器标签符合条件的容器,docker场景使用,K8s场景不推荐使用。
黑名单
:开启采集黑名单,单击添加,配置黑名单。
支持完整匹配和通配符匹配目录和文件名,通配符只支持星号(*)和半角问号(?)。
文件路径黑名单:需要忽略的文件路径,示例:
/home/admin/private*.log
:在采集时忽略/home/admin/
目录下所有以private开头,以.log结尾的文件。/home/admin/private*/*_inner.log
:在采集时忽略/home/admin/
目录下以private开头的目录内,以_inner.log结尾的文件。
文件黑名单:配置采集时需要忽略的文件名,示例:
app_inner.log
:在采集时忽略所有名为app_inner.log
的文件。
目录黑名单:目录路径不能以正斜线(/)结尾,示例:
/home/admin/dir1/
:目录黑名单不会生效。/home/admin/dir*
:在采集时忽略/home/admin/
目录下所有以dir开头的子目录下的文件。/home/admin/*/dir
:在采集时忽略/home/admin/
目录下二级目录名为dir的子目录下的所有文件。例如/home/admin/a/dir
目录下的文件被忽略,/home/admin/a/b/dir
目录下的文件被采集。
日志标签富化
:
开启日志标签富化,单击添加:
环境变量相关:配置环境变量名和tag名,环境变量值将存放在tag名中。
环境变量名:指定需要提取的环境变量名称。
tag名:环境变量标签名称
Pod标签相关:配置Pod标签名和tag名,Pod标签值将存放在tag名中。
Pod标签名:需要提取的 Kubernetes Pod 标签名称。
tag名:标签名称。
日志传输压缩
:
仅Logtail 1.3.4及以上的版本支持zstd压缩。
lz4:压缩速度快,压缩率较低。
zstd:压缩率高,速度略低,内存占用高。
后续步骤
日志查询与分析:可以使用内置的通过AI智能生成查询与分析语句(Copilot),自动生成查询分析语句。采集的每条容器文本日志中默认包含以下字段信息:
字段名称
说明
__tag__:__hostname__
容器宿主机的名称。
__tag__:__path__
容器内日志文件的路径。
__tag__:_container_ip_
容器的IP地址。
__tag__:_image_name_
容器使用的镜像名称。
__tag__:_pod_name_
Pod的名称。
__tag__:_namespace_
Pod所属的命名空间。
__tag__:_pod_uid_
Pod的唯一标识符(UID)。
数据可视化:借助可视化仪表盘监控关键指标趋势。
数据异常自动预警:设置告警策略,实时感知系统的异常情况。
容器日志采集无数据排查思路
检查是否有增量日志:配置LoongCollector(Logtail)采集后,如果待采集的日志文件没有新增日志,则LoongCollector(Logtail)不会采集该文件。
常见问题
如何将ACK集群日志传输到另一个阿里云账号的Project?
通过在ACK集群中手动安装日志服务 LoongCollector(Logtail) 组件,并为其配置目标账号的主账号ID或访问凭证(AccessKey),即可实现将容器日志发送到另一个阿里云账号的日志服务Project中。
场景描述:当因为组织架构、权限隔离或统一监控等原因,需要将某个ACK集群的日志数据采集到另一个独立的阿里云账号的日志服务Project时,可通过手动安装 LoongCollector(Logtail)进行跨账号配置。
操作步骤:此处以手动安装LoongCollector为例,如需了解如何安装Logtail,请参考Logtail安装与配置。
连接Kubernetes集群,根据地域选择对应命令,下载LoongCollector及其依赖组件:
中国地域:
wget https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongcollector/k8s-custom-pkg/3.0.12/loongcollector-custom-k8s-package.tgz; tar xvf loongcollector-custom-k8s-package.tgz; chmod 744 ./loongcollector-custom-k8s-package/k8s-custom-install.sh
海外地域:
wget https://aliyun-observability-release-ap-southeast-1.oss-ap-southeast-1.aliyuncs.com/loongcollector/k8s-custom-pkg/3.0.12/loongcollector-custom-k8s-package.tgz; tar xvf loongcollector-custom-k8s-package.tgz; chmod 744 ./loongcollector-custom-k8s-package/k8s-custom-install.sh
进入
loongcollector-custom-k8s-package
目录,修改配置文件./loongcollector/values.yaml
。# ===================== 必需要补充的内容 ===================== # 本集群要采集的Project名,例如 k8s-log-custom-sd89ehdq projectName: "" # Project所属地域,例如上海:cn-shanghai region: "" # Project所属主账号uid,请用引号包围,例如"123456789" aliUid: "" # 使用网络,可选参数:公网Internet,内网Intranet,默认使用公网 net: Internet # 主账号或者子账号的AK,SK,需具备AliyunLogFullAccess系统策略权限 accessKeyID: "" accessKeySecret: "" # 自定义集群ID,命名只支持大小写,数字,短划线(-)。 clusterID: ""
在
loongcollector-custom-k8s-package
目录,执行如下命令,安装LoongCollector及其他依赖组件:bash k8s-custom-install.sh install
安装完成后,查看组件运行状态。
若Pod未成功启动,请确认values.yaml配置是否正确,相关镜像拉取是否成功。
# 检查Pod状态 kubectl get po -n kube-system | grep loongcollector-ds
同时,日志服务会自动创建如下资源,可登录日志服务控制台查看。
资源类型
资源名称
作用
Project
values.yaml文件中自定义的
projectName
的值资源管理单元,隔离不同业务日志。
如需自行创建Project以实现更灵活的日志资源管理,请参考创建Project。
机器组
k8s-group-${cluster_id}
日志采集节点集合。
Logstore
config-operation-log
重要请不要删除该Logstore。
用于存储loongcollector-operator组件的日志,其收费标准与普通Logstore完全相同,具体请参见按写入数据量计费模式计费项。建议不要在此Logstore下创建采集配置。
如何让同一个日志文件或容器标准输出被多个采集配置同时采集?
默认情况下,日志服务为了防止数据重复,限制了每个日志源只能被一个采集配置采集:
一个 文本日志文件只能匹配一个 Logtail 采集配置;
一个 容器的标准输出(stdout) 也只能被一个标准输出采集配置采集。
登录日志服务控制台,进入目标Project。
在左侧导航选择
日志库,找到目标Logstore。
单击其名称前的
展开Logstore。
单击Logtail配置,在配置列表中,找到目标Logtail配置,单击操作列的管理Logtail配置。
在Logtail配置页面,单击编辑,下滑至输入配置区域:
采集文本文件日志:开启允许文件多次采集。
采集容器标准输出:开启允许标准输出多次采集。