本文将指导您如何使用Kubernetes自定义资源(CRD)AliyunPipelineConfig
创建日志采集配置,从而实现对集群中容器标准输出和文件日志的采集。
旧版CRD-AliyunLogConfig的配置方式已停止维护,推荐您使用新版CRD-AliyunPipelineConfig
,新旧版的能力对比请参见CRD类型。
对于通过自定义资源(CRD)创建的采集配置,其修改只能通过更新相应的自定义资源来实现,在日志服务控制台上对采集配置的修改不会同步到自定义资源中。
核心概念
在开始配置日志采集前,请先了解阿里云日志服务(SLS)的核心资源概念以及LoongCollector(Logtail)在Kubernetes环境中的运行模式。
什么是Project
Project是阿里云日志服务中的资源管理单元,用于隔离和控制不同项目或应用的日志数据。一个Project可以包含多个Logstore。您可以参考此处步骤预先创建好所需的Project。
登录日志服务控制台,单击创建Project,完成下述基础配置,其他配置保持默认即可:
所属地域:请根据日志来源等信息选择合适的阿里云地域,创建后不可修改。
Project名称:设置名称,名称在阿里云地域内全局唯一,创建后不可修改。
什么是Logstore
Logstore是日志数据的存储单元,用于存储日志。在Project内,您可以根据业务需求创建多个Logstore存储不同类型的日志,如使用两个Logstore分别存储Nginx访问日志和应用错误日志。您可以参考此处步骤预先创建一个基础Logstore。
登录日志服务控制台,在Project列表中单击管理日志资源的Project。
在日志存储 > 日志库页签中,单击+图标。
填写Logstore名称,其余配置保持默认无需修改。
LoongCollector(Logtail)运行模式
特性 | DaemonSet模式 | Sidecar模式 |
部署方式 | 每个节点部署1个采集容器 | 每个Pod部署1个采集容器 |
资源消耗 | 低(共享节点资源) | 较高(每个Pod单独占用) |
适用场景 | 节点级统一日志采集 | 特定应用独立隔离采集 |
隔离性 | 节点级共享 | Pod级独立 |
容器日志源
容器内日志包含两种日志来源:
日志来源 | 说明 |
容器标准输出与标准错误(stdout与stderr) | 容器运行过程中,程序直接打印到控制台的日志内容。 |
文本日志文件 | 采集容器内指定路径下的日志文件(支持通配符)。 |
前提条件
安装LoongCollector(Logtail)组件
若您的集群未安装LoongCollector(Logtail)组件,请参考此处步骤进行安装,本文以安装LoongCollector为例介绍。如需了解如何安装Logtail,请参考Logtail安装与配置。
LoongCollector 是阿里云日志服务(SLS)推出的新一代日志采集 Agent,是 Logtail 的升级版,二者不能同时存在。如果您当前正在使用 logtail-ds,并希望升级到 LoongCollector,请先卸载logtail-ds再安装LoongCollector。
ACK集群安装LoongCollector
此操作仅适用于阿里云容器服务专有版Kubernetes和托管版Kubernetes。
通过容器服务控制台安装LoongCollector,默认将日志发送到当前阿里云账号的日志服务中,如果您需要配置跨账号日志采集,即将当前账号下的ACK集群日志,发送至另一个阿里云账号的日志服务Project中,请参考如何将ACK集群日志传输到另一个阿里云账号的日志服务?
为已有的ACK集群安装LoongCollector组件
登录容器服务管理控制台,在左侧导航栏选择集群列表。
在集群列表页面,单击目标集群名称,然后在左侧导航栏,单击组件管理。
在日志与监控页签中,找到loongcollector,单击安装。
安装完成后,日志服务会自动在ACK所属地域下创建如下资源,您可登录日志服务控制台查看。
资源类型
资源名称
作用
Project
k8s-log-${cluster_id}
资源管理单元,隔离不同业务日志。
机器组
k8s-group-${cluster_id}
日志采集节点集合。
Logstore
config-operation-log
重要请不要删除该Logstore。
用于存储LoongCollector组件中的alibaba-log-controller日志,其收费标准与普通Logstore完全相同,具体请参见按写入数据量计费模式计费项。建议不要在此Logstore下创建采集配置。
创建存储采集日志的Logstore:登录日志服务控制台,在Project列表中单击默认创建的名为
k8s-log-${cluster_id}
的Project。在日志存储 > 日志库页签中,单击+图标。填写Logstore名称,其余配置无需修改,使用默认值即可。如需详细了解创建配置请参见管理Logstore。
新建ACK集群时安装LoongCollector组件
登录容器服务管理控制台,在左侧导航栏选择集群列表。
单击创建集群,在组件配置页面,选中使用日志服务。支持创建新Project或使用已有Project。
本文只描述日志服务相关配置,关于更多配置项说明,请参见创建ACK托管集群。
选择创建新Project,日志服务会自动创建如下资源,您可登录日志服务控制台查看。
资源类型
资源名称
作用
Project
k8s-log-${cluster_id}
资源管理单元,隔离不同业务日志。
机器组
k8s-group-${cluster_id}
日志采集节点集合。
Logstore
config-operation-log
重要请不要删除该Logstore。
用于存储LoongCollector组件中的alibaba-log-controller日志,其收费标准与普通Logstore完全相同,具体请参见按写入数据量计费模式计费项。建议不要在此Logstore下创建采集配置。
创建存储采集日志的Logstore:登录日志服务控制台,在Project列表中单击默认创建的名为
k8s-log-${cluster_id}
的Project。在日志存储 > 日志库页签中,单击+图标。填写Logstore名称,其余配置无需修改,使用默认值即可。如需详细了解创建配置请参见管理Logstore。
自建集群安装LoongCollector
安装之前,请确保您的集群满足Kubernetes 1.6及以上版本,且已安装kubectl。
登录您的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
,详细配置参数请参见LoongCollector安装与管理(Kubernetes)。# ===================== 必需要补充的内容 ===================== # 本集群要采集的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
安装完成后,查看组件状态,若未成功启动,请确认values.yaml配置是否正确,相关镜像拉取是否成功。日志服务会自动创建如下资源,您可登录日志服务控制台查看。
# 检查Pod状态 kubectl get po -n kube-system | grep loongcollector-ds
资源类型 | 资源名称 | 作用 |
Project | values.yaml文件中自定义的 | 资源管理单元,隔离不同业务日志。 |
机器组 |
| 日志采集节点集合。 |
Logstore |
重要 请不要删除该Logstore。 | 用于存储LoongCollector组件中的alibaba-log-controller日志,其收费标准与普通Logstore完全相同,具体请参见按写入数据量计费模式计费项。建议不要在此Logstore下创建采集配置。 |
创建存储日志的Logstore:登录日志服务控制台,在Project列表区域单击名为k8s-log-{ClusterID}的目标Project,在日志存储 > 日志库页签中,单击+图标。填写Logstore名称,其余配置无需修改,使用默认值即可。如需详细了解创建配置请参见管理Logstore。
通过 kubectl 连接到您的集群
如果您使用的是阿里云容器服务Kubernetes版 ACK,可以参考获取集群KubeConfig并通过kubectl工具连接集群
如果您是自建集群,请参考如下步骤安装并配置kubectl,以建立与集群的安全连接:
在需要管理集群的机器上安装kubectl。
参考配置 KubeConfig设置
kubectl
与哪个 Kubernetes 集群进行通信并修改配置信息。将集群的kubeconfig文件内容添加到默认路径 ~/.kube/config 文件中,若
.cube
不存在,请手动创建。执行kubectl命令以验证集群的连通性,以查询命名空间为例:
kubectl get namespace
采集配置创建流程
完成前提条件后,您就可以开始通过Kubernetes自定义资源创建日志采集配置了,核心流程如下:
在Kubernetes集群上,创建Logtail采集配置的YAML文件,您可以通过采集配置生成器自动生成,也可以根据如下章节手动编写采集配置。一个完整的配置通常包含以下部分:
基础配置(必选):采集配置的骨架,为必需配置,建立起从集群到日志服务的数据通道。它包含两部分:
输入
(inputs)
:定义日志的来源。输出
(flushers)
:定义日志要发送到哪里。
解析配置(可选):通过定义
processors
字段,将原始日志结构化解析为键值对数据。高级配置(可选):对日志内容进行脱敏、过滤等处理,实现更精细化的日志采集需求。
CR参数说明
apiVersion
string
(必选)固定为
telemetry.alibabacloud.com/v1alpha1
。采集文本日志模板示例
apiVersion: telemetry.alibabacloud.com/v1alpha1 kind: ClusterAliyunPipelineConfig metadata: # 设置资源名,在当前Kubernetes集群内唯一,也是创建出的Logtail采集配置名。 name: logtail-config-name spec: # 指定日志要发送到的目标Project。 project: name: <your-project-name> logstores: - name: <your-logstore-name> # 定义LoongCollector(Logtail)采集与处理配置。 config: # 日志样例(可不填写) sample: '' # --- 输入插件:定义从哪里采集日志 --- inputs: # 使用input_file插件采集容器内文本日志 - Type: input_file # ... 此处为输入插件的具体配置 ... # 容器内的文件路径 FilePaths: - /data/logs/app_1/**/test.LOG # 最大目录监控深度 MaxDirSearchDepth: 0 FileEncoding: utf8 # 启用容器发现功能。 EnableContainerDiscovery: true # --- 处理插件(可选):定义如何解析和处理日志 --- processors: [] # --- 输出插件:定义将日志发送到哪里 --- flushers: - Type: flusher_sls # 指定使用SLS输出插件 Logstore: <your-logstore-name> # ... 此处为输出插件的具体配置 ... # 需要确保 endpoint 正确 Endpoint: cn-hangzhou.log.aliyuncs.com Region: cn-hangzhou TelemetryType: logs
采集容器标准输出模板示例
apiVersion: telemetry.alibabacloud.com/v1alpha1 kind: ClusterAliyunPipelineConfig metadata: # 设置资源名,在当前Kubernetes集群内唯一,也是创建出的Logtail采集配置名。 name: new-stdio-config spec: project: name: test-not-exist logstores: - name: new-stdio-logstore # 定义LoongCollector(Logtail)采集与处理配置。 config: # --- 输入插件:定义从哪里采集日志 --- inputs: # 使用input_file插件采集容器内文本日志 - Type: input_container_stdio IgnoringStderr: false IgnoringStdout: false # --- 处理插件(可选):定义如何解析和处理日志 --- processors: [] # --- 输出插件:定义将日志发送到哪里 --- flushers: - Type: flusher_sls # 指定使用SLS输出插件 Logstore: new-stdio-logstore # 需要确保 endpoint 正确 Endpoint: cn-hangzhou.log.aliyuncs.com Region: cn-hangzhou TelemetryType: logs
kind
string
(必选)固定为
ClusterAliyunPipelineConfig
。metadata
object
(必选)资源属性名。
属性
name
string
(必选)CR的唯一标识,同时也是创建出的Logtail采集配置的名字。
该参数会作为Logtail采集配置名称使用,在所属Project内唯一,且创建成功后无法修改。需要满足以下条件:长度必须在2~128字符之间,且只能包括小写字母、数字、-和_。必须以小写字母或数字开头和结尾。
spec
object
(必选)采集配置。
属性
project
object
(必选)目标Project的信息。
project信息在CR创建后不允许更改,如需切换project请创建新的CR。
属性
name
string
(必选)目标 Project 的名称。
如果您所指定的Project不存在,日志服务会自动创建。
description
string
(可选)
目标 Project 的描述。
该参数仅在创建Project时生效。
endpoint
string
(可选)
目标Project的服务入口。默认为当前集群所在的地域,如果目标 Project 与集群不在同一地域,需要配置该参数。
该参数仅控制采集配置所在的region,logtail数据投递到该region需要另外配置logtail的config_server_address、data_server_list,参考Logtail网络类型,启动参数与配置文件。
uid
string
(可选)
目标账号的uid。默认使用当前集群所属账号。如果需要跨账号投递日志,请配置该参数,并在 alibaba-log-controller 组件的环境变量中配置
ALICLOUD_LOG_ACCOUNT_INFOS={"<uid>":{"accessKeyID":"<your_access_key_id>","accessKeySecret":"<your_access_key_secret>"}}
。该参数仅控制project所属的账号,logtail数据投递到该账号需要另外配置logtail的用户标识,参考机器组。
logstores
object
(可选)
需要创建的Logstore列表,支持创建多个Logstore。
此列表并不指定logtail采集配置的发送目标,logtail采集配置的发送目标,由config中的flusher插件决定。此列表只会按需创建Logstore,即对不存在的Logstore进行创建,对已存在的Logstore不做处理,参数也不会生效。
属性
name
string
(必选)需要创建的Logstore的名称。
queryMode
string
(可选)
目标Logstore的类型。默认值为standard,可选值:
query:查询型Logstore。
standard:标准型Logstore。
ttl
int
(可选)
目标Logstore的数据保存时间(以天为单位)。默认值为30,取值范围为1~3650,如果配置为3650,表示永久保存。
hotTtl
int
(可选)
目标Logstore的热数据存储的时间(以天为单位)。更多信息,请参见智能存储分层。默认值为0,需要小于ttl且大于等于 7。
shardCount
int
(可选)
目标Logstore的Shard数量,默认值为2,取值范围为1~100。
maxSplitShard
int
(可选)
目标 Logstore 的最大自动分裂Shard。默认值为64,取值范围为1~256。
autoSplit
bool
(可选)
默认为true
目标Logstore是否开启自动分裂Shard。
telemetryType
string
(可选)
目标 Logstore 的可观测数据类型。更多信息,请参见telemetryType。默认值为None,可选值:
None:日志类型。
Metrics:Metrics 类型。
appendMeta
bool
(可选)
默认为true
目标Logstore是否开通记录外网IP功能。
enableTracking
bool
(可选)
默认为false
目标Logstore是否启用WebTracking。
encryptConf
object
(可选)
目标Logstore的加密配置信息。更多信息,请参见通用数据结构。默认值为空。
meteringMode
string
(可选)
目标Logstore的计费模式。更多信息,请参见计费模式。默认值为空,可选值:
ChargeByFunction:按功能计费
ChargeByDataIngest:按写入量计费。
如果queryMode为query,只支持按功能计费。如果账号未开通写入量计费则无法配置为ChargeByDataIngest。
config
object
(必选)定义Logtail 采集配置详情。
属性
sample
string
(可选)
日志样例。支持多条日志,总长度不超过1500字节。
global
object
(可选)
全局配置。
属性
TopicType
string
(可选)
日志主题Topic 类型。默认为空,可选值包括:
filepath:从日志文件路径中提取信息作为 Topic。仅当输入插件为 input_file 时有效。
machine_group_topic:将应用该配置的机器组 Topic 作为 Topic。
custom:自定义 Topic 。
TopicFormat
string
(可选)
Topic 格式。当 TopicType 取值为 filepath 或 custom 时必填。
EnableTimestampNanosecond
bool
(可选)
默认值false
是否启用时间纳秒精度。
inputs
object
(必选)输入插件列表,本文以文本输入插件为例。详细信息与插件参数,请参见CreateLogtailPipelineConfig - 创建Logtail流水线配置。
目前,只允许配置 1 个输入插件。
属性
Type
string
(必选)插件类型。文本输入插件固定为input_file。
FilePaths
string
(必选)待采集的日志文件路径列表(目前仅限 1 个路径)。路径中支持使用*和**通配符,其中**通配符仅能出现一次且仅限用于文件名前。例如/var/log/**/*.log为采集/var/log目录下所有后缀为.log的文件。
MaxDirSearchDepth
uint
(可选)
文件路径FilePaths中**通配符匹配的最大目录深度。仅当路径中存在**通配符时有效,取值范围为 0~1000。默认为0,若设置为1,FilePaths为/var/log/**/*.log,则采集/var/log目录下一级目录内所有后缀为.log的文件。
ExcludeFilePaths
string
(可选)
文件路径黑名单,排除指定条件的文件。路径必须为绝对路径,支持使用*通配符。
ExcludeFiles
string
(可选)
文件名黑名单,排除指定条件的文件。支持使用*通配符。
ExcludeDirs
string
(可选)
目录黑名单,排除指定条件的文件。路径必须为绝对路径,支持使用*通配符。
FileEncoding string
(可选)
文件编码格式。默认utf8。可选值包括 utf8 和 gbk。
TailSizeKB uint
(可选)
配置首次生效时,匹配文件中内容起始采集位置距离文件结尾的大小。默认为1024。如果文件大小小于该值,则从头开始采集,取值范围为 0~10485760KB。
Multiline
object
(可选)
多行聚合选项,填写该项表示开启多行日志采集,单行日志采集请删除该配置。
属性
Mod
string
(可选)
多行聚合模式。可选值:
custom:自定义匹配模式。
JSON:多行JSON模式。
StartPattern
string
(可选)
行首正则表达式,当Mod取值为custom时必填。以正则表达式来标定每一条日志的起始行。
EnableContainerDiscovery
bool
(可选)
是否启用容器发现功能。默认值false。仅当 Logtail 以 Daemonset 模式运行,且采集文件路径为容器内路径时有效。
ContainerFilters
object
(可选)
容器过滤选项。多个选项之间为“且”的关系,仅当 EnableContainerDiscovery 取值为 true 时有效。
属性
K8sNamespaceRegex
string
(可选)
对于部署于 K8s 环境的容器,指定待采集容器所在 Pod 所属的命名空间条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。
K8sPodRegex
string
(可选)
对于部署于 K8s 环境的容器,指定待采集容器所在 Pod 的名称条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。
IncludeK8sLabel
map
(可选)
对于部署于 K8s 环境的容器,指定待采集容器所在 pod 的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为 Pod 标签名,value 为 Pod 标签值。
若map 中 value 为空,则 pod 标签为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则 pod 标签中存在以 key 为标签名且对应标签值能正则匹配 value 的 pod 会被匹配;其他情况则 pod 标签中存在以 key 为标签名且对应标签值为 value 的 pod 才会被匹配。ExcludeK8sLabel
map
(可选)
对于部署于 K8s 环境的容器,指定需要排除采集容器所在 pod 的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为 pod 标签名,value 为 pod 标签的值。
若map 中 value 为空,则 pod 标签为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则 pod 标签中存在以 key 为标签名且对应标签值能正则匹配 value 的 pod 会被匹配;其他情况则 pod 标签中存在以 key 为标签名且对应标签值为 value 的 pod 才会被匹配。K8sContainerRegex
string
(可选)
对于部署于 K8s 环境的容器,指定待采集容器的名称条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。
IncludeEnv
map
(可选)
指定待采集容器的环境变量条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为环境变量名,value 为环境变量的值。
若map 中 value 为空,则容器环境变量为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器环境变量中存在以 key 为环境变量名且对应环境变量值能正则匹配 value 的 pod 会被匹配;其他情况则容器环境变量中存在以 key 为环境变量名且对应环境变量值为 value 的 pod 才会被匹配。ExcludeEnv
map
(可选)
指定需要排除采集容器的环境变量条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为环境变量名,value 为环境变量的值。
若map 中 value 为空,则容器环境变量为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器环境变量中存在以 key 为环境变量名且对应环境变量值能正则匹配 value 的 pod 会被匹配;其他情况则容器环境变量中存在以 key 为环境变量名且对应环境变量值为 value 的 pod 才会被匹配。IncludeContainerLabel
map
(可选)
指定待采集容器的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则默认为空,表示采集所有容器。支持正则匹配。 map 中的 key 为容器标签名,value 为容器标签的值。
若map 中 value 为空,则容器标签为 key 的容器都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器标签中存在以 key 为标签名且对应标签值能正则匹配 value 的容器会被匹配;其他情况则容器标签中存在以 key 为标签名且对应标签值为 value 的容器才会被匹配。ExcludeContainerLabel
map
(可选)
指定需要排除采集容器的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则默认为空,表示采集所有容器。支持正则匹配。 map 中的 key 为容器标签名,value 为容器标签的值。
若map 中 value 为空,则容器标签为 key 的容器都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器标签中存在以 key 为标签名且对应标签值能正则匹配 value 的容器会被匹配;其他情况则容器标签中存在以 key 为标签名且对应标签值为 value 的容器才会被匹配。ExternalK8sLabelTag
map
(可选)
对于部署于 K8s 环境的容器,需要在日志中额外添加的与 Pod 标签相关的 tag。map 中的 key 为 Pod 标签名,value 为对应的 tag 名。 例如:在 map 中添加
app: k8s\_label\_app
,则若 pod 中包含app=serviceA
的标签时,会将该信息以 tag 的形式添加到日志中,即添加字段__tag__:k8s_label_app: serviceA
;若不包含app
标签,则会添加空字段__tag__:k8s_label_app:
。ExternalEnvTag
map
(可选)
对于部署于 K8s 环境的容器,需要在日志中额外添加的与容器环境变量相关的 tag。map 中的 key 为环境变量名,value 为对应的 tag 名。 例如:在 map 中添加
VERSION: env\_version
,则当容器中包含环境变量VERSION=v1.0.0
时,会将该信息以 tag 的形式添加到日志中,即添加字段__tag__:env_version: v1.0.0
;若不包含VERSION
环境变量,则会添加空字段__tag__:env_version:
。CollectingContainersMeta
bool
(可选)
是否启用容器元信息预览。默认值false。
AppendingLogPositionMeta
bool
(可选)
是否在日志中添加该条日志所属文件的元信息,包括__tag__:__inode__字段和__file_offset__字段。默认值false。
AllowingIncludedByMultiConfigs
bool
(可选)
是否允许当前配置采集其它配置已匹配的文件。默认值false。
processors
object
(可选)
处理插件列表。本文以正则解析插件为例。详细信息与插件参数,请参见CreateLogtailPipelineConfig - 创建Logtail流水线配置。
属性
Type
string
(必选)插件类型。正则解析插件固定为 processor_parse_regex_native。
SourceKey
string
(必选)源字段名。一般为content。
Regex
string
(必选)正则表达式。
Keys
[string]
(必选)提取的字段列表。
KeepingSourceWhenParseFail
bool
(可选)
当解析失败时,是否保留源字段。默认false。
KeepingSourceWhenParseSucceed
bool
(可选)
当解析成功时,是否保留源字段。默认false。
RenamedSourceKey
string
(可选)
当源字段被保留时,用于存储源字段的字段名。若不填,默认不改名。
aggregators
object
(可选)
聚合插件列表。本文以数据脱敏插件为例。详细信息与插件参数,请参见CreateLogtailPipelineConfig - 创建Logtail流水线配置。
属性
Type
string
(必选)插件类型。数据脱敏插件固定为 processor_desensitize。
SourceKey
string
(必选)日志字段名称。一般为content。
Method
string
(必选)脱敏方式。可选值:
const :将敏感内容替换为字符串。您可以通过 ReplaceString 参数指定目标字符串。
md5 :将敏感内容替换为对应的 MD5 值。
Match
string
(可选)
指定提取敏感内容的方式。可选值:
full(默认值) :全部提取,即替换目标字段值中的所有内容。
regex :使用正则表达式提取敏感内容。
ReplaceString
string
(可选)
用于替换敏感内容的字符串。 设置 Method 为 const 时必填。
RegexBegin
string
(可选)
匹配敏感内容前缀的正则表达式。 设置 Match 为 regex 时必填。
RegexContent
string
(可选)
匹配敏感内容的正则表达式。设置 Match 为 regex 时必填。
flushers
object
(必选)输出插件列表。
目前,只允许存在 1 个 flusher_sls 插件。
属性
Type
string
(必选)插件类型。固定为 flusher_sls。
Logstore
string
(必选)LogStrore 名称。用于确定采集配置的发送目标,需要确保存在。
configTags
map
(可选)
用于标记logtail采集配置的自定义标签。
machineGroups
object
(可选)
需要与logtail采集配置关联的机器组列表。安装
logtail-ds
组件时,日志服务会自动创建名为k8s-group-${your_k8s_cluster_id}
的机器组,默认值为仅包含该机器组的列表。alibaba-log-controller组件会保证logtail采集配置关联的机器组严格等于machineGroups指定的机器组,不在machineGroups中的机器组会被解除关联。
属性
name
string
(必选)需要与logtail采集配置关联的机器组名。
如果机器组不存在,alibaba-log-controller会自动创建同名的标识型机器组,标识与机器组名相同。详细信息,参见创建用户自定义标识机器组。该行为仅在创建机器组时生效。
enableUpgradeOverride
boolean
(可选)默认值为false
当集群中存在AliyunLogConfig定义的采集配置、且与当前的AliyunPipelineConfig指向同一个logtail采集配置时:
true:alibaba-log-controller会对已有的AliyunLogConfig定义的采集配置进行覆盖升级。
false:采集配置存在冲突,AliyunPipelineConfig应用失败。
指向同一个logtail采集配置的定义:目标project相同且目标Logtail采集配置名相同。
覆盖升级的定义:首先AliyunPipelineConfig生效,并更新logtail采集配置。然后删除集群内指向同一个logtail采集配置的AliyunLogConfig,覆盖更新完成。
两类CRD采集方式对比请参见CRD类型。
spec
object
(必选)采集配置。
属性
project
object
(必选)目标Project的信息。
project信息在CR创建后不允许更改,如需切换project请创建新的CR。
属性
name
string
(必选)目标 Project 的名称。
如果您所指定的Project不存在,日志服务会自动创建。
description
string
(可选)
目标 Project 的描述。
该参数仅在创建Project时生效。
endpoint
string
(可选)
目标Project的服务入口。默认为当前集群所在的地域,如果目标 Project 与集群不在同一地域,需要配置该参数。
该参数仅控制采集配置所在的region,logtail数据投递到该region需要另外配置logtail的config_server_address、data_server_list,参考Logtail网络类型,启动参数与配置文件。
uid
string
(可选)
目标账号的uid。默认使用当前集群所属账号。如果需要跨账号投递日志,请配置该参数,并在 alibaba-log-controller 组件的环境变量中配置
ALICLOUD_LOG_ACCOUNT_INFOS={"<uid>":{"accessKeyID":"<your_access_key_id>","accessKeySecret":"<your_access_key_secret>"}}
。该参数仅控制project所属的账号,logtail数据投递到该账号需要另外配置logtail的用户标识,参考机器组。
logstores
object
(可选)
需要创建的Logstore列表,支持创建多个Logstore。
此列表并不指定logtail采集配置的发送目标,logtail采集配置的发送目标,由config中的flusher插件决定。此列表只会按需创建Logstore,即对不存在的Logstore进行创建,对已存在的Logstore不做处理,参数也不会生效。
属性
name
string
(必选)需要创建的Logstore的名称。
queryMode
string
(可选)
目标Logstore的类型。默认值为standard,可选值:
query:查询型Logstore。
standard:标准型Logstore。
ttl
int
(可选)
目标Logstore的数据保存时间(以天为单位)。默认值为30,取值范围为1~3650,如果配置为3650,表示永久保存。
hotTtl
int
(可选)
目标Logstore的热数据存储的时间(以天为单位)。更多信息,请参见智能存储分层。默认值为0,需要小于ttl且大于等于 7。
shardCount
int
(可选)
目标Logstore的Shard数量,默认值为2,取值范围为1~100。
maxSplitShard
int
(可选)
目标 Logstore 的最大自动分裂Shard。默认值为64,取值范围为1~256。
autoSplit
bool
(可选)
默认为true
目标Logstore是否开启自动分裂Shard。
telemetryType
string
(可选)
目标 Logstore 的可观测数据类型。更多信息,请参见telemetryType。默认值为None,可选值:
None:日志类型。
Metrics:Metrics 类型。
appendMeta
bool
(可选)
默认为true
目标Logstore是否开通记录外网IP功能。
enableTracking
bool
(可选)
默认为false
目标Logstore是否启用WebTracking。
encryptConf
object
(可选)
目标Logstore的加密配置信息。更多信息,请参见通用数据结构。默认值为空。
meteringMode
string
(可选)
目标Logstore的计费模式。更多信息,请参见计费模式。默认值为空,可选值:
ChargeByFunction:按功能计费
ChargeByDataIngest:按写入量计费。
如果queryMode为query,只支持按功能计费。如果账号未开通写入量计费则无法配置为ChargeByDataIngest。
config
object
(必选)定义Logtail 采集配置详情。
属性
sample
string
(可选)
日志样例。支持多条日志,总长度不超过1500字节。
global
object
(可选)
全局配置。
属性
TopicType
string
(可选)
日志主题Topic 类型。默认为空,可选值包括:
filepath:从日志文件路径中提取信息作为 Topic。仅当输入插件为 input_file 时有效。
machine_group_topic:将应用该配置的机器组 Topic 作为 Topic。
custom:自定义 Topic 。
TopicFormat
string
(可选)
Topic 格式。当 TopicType 取值为 filepath 或 custom 时必填。
EnableTimestampNanosecond
bool
(可选)
默认值false
是否启用时间纳秒精度。
inputs
object
(必选)输入插件列表,本文以文本输入插件为例。详细信息与插件参数,请参见CreateLogtailPipelineConfig - 创建Logtail流水线配置。
目前,只允许配置 1 个输入插件。
属性
Type
string
(必选)插件类型。文本输入插件固定为input_file。
FilePaths
string
(必选)待采集的日志文件路径列表(目前仅限 1 个路径)。路径中支持使用*和**通配符,其中**通配符仅能出现一次且仅限用于文件名前。例如/var/log/**/*.log为采集/var/log目录下所有后缀为.log的文件。
MaxDirSearchDepth
uint
(可选)
文件路径FilePaths中**通配符匹配的最大目录深度。仅当路径中存在**通配符时有效,取值范围为 0~1000。默认为0,若设置为1,FilePaths为/var/log/**/*.log,则采集/var/log目录下一级目录内所有后缀为.log的文件。
ExcludeFilePaths
string
(可选)
文件路径黑名单,排除指定条件的文件。路径必须为绝对路径,支持使用*通配符。
ExcludeFiles
string
(可选)
文件名黑名单,排除指定条件的文件。支持使用*通配符。
ExcludeDirs
string
(可选)
目录黑名单,排除指定条件的文件。路径必须为绝对路径,支持使用*通配符。
FileEncoding string
(可选)
文件编码格式。默认utf8。可选值包括 utf8 和 gbk。
TailSizeKB uint
(可选)
配置首次生效时,匹配文件中内容起始采集位置距离文件结尾的大小。默认为1024。如果文件大小小于该值,则从头开始采集,取值范围为 0~10485760KB。
Multiline
object
(可选)
多行聚合选项,填写该项表示开启多行日志采集,单行日志采集请删除该配置。
属性
Mod
string
(可选)
多行聚合模式。可选值:
custom:自定义匹配模式。
JSON:多行JSON模式。
StartPattern
string
(可选)
行首正则表达式,当Mod取值为custom时必填。以正则表达式来标定每一条日志的起始行。
EnableContainerDiscovery
bool
(可选)
是否启用容器发现功能。默认值false。仅当 Logtail 以 Daemonset 模式运行,且采集文件路径为容器内路径时有效。
ContainerFilters
object
(可选)
容器过滤选项。多个选项之间为“且”的关系,仅当 EnableContainerDiscovery 取值为 true 时有效。
属性
K8sNamespaceRegex
string
(可选)
对于部署于 K8s 环境的容器,指定待采集容器所在 Pod 所属的命名空间条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。
K8sPodRegex
string
(可选)
对于部署于 K8s 环境的容器,指定待采集容器所在 Pod 的名称条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。
IncludeK8sLabel
map
(可选)
对于部署于 K8s 环境的容器,指定待采集容器所在 pod 的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为 Pod 标签名,value 为 Pod 标签值。
若map 中 value 为空,则 pod 标签为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则 pod 标签中存在以 key 为标签名且对应标签值能正则匹配 value 的 pod 会被匹配;其他情况则 pod 标签中存在以 key 为标签名且对应标签值为 value 的 pod 才会被匹配。ExcludeK8sLabel
map
(可选)
对于部署于 K8s 环境的容器,指定需要排除采集容器所在 pod 的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为 pod 标签名,value 为 pod 标签的值。
若map 中 value 为空,则 pod 标签为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则 pod 标签中存在以 key 为标签名且对应标签值能正则匹配 value 的 pod 会被匹配;其他情况则 pod 标签中存在以 key 为标签名且对应标签值为 value 的 pod 才会被匹配。K8sContainerRegex
string
(可选)
对于部署于 K8s 环境的容器,指定待采集容器的名称条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。
IncludeEnv
map
(可选)
指定待采集容器的环境变量条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为环境变量名,value 为环境变量的值。
若map 中 value 为空,则容器环境变量为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器环境变量中存在以 key 为环境变量名且对应环境变量值能正则匹配 value 的 pod 会被匹配;其他情况则容器环境变量中存在以 key 为环境变量名且对应环境变量值为 value 的 pod 才会被匹配。ExcludeEnv
map
(可选)
指定需要排除采集容器的环境变量条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map 中的 key 为环境变量名,value 为环境变量的值。
若map 中 value 为空,则容器环境变量为 key 的 pod 都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器环境变量中存在以 key 为环境变量名且对应环境变量值能正则匹配 value 的 pod 会被匹配;其他情况则容器环境变量中存在以 key 为环境变量名且对应环境变量值为 value 的 pod 才会被匹配。IncludeContainerLabel
map
(可选)
指定待采集容器的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则默认为空,表示采集所有容器。支持正则匹配。 map 中的 key 为容器标签名,value 为容器标签的值。
若map 中 value 为空,则容器标签为 key 的容器都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器标签中存在以 key 为标签名且对应标签值能正则匹配 value 的容器会被匹配;其他情况则容器标签中存在以 key 为标签名且对应标签值为 value 的容器才会被匹配。ExcludeContainerLabel
map
(可选)
指定需要排除采集容器的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则默认为空,表示采集所有容器。支持正则匹配。 map 中的 key 为容器标签名,value 为容器标签的值。
若map 中 value 为空,则容器标签为 key 的容器都会被匹配;
若map 中 value 不为空,当 value 以
^
开头并以$
结尾,则容器标签中存在以 key 为标签名且对应标签值能正则匹配 value 的容器会被匹配;其他情况则容器标签中存在以 key 为标签名且对应标签值为 value 的容器才会被匹配。ExternalK8sLabelTag
map
(可选)
对于部署于 K8s 环境的容器,需要在日志中额外添加的与 Pod 标签相关的 tag。map 中的 key 为 Pod 标签名,value 为对应的 tag 名。 例如:在 map 中添加
app: k8s\_label\_app
,则若 pod 中包含app=serviceA
的标签时,会将该信息以 tag 的形式添加到日志中,即添加字段__tag__:k8s_label_app: serviceA
;若不包含app
标签,则会添加空字段__tag__:k8s_label_app:
。ExternalEnvTag
map
(可选)
对于部署于 K8s 环境的容器,需要在日志中额外添加的与容器环境变量相关的 tag。map 中的 key 为环境变量名,value 为对应的 tag 名。 例如:在 map 中添加
VERSION: env\_version
,则当容器中包含环境变量VERSION=v1.0.0
时,会将该信息以 tag 的形式添加到日志中,即添加字段__tag__:env_version: v1.0.0
;若不包含VERSION
环境变量,则会添加空字段__tag__:env_version:
。CollectingContainersMeta
bool
(可选)
是否启用容器元信息预览。默认值false。
AppendingLogPositionMeta
bool
(可选)
是否在日志中添加该条日志所属文件的元信息,包括__tag__:__inode__字段和__file_offset__字段。默认值false。
AllowingIncludedByMultiConfigs
bool
(可选)
是否允许当前配置采集其它配置已匹配的文件。默认值false。
processors
object
(可选)
处理插件列表。本文以正则解析插件为例。详细信息与插件参数,请参见CreateLogtailPipelineConfig - 创建Logtail流水线配置。
属性
Type
string
(必选)插件类型。正则解析插件固定为 processor_parse_regex_native。
SourceKey
string
(必选)源字段名。一般为content。
Regex
string
(必选)正则表达式。
Keys
[string]
(必选)提取的字段列表。
KeepingSourceWhenParseFail
bool
(可选)
当解析失败时,是否保留源字段。默认false。
KeepingSourceWhenParseSucceed
bool
(可选)
当解析成功时,是否保留源字段。默认false。
RenamedSourceKey
string
(可选)
当源字段被保留时,用于存储源字段的字段名。若不填,默认不改名。
aggregators
object
(可选)
聚合插件列表。本文以数据脱敏插件为例。详细信息与插件参数,请参见CreateLogtailPipelineConfig - 创建Logtail流水线配置。
属性
Type
string
(必选)插件类型。数据脱敏插件固定为 processor_desensitize。
SourceKey
string
(必选)日志字段名称。一般为content。
Method
string
(必选)脱敏方式。可选值:
const :将敏感内容替换为字符串。您可以通过 ReplaceString 参数指定目标字符串。
md5 :将敏感内容替换为对应的 MD5 值。
Match
string
(可选)
指定提取敏感内容的方式。可选值:
full(默认值) :全部提取,即替换目标字段值中的所有内容。
regex :使用正则表达式提取敏感内容。
ReplaceString
string
(可选)
用于替换敏感内容的字符串。 设置 Method 为 const 时必填。
RegexBegin
string
(可选)
匹配敏感内容前缀的正则表达式。 设置 Match 为 regex 时必填。
RegexContent
string
(可选)
匹配敏感内容的正则表达式。设置 Match 为 regex 时必填。
flushers
object
(必选)输出插件列表。
目前,只允许存在 1 个 flusher_sls 插件。
属性
Type
string
(必选)插件类型。固定为 flusher_sls。
Logstore
string
(必选)LogStrore 名称。用于确定采集配置的发送目标,需要确保存在。
configTags
map
(可选)
用于标记logtail采集配置的自定义标签。
machineGroups
object
(可选)
需要与logtail采集配置关联的机器组列表。安装
logtail-ds
组件时,日志服务会自动创建名为k8s-group-${your_k8s_cluster_id}
的机器组,默认值为仅包含该机器组的列表。alibaba-log-controller组件会保证logtail采集配置关联的机器组严格等于machineGroups指定的机器组,不在machineGroups中的机器组会被解除关联。
属性
name
string
(必选)需要与logtail采集配置关联的机器组名。
如果机器组不存在,alibaba-log-controller会自动创建同名的标识型机器组,标识与机器组名相同。详细信息,参见创建用户自定义标识机器组。该行为仅在创建机器组时生效。
enableUpgradeOverride
boolean
(可选)默认值为false
当集群中存在AliyunLogConfig定义的采集配置、且与当前的AliyunPipelineConfig指向同一个logtail采集配置时:
true:alibaba-log-controller会对已有的AliyunLogConfig定义的采集配置进行覆盖升级。
false:采集配置存在冲突,AliyunPipelineConfig应用失败。
指向同一个logtail采集配置的定义:目标project相同且目标Logtail采集配置名相同。
覆盖升级的定义:首先AliyunPipelineConfig生效,并更新logtail采集配置。然后删除集群内指向同一个logtail采集配置的AliyunLogConfig,覆盖更新完成。
两类CRD采集方式对比请参见CRD类型。
应用配置,执行如下命令:
kubectl apply -f <your_yaml>
验证生效:命令执行后,LoongCollector(Logtail)将依据您的配置开始采集容器日志,并将其发送到日志服务。
基础配置:定义输入与输出
输入(inputs)与输出(flushers),分别定义了要从哪里采集日志,以及日志要发送到哪里。这两部分共同构成了最基本、可运行的采集规则。
定义日志来源(inputs配置)
inputs
字段是采集配置的起点,它精确地告诉LoongCollector(Logtail)采集日志的来源和类型。目前,只允许配置1个输入插件。
容器标准输出-新版
用途:采集直接打印到控制台的(stdout/stderr)的日志。
关键字段详解 | 示例
|
Type 插件类型,容器标准输出(新版)为input_container_stdio。 | |
IgnoringStderr 是否忽略标准出错信息stderr。 | |
IgnoringStdout 是否忽略标准输出stdout。 |
采集容器内文本文件
用途:采集写入到容器内特定文件路径的日志,如传统的access.log或app.log。
关键字段详解 | 示例
|
Type 插件类型,采集容器内文件的插件类型为 | |
FilePaths 待采集的日志文件路径列表(目前仅限1个路径)。路径中支持使用 | |
MaxDirSearchDepth 文件路径中 | |
FileEncoding 文件编码格式。可选值包括utf8和gbk。 | |
EnableContainerDiscovery 是否启用容器发现功能。 说明 仅当LoongCollector(Logtail)以Daemonset模式运行,且采集文件路径为容器内路径时有效。 |
定义日志输出(flushers配置)
通过配置 flusher_sls
插件将日志数据输出到指定的 Logstore,并支持以 LZ4 压缩方式传输日志。目前,只允许配置1个输出插件。
关键字段详解 | 示例
|
Type 插件类型,输出插件类型为 | |
Logstore LogStrore 名称。用于确定采集配置的发送目标,需要确保存在。 |
示例:采集容器标准输出-新版
这是容器标准输出采集的最基础场景:仅采集容器的标准输出(Stdout)和标准错误(Stderr)原始日志,不做任何解析处理。
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
# 设置资源名,在当前Kubernetes集群内唯一,也是创建出的Logtail采集配置名。
name: new-stdio-config
spec:
project:
name: test-not-exist
logstores:
- name: new-stdio-logstore
# 定义LoongCollector(Logtail)采集与处理配置。
config:
# --- 输入插件:定义从哪里采集日志 ---
inputs:
# 使用input_file插件采集容器内文本日志
- Type: input_container_stdio
IgnoringStderr: false
IgnoringStdout: false
# --- 处理插件(可选):定义如何解析和处理日志 ---
processors: []
# --- 输出插件:定义将日志发送到哪里 ---
flushers:
- Type: flusher_sls # 指定使用SLS输出插件
Logstore: new-stdio-logstore
# 需要确保 endpoint 正确
Endpoint: cn-hangzhou.log.aliyuncs.com
Region: cn-hangzhou
TelemetryType: logs
示例:采集原始文本日志
这是文本日志采集的最基础场景:采集容器内原始日志文件内容,不进行任何解析,将原始日志整行上传至日志服务。
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: easy-row-config
spec:
# 指定日志要发送到的目标Project。
project:
name: test-not-exist
logstores:
- name: easy-row-logstore
# 定义LoongCollector(Logtail)采集与处理配置。
config:
# 日志样例(可不填写)
sample: ''
# --- 输入插件:定义从哪里采集日志 ---
inputs:
# 使用input_file插件采集容器内文本日志
- Type: input_file
# ... 此处为输入插件的具体配置 ...
# 容器内的文件路径
FilePaths:
- /var/log/text1.log
# 最大目录监控深度
MaxDirSearchDepth: 0
FileEncoding: utf8
# 启用容器发现功能。
EnableContainerDiscovery: true
# --- 处理插件(可选):定义如何解析和处理日志 ---
processors: []
# --- 输出插件:定义将日志发送到哪里 ---
flushers:
- Type: flusher_sls # 指定使用SLS输出插件
Logstore: easy-row-logstore
# ... 此处为输出插件的具体配置 ...
# 需要确保 endpoint 正确
Endpoint: cn-hangzhou.log.aliyuncs.com
Region: cn-hangzhou
TelemetryType: logs
解析配置:结构化日志
在完成基础配置:定义输入与输出后,您可以通过添加processors插件进行解析,将原始日志进行结构化解析,使其变为易于查询和分析的结构化数据。
核心配置:在config
中添加processors
部分,配置解析插件,支持同时启用多个插件。
Logtail提供了处理插件用于将原始日志进一步解析为结构化数据,处理插件分为原生处理插件和扩展处理插件,此处仅覆盖原生处理插件的使用。
对于Logtail 2.0之后的版本及LoongCollector组件,建议您优先用原生插件,在功能不满足的情况下,可以在原生插件后面级联扩展插件,但是扩展之后不能再级联原生插件。
正则解析
通过正则表达式提取日志字段,并将日志解析为键值对形式。
关键字段详解 | 示例
|
Type 插件类型,正则解析的插件类型为 | |
SourceKey 原始字段名。 | |
Regex 匹配日志的正则表达式。 | |
Keys 提取的字段列表。 | |
KeepingSourceWhenParseFail 解析失败时是否保留原始字段。 | |
KeepingSourceWhenParseSucceed 解析成功时是否保留原始字段。 | |
RenamedSourceKey 保留原始字段时,用于存储原始的字段名。 |
分隔符解析
通过分隔符将日志内容结构化,解析为多个键值对形式。支持单字符分隔符和多字符分隔符。
关键字段详解 | 示例
|
Type 插件类型,分隔符解析的插件类型为 | |
SourceKey 原始字段名。 | |
Separator 字段分隔符,例如 CSV 使用逗号 (,)。 | |
Keys 提取的字段列表。 | |
Quote 引用符,用于包裹包含特殊字符(如逗号)的字段内容。 | |
AllowingShortenedFields 是否允许提取的字段数量小于 Keys 的数量。若不允许,则此情景会被视为解析失败。 | |
OverflowedFieldsTreatment 当提取的字段数量大于 Keys 的数量时的行为。可选值包括:
| |
KeepingSourceWhenParseFail 解析失败时是否保留原始字段。 | |
KeepingSourceWhenParseSucceed 解析成功时是否保留原始字段。 | |
RenamedSourceKey 保留原始字段时,用于存储原始的字段名。 |
标准JSON解析
将Object类型的JSON日志结构化,解析为键值对形式。
关键字段详解 | 示例
|
Type 插件类型,JSON解析插件类型为 | |
SourceKey 原始字段名。 | |
KeepingSourceWhenParseFail 解析失败时是否保留原始字段。 | |
KeepingSourceWhenParseSucceed 解析成功时是否保留原始字段。 | |
RenamedSourceKey 保留原始字段时,用于存储原始的字段名。 |
嵌套JSON解析
通过指定展开深度,将嵌套的JSON日志解析为键值对形式。
关键字段详解 | 示例
|
Type 插件类型,嵌套JSON解析的插件类型为 | |
SourceKey 原始字段名。 | |
ExpandDepth JSON 展开深度。
| |
ExpandConnector JSON 展开时字段名的连接符。 | |
Prefix 指定 JSON 展开后字段名的前缀。 | |
IgnoreFirstConnector 是否忽略第一个连接符,即是否在顶级字段前添加连接符 | |
ExpandArray 是否展开数组类型。
说明 Logtail 1.8.0 及以上版本支持该参数。 | |
KeepSource 被解析后的日志中是否保留原始字段。
| |
NoKeyError 原始日志中无您所指定的原始字段时,系统是否报错。
| |
UseSourceKeyAsPrefix 是否将原始字段名作为所有 JSON 展开字段名的前缀。 | |
KeepSourceIfParseError 解析日志失败时,是否保留原始日志。
|
JSON数组解析
使用json_extract
函数,从JSON数组中提取JSON对象,更多json函数请参考JSON函数。
关键字段详解 | 示例
|
Type 插件类型,SPL插件类型为 | |
Script SPL 脚本内容,用于从 content 字段中提取 JSON 数组中的元素。 | |
TimeoutMilliSeconds 脚本超时时间,取值范围0~10000,单位为毫秒。 |
Nginx日志解析
根据log_format中的定义将日志内容结构化,解析为多个键值对形式。如默认内容不符合您的需求,可使用自定义格式。
关键字段详解 | 示例
|
Type 插件类型,Nginx日志解析的插件类型为 | |
SourceKey 源字段名。 | |
Regex 正则表达式。 | |
Keys 提取的字段列表。 | |
Extra 属性 Format Nginx配置文件中的日志配置部分,以log_format开头。 LogType 解析日志类型,固定值为 | |
KeepingSourceWhenParseFail 解析失败时是否保留原始字段。 | |
KeepingSourceWhenParseSucceed 解析成功时是否保留原始字段。 | |
RenamedSourceKey 保留原始字段时,用于存储原始的字段名。 |
Apache日志解析
根据Apache日志配置文件中的定义将日志内容结构化,解析为多个键值对形式。
关键字段详解 | 示例
|
Type 插件类型,Apache日志解析的插件类型为 | |
SourceKey 源字段名。 | |
Regex 正则表达式。 | |
Keys 提取的字段列表。 | |
Extra 属性 Format Apache配置文件中的日志配置部分,通常以LogFormat开头。 LogType 解析日志类型,固定值为 SubType 日志格式。
| |
KeepingSourceWhenParseFail 解析失败时是否保留原始字段。 | |
KeepingSourceWhenParseSucceed 解析成功时是否保留原始字段。 | |
RenamedSourceKey 保留原始字段时,用于存储原始的字段名。 |
高级配置:精细化处理
在完成基础配置:定义输入与输出后,您可以参考下述操作采集多行日志、对日志进行过滤、脱敏等处理,以满足更精细化的日志采集需求。以下是常见高级配置及其功能:
配置多行日志采集:当一条日志内容(如异常堆栈信息)占用多行时,需启用多行模式,并配置行首正则表达式以匹配日志的起始行,将占用多行的日志作为一条日志采集并存储到日志服务。
允许日志(文本文件/容器标准输出)多次采集:允许一个文件日志或容器标准输出被多个LoongCollector(Logtail)配置采集。
配置日志主题类型:为不同的日志流设置不同的主题(Topic),可用于组织和分类日志数据,更好地管理和检索相关日志。
指定容器采集(过滤与黑名单):需要指定特定容器与路径采集时,包括白名单与黑名单配置。
日志标签富化:将环境变量、Pod标签相关的元信息添加到日志中,作为日志的扩展字段。
日志脱敏处理:对日志中的敏感信息进行脱敏处理后保存到日志服务。
日志内容过滤:当原始日志中有大量无效日志无需保存到日志服务时,可使用日志过滤来剔除。
指定写入日志时间:用于解析日志中的时间字段,并将解析结果设置为日志的
__time__
字段。
配置多行日志采集
日志服务默认为单行模式,按行进行日志的切分与存储,导致含堆栈信息的多行日志被逐行切分,每一行作为独立日志存储和展示,不利于分析。
针对上述问题,可通过开启多行模式来改变日志服务的切分方式,并通过配置正则表达式匹配日志起始行,从而将原始日志按照起始行规则进行切分和存储。
核心配置:在inputs配置中添加Multiline参数。
参数说明:
mode
:多行聚合模式。可选值包括 custom 和 JSON。StartPattern
:行首正则表达式。当mode
取值为 custom 时必填。
示例:
# ...在 spec.config下...
inputs:
- Type: input_file
# 开启多行日志采集功能
Multiline:
# 模式选择:custom 表示自定义正则表达式匹配行首
Mode: custom
# 正则表达式匹配每条日志的起始行(即新日志开始的标志)
StartPattern: '\d+-\d+-\d+\s\d+:\d+:\d+'
允许日志(文本文件/容器标准输出)多次采集
默认情况下,一个日志文件/容器标准输出(Stdout)只能被一个Logtail配置匹配并采集。如果需要让多个 Logtail配置同时采集同一个日志文件/容器标准输出,则需启用 AllowingIncludedByMultiConfigs
参数。
示例:
# ...在 spec.config下...
inputs:
# input_container_stdio:容器标准输出-新版,input_file:文本日志采集
- Type: input_container_stdio # 或 input_file
# 允许同一个容器标准输出/文本日志被多个配置同时采集
AllowingIncludedByMultiConfigs: true
配置日志主题类型
核心配置:增加global
参数用以设置Topic,以下为日志主题的生成方式示例:
使用机器组 Topic
日志服务支持将一个Logtail配置应用到多个机器组。使用机器组Topic可用于区分来自不同机器组的日志。Logtail上报数据时,会将服务器所在机器组的机器组Topic作为日志主题上传至Project。用户在查询日志时需要指定日志主题作为查询条件。
spec:
config:
global:
#将应用该配置的机器组 Topic 作为 Topic
TopicType: machine_group_topic
文件路径提取
若不同的用户或应用将日志保存在不同的顶级目录中,但下级目录和日志文件名相同,日志服务在采集日志时无法明确区分日志是由哪个用户或应用产生的。此时文件路径提取方式可用于区分不同用户或应用产生的日志数据。通过正则表达式来完整匹配文件路径,并将表达式匹配的结果(用户名或应用名)作为日志主题(Topic)上传至日志服务。
场景1:不同用户将日志记录在不同目录下,但是日志文件名称相同,目录路径如下所示:
/data/logs
├── userA
│ └── serviceA
│ └── service.log
├── userB
│ └── serviceA
│ └── service.log
└── userC
└── serviceA
└── service.log
若仅配置/data/logs
下文件名称为service.log
的内容作为文件路径,LoongCollector(Logtail)会将三个service.log
文件中的内容采集至同一个Logstore中,则无法区分日志具体由哪个用户产生。此时您可以使用正则表达式提取文件路径中的值,生成不同的日志主题。
spec:
config:
global:
TopicType: filepath
# Topic 格式。当 TopicType 取值为 filepath 或 custom 时必填。
# 提取结果为__topic__: userA,__topic__: userB,__topic__: userC
TopicFormat: \/data\/logs\/(.*)\/serviceA\/.*
场景2:如果单个日志主题不足以区分日志的来源,您可以在日志文件路径中配置多个正则捕获组来提取关键信息。其中捕获组包括命名捕获组(?P<name>)与非命名捕获组两类。
如果使用命名捕获组,则生成的tag字段为
__tag__:{name}
;如果使用非命名捕获组,则生成的tag字段为
__tag__:__topic_{i}__
,其中{i}
为捕获组的序号。
spec:
config:
global:
TopicType: filepath
# 若文件路径为/data/logs/userA/serviceA/service.log,请根据以下两种捕获组的效果选择一种正则作为下方TopicFormat的值
# 非命名捕获组正则为:\/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
TopicFormat:
自定义
使用自定义的静态日志主题,修改下列示例中的自定义主题名。
spec:
config:
global:
TopicType: custom
# Topic 格式。当 TopicType 取值为 filepath 或 custom 时必填。
TopicFormat: customized:// + 自定义主题名
指定容器采集(过滤与黑名单)
过滤
只采集符合条件的容器,多个条件之间为“且”的关系,任意条件为空表示忽略该条件;条件支持使用正则表达式。需要在YAML的config.inputs使用容器过滤相关参数,以下为几种场景的示例:
Pod标签白名单/黑名单
# ...在 spec.config下...
inputs:
- Type: input_file # 或 input_container_stdio
# 容器过滤
ContainerFilters:
# K8s Pod标签白名单:指定需要采集日志的容器
IncludeK8sLabel:
# 示例:匹配所有包含 app 标签且标签值为 nginx 或 redis 的 Pod。
app: ^(nginx|redis)$
# K8s Pod标签黑名单:排除符合特定条件的容器日志采集
ExcludeK8sLabel:
# 示例:排除所有包含 app:test 标签的 Pod
app: test
环境变量白名单/黑名单
# ...在 spec.config下...
inputs:
- Type: input_file # 或 input_container_stdio
# 容器过滤
ContainerFilters:
# 环境变量白名单
IncludeEnv:
# 匹配所有包含 NGINX_SERVICE_PORT=80 或 NGINX_SERVICE_PORT=6379 的容器。
NGINX_SERVICE_PORT: ^(80|6379)$
# 环境变量黑名单
ExcludeEnv:
# 排除所有 ENVIRONMENT=test 的容器。
ENVIRONMENT: test
Pod名称/Namespace/容器名称正则匹配
# ...在 spec.config下...
inputs:
- Type: input_file # 或 input_container_stdio
# 容器过滤
ContainerFilters:
# Namespace 正则匹配,示例为匹配 default 和 nginx 命名空间下的所有容器。
K8sNamespaceRegex: ^(default|nginx)$
# Pod 名称正则匹配,示例为匹配所有以 nginx-log-demo 开头的 Pod 下的容器。
K8sPodRegex: ^(nginx-log-demo.*)$
# 容器名称正则匹配,示例为匹配所有名为 container-test 的容器
K8sContainerRegex: ^(container-test)$
黑名单
排除指定条件的文件。需要在YAML的config.inputs下按需使用如下参数:
# ...在 spec.config下...
inputs:
- Type: input_file
# 文件路径黑名单,排除指定条件的文件。路径必须为绝对路径,支持使用 * 通配符。
ExcludeFilePaths:
- /var/log/*.log
# 文件名黑名单,排除指定条件的文件。支持使用 * 通配符。
ExcludeFiles:
- test
# 目录黑名单,排除指定条件的文件。路径必须为绝对路径,支持使用 * 通配符。
ExcludeDirs:
- /var/log/backup*
日志标签富化
通过ExternalEnvTag
和 ExternalK8sLabelTag
向日志中添加与容器环境变量、Pod标签相关的tag。
# ...在 spec.config下...
inputs:
- Type: input_file # 或 input_container_stdio
# 环境变量相关:将指定的环境变量值映射为 tag 字段
ExternalEnvTag:
<环境变量名>: <tag名>
# Pod 标签相关:将 Kubernetes Pod 的标签值映射为 tag 字段
ExternalK8sLabelTag:
<Pod标签名>: <tag名>
日志脱敏处理
使用 processor_desensitize_native
插件对日志中的敏感数据进行脱敏处理。该插件通过指定字段名、脱敏方式、正则表达式等参数,将匹配的日志内容替换为指定字符串或加密值。
# ...在 spec.config下...
processors:
# 配置原生日志脱敏插件
- Type: processor_desensitize_native
# 原始字段名
SourceKey: content
# 脱敏方式:const 表示用固定字符串替换敏感内容
Method: const
# 替换敏感内容的目标字符串
ReplacingString: '********'
# 被替换内容前的内容表达式
ContentPatternBeforeReplacedString: 'password'':'''
# 敏感内容本身的正则表达式,匹配要被替换的内容
ReplacedContentPattern: '[^'']*'
# 是否替换所有匹配项,默认为 true
ReplacingAll: true
日志内容过滤
通过配置 processor_filter_regex_native
插件实现日志内容的过滤功能。该插件基于正则表达式匹配日志字段值,仅保留满足条件的日志,从而实现对日志的筛选。
# ...在 spec.config下...
processors:
# 配置正则表达式过滤插件(可用于日志脱敏或敏感词过滤)
- Type: processor_filter_regex_native
# 定义正则表达式列表,用于匹配日志字段的内容
FilterRegex:
# 示例:匹配日志字段值中包含 "WARNING" 或 "ERROR" 的内容
- WARNING|ERROR
# 指定需要匹配的日志字段名,示例为对 level 字段进行过滤
FilterKey:
- level
指定写入日志时间
配置 processor_parse_timestamp_native
插件对日志中的时间字段进行解析,并将解析结果设置为日志的时间戳字段(__time__
)。该插件通过指定时间格式和原始字段,提取日志中的时间信息并标准化处理。
# ...在 spec.config下...
processors:
# 配置原生时间解析插件
- Type: processor_parse_timestamp_native
# 原始日志字段来源,通常为 content
SourceKey: content
# 时间格式定义,需与日志中的时间字段格式完全匹配
SourceFormat: '%Y-%m-%d %H:%M:%S'
常见场景完整配置示例
场景一:采集Nginx Access log并解析为结构化字段
解析Nginx日志,根据log_format中的定义将日志内容结构化,解析为多个键值对形式。
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: nginx-config
spec:
config:
aggregators: []
global: {}
inputs:
- Type: input_file
FilePaths:
- /root/log/text1.log
MaxDirSearchDepth: 0
FileEncoding: utf8
EnableContainerDiscovery: true
processors:
- Type: processor_parse_regex_native
SourceKey: content
Regex: >-
(\S*)\s*-\s*(\S*)\s*\[(\d+/\S+/\d+:\d+:\d+:\d+)\s+\S+\]\s*"(\S+)\s+(\S+)\s+\S+"\s*(\S*)\s*(\S*)\s*(\S*)\s*(\S*)\s*"([^"]*)"\s*"([^"]*)".*
Keys:
- remote_addr
- remote_user
- time_local
- request_method
- request_uri
- request_time
- request_length
- status
- body_bytes_sent
- http_referer
- http_user_agent
Extra:
Format: >-
log_format main '$remote_addr - $remote_user [$time_local]
"$request" ''$request_time $request_length ''$status
$body_bytes_sent "$http_referer" ''"$http_user_agent"';
LogType: NGINX
flushers:
- Type: flusher_sls
Logstore: my-log-logstore
sample: >-
192.168.*.* - - [15/Apr/2025:16:40:00 +0800] "GET /nginx-logo.png
HTTP/1.1" 0.000 514 200 368 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.*.* Safari/537.36"
project:
name: my-log-project
logstores:
- name: my-log-logstore
场景二:采集并处理多行日志
日志服务默认为单行模式,按行进行日志的切分与存储,导致含堆栈信息的多行日志被逐行切分,每一行作为独立日志存储和展示,不利于分析。
针对上述问题,可通过开启多行模式来改变日志服务的切分方式,并通过配置正则表达式匹配日志起始行,从而将原始日志按照起始行规则进行切分和存储。示例如下:
apiVersion: telemetry.alibabacloud.com/v1alpha1
kind: ClusterAliyunPipelineConfig
metadata:
name: multiline-config
spec:
config:
aggregators: []
global: {}
inputs:
- Type: input_file
FilePaths:
- /root/log/text1.log
MaxDirSearchDepth: 0
FileEncoding: utf8
Multiline:
StartPattern: '\[\d+-\d+-\w+:\d+:\d+,\d+]\s\[\w+]\s.*'
Mode: custom
UnmatchedContentTreatment: single_line
EnableContainerDiscovery: true
processors: []
flushers:
- Type: flusher_sls
Logstore: my-log-logstore
sample: |-
[2023-10-01T10:30:01,000] [INFO] java.lang.Exception: exception happened
at TestPrintStackTrace.f(TestPrintStackTrace.java:3)
at TestPrintStackTrace.g(TestPrintStackTrace.java:7)
at TestPrintStackTrace.main(TestPrintStackTrace.java:16)
project:
name: my-log-project
logstores:
- name: my-log-logstore
常见问题
如何将ACK集群日志传输到另一个阿里云账号的日志服务?
通过在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
,详细配置参数请参见LoongCollector安装与管理(Kubernetes)。# ===================== 必需要补充的内容 ===================== # 本集群要采集的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
安装完成后,查看组件状态,若未成功启动,请确认values.yaml配置是否正确,相关镜像拉取是否成功。日志服务会自动创建如下资源,您可登录日志服务控制台查看。
# 检查Pod状态 kubectl get po -n kube-system | grep loongcollector-ds
安装完LoongCollector(Logtail)之后,您可以参考基础配置定义采集任务的核心参数,日志数据顺利采集并传输至指定Project下的Logstore。