帮你快速理解、总结文档立即下载
文档中心>日志服务>操作指南>日志采集>使用环境变量声明式采集日志

使用环境变量声明式采集日志

最近更新时间：2026-07-27 16:47:32

我的收藏

本页目录：

操作场景

在 Kubernetes 容器环境中，应用开发者通常需要运维人员先在控制台上进行配置 CRD 等操作后，才能接入 CLS 日志采集。Workload 环境变量声明式采集功能允许开发者在 Workload 的 env 中直接声明环境变量，无需编写 LogConfig CRD 即可自动完成日志采集配置。
该功能适用于以下场景：
应用开发者需要自助接入日志采集，无需等待运维操作。
团队希望将日志采集配置与应用部署声明放在一起，实现 GitOps 管理。
快速验证或开发环境下需要极简方式接入日志服务。

前提条件

已开通 日志服务 CLS。根据集群类型，还需满足以下条件：

TKE 集群

已创建 TKE 标准集群，且 Kubernetes 版本 ≥ 1.18，可参见 创建集群。
集群已开启日志采集功能，即已安装 3.0.3 及以上镜像版本的 tke-log-agent（DaemonSet）和 3.0.3 及以上镜像版本的 cls-provisioner（Deployment）。如未安装，请在 TKE 控制台 的集群监控告警 > 日志页面开启日志采集。

自建 K8s 集群

已创建自建 Kubernetes 集群，且 Kubernetes 版本 ≥ 1.18。
集群已安装 LogListener DaemonSet 组件（安装方式请参见 自建 K8s 集群安装 LogListener）。
集群已部署 3.0.3 及以上镜像版本的 cls-provisioner（Deployment）。

使用限制

仅支持 Deployment、StatefulSet、DaemonSet、Job、CronJob 工作负载类型，不支持裸 Pod（无 ownerReference 的 Pod，例如通过 kubectl run 创建的 Pod）。
支持 TKE 标准集群和自建 K8s 集群（需部署 cls-provisioner），不支持 EKS Serverless 集群。
同一 Workload 下所有副本的 env 必须一致，不支持多副本 env 不同的场景。
通过环境变量创建的采集配置不支持在 CLS 控制台或 TKE 控制台修改。修改内容会在 Pod 重建时被环境变量的原始声明覆盖。如需调整采集规则，请直接修改 Pod env 后重新部署（重新部署会导致 Pod 重启）。
环境变量适用于标准采集场景，如需使用高级功能（如投递配置、处理插件等），建议删除当前环境变量与已创建的采集配置，改用 TKE 控制台、API 或 LogConfig CRD 进行配置。

操作步骤

根据您的日志来源，选择以下任一采集场景进行配置。各场景之间可组合使用，一个 Pod 中可同时声明多组 cls_logs_{key} 环境变量，实现多路采集，可参见 场景五：多路采集（组合配置）。

场景一：采集容器标准输出（最简配置）

在 Pod 的工作负载 YAML 中，为目标容器的 env 字段添加以下环境变量即可开启标准输出采集：
env:
  - name: cls_logs_demo
    value: stdout
说明：
其中 {key} 是用户自定义的采集规则标识名，用于区分同一 Workload 中的不同采集规则。同一个 Workload 中可以声明多组 cls_logs_{key} 环境变量（即多个不同的 key），每组代表一路独立的采集配置。
{key} 需遵循以下约束：
只能包含小写字母、数字和短划线（-）。
在同一个 Workload 内必须唯一，即同一个 Deployment / StatefulSet / DaemonSet 等工作负载中不能声明两组相同 key 的环境变量。
完整的 Deployment YAML 示例如下（ env 部分为需要添加的环境变量）：
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:latest
          env:
            # 添加以下环境变量即可开启 CLS 标准输出采集
            - name: cls_logs_demo
              value: stdout

场景二：采集容器内文件

如需采集容器内指定路径的日志文件，设置采集类型为 container_file 并通过 _path 指定文件路径：
env:
  - name: cls_logs_applog
    value: container_file
  - name: cls_logs_applog_path
    value: /usr/local/app/logs/*.log

场景三：采集节点（宿主机）文件

如需采集宿主机上的日志文件，设置采集类型为 host_file：
env:
  - name: cls_logs_hostlog
    value: host_file
  - name: cls_logs_hostlog_path
    value: /data/logs/*.log
说明：
此处的路径是宿主机上的路径，而非容器内路径。LogListener 以 DaemonSet 形式运行在每个节点上，因此可以直接访问宿主机文件系统。开发者在容器的 env 中声明路径后，会生成对应的 LogConfig CR，由节点上的 LogListener 进程完成采集。

场景四：指定已有 Topic（不自动创建资源）

如果您已有 CLS Topic，可通过 _topic_id 环境变量直接指定，cls-provisioner 将复用该 Topic 而不自动创建新资源。
env:
  - name: cls_logs_demo
    value: stdout
  - name: cls_logs_demo_topic_id
    value: lhxxx-xxxx-xxxx-1234567890
说明：
指定 _topic_id 后，TTL、分区数等自动建相关的参数将被忽略，系统直接使用该 Topic 现有配置。

场景五：多路采集（组合配置）

一个 Pod 中可以同时声明多组 cls_logs_{key} 环境变量，实现多路日志采集。每组使用不同的 {key} 即可，cls-provisioner 会为每组声明分别创建独立的 LogConfig CR 和 Topic。
以下示例同时采集标准输出和容器内文件：
env:
  # 第一路：采集标准输出
  - name: cls_logs_stdout
    value: stdout
  # 第二路：采集容器内应用日志文件
  - name: cls_logs_applog
    value: container_file
  - name: cls_logs_applog_path
    value: /usr/local/app/logs/*.log
  - name: cls_logs_applog_log_type
    value: json_log

场景六：配置日志解析规则（可选）

默认采集模式为单行全文（minimalist_log）。如需其他解析方式，可通过 _log_type 环境变量指定。

JSON 格式

env:
  - name: cls_logs_demo
    value: stdout
  - name: cls_logs_demo_log_type
    value: json_log
  - name: cls_logs_demo_json_standard
    value: "true"

分隔符格式

env:
  - name: cls_logs_demo
    value: stdout
  - name: cls_logs_demo_log_type
    value: delimiter_log
  - name: cls_logs_demo_delimiter
    value: "|"
  - name: cls_logs_demo_keys
    value: "time,level,module,message"

多行全文格式

env:
  - name: cls_logs_demo
    value: stdout
  - name: cls_logs_demo_log_type
    value: multiline_log
  - name: cls_logs_demo_beginning_regex
    value: "\\\\d{4}-\\\\d{2}-\\\\d{2}"

完全正则格式

env:
  - name: cls_logs_demo
    value: stdout
  - name: cls_logs_demo_log_type
    value: fullregex_log
  - name: cls_logs_demo_log_regex
    value: "(\\\\d{4}-\\\\d{2}-\\\\d{2} \\\\d{2}:\\\\d{2}:\\\\d{2}) (\\\\w+) (.*)"
  - name: cls_logs_demo_keys
    value: "time,level,message"
说明：
在 YAML 双引号字符串中，反斜杠需要双重转义。例如正则 \\d{4} 在 YAML 中应写为 "\\\\d{4}"。如果使用单引号或无引号的 YAML 字符串，则只需单个反斜杠。

验证采集结果

1. 部署或更新工作负载后，等待约30秒完成解析和 LogConfig CR 创建。
2. 登录 容器服务控制台，在左侧导航栏中选择集群。在集群列表中，单击目标集群 ID，进入集群详情页。选择左侧导航栏中的日志，在日志采集页签预期输出中可看到名称格式为 cls-env-{namespace}-{workload}-{key} 的采集配置。

3. 登录 CLS 控制台，在日志检索页面选择对应 Topic，查看是否有日志数据上报。

环境变量完整参数

以下列出所有支持的环境变量参数。所有参数均以 cls_logs_{key}_ 为前缀（{key} 为您自定义的采集规则标识名）。
说明：
关于 {key}：可参见 { key } 说明。

基础配置

环境变量
必填
默认值
说明
cls_logs_{key}
是
-
采集类型：stdout（标准输出）、container_file（容器内文件）、host_file（节点文件）
cls_logs_{key}_path
条件必填
-
日志文件路径，采集类型为 container_file 或 host_file 时必填。支持通配符（如 /data/logs/*.log）。一个环境变量只能配置一个路径模式，如需采集多个不同路径，需创建多组 cls_logs_{key} 环境变量（使用不同的 key）

日志主题配置

日志主题（Topic）和日志集（Logset）的创建分为两种方式。

方式一：自动创建（推荐）

不指定 _topic_id 时，系统将自动创建日志集和日志主题，并使用以下命名规则：
日志集名称：k8s-<cluster-id>（按集群 ID 自动命名）。
日志主题名称：{namespace}-{key}（按命名空间和 key 自动命名）。
说明：
如果您希望日志主题和日志集的名称与业务有清晰的语义对应关系，建议使用自动创建模式。系统会基于集群 ID、命名空间和采集规则标识（key）自动生成有语义的名称，便于后续管理和检索。
自动创建时，支持通过以下环境变量自定义日志主题属性：
环境变量
必填
默认值
说明
cls_logs_{key}_period
否
30
日志保存时间（天），取值1 - 3600，3640表示永久保存
cls_logs_{key}_partition_count
否
1
Topic 分区数，取值1 - 10

方式二：指定已有日志主题

如果您已有日志主题，可以通过 _topic_id 直接指定该 Topic 的 ID，日志将投递到该已有 Topic。此时，上述自动创建相关参数（_period、_partition_count）均不生效。
环境变量
必填
默认值
说明
cls_logs_{key}_topic_id
是
-
指定已有日志主题的 ID。填写后日志将直接投递到该 Topic，自动创建相关参数不生效

解析规则配置

环境变量
必填
默认值
说明
cls_logs_{key}_log_type
否
minimalist_log
提取模式，取值：
minimalist_log：单行全文
json_log：JSON 格式
delimiter_log：分隔符格式
multiline_log：多行全文
fullregex_log：单行完全正则
multiline_fullregex_log：多行完全正则
cls_logs_{key}_json_standard
否
true
是否为标准 JSON，仅 json_log 模式生效
cls_logs_{key}_delimiter
否
空格
分隔符，仅 delimiter_log 模式生效，例如空格、`
、\\t` 等
cls_logs_{key}_keys
否
-
提取的字段名，逗号分隔。delimiter_log 和 fullregex_log 模式使用。为空的 key 代表丢弃该字段
cls_logs_{key}_log_regex
否
-
正则表达式，仅 fullregex_log 或 multiline_fullregex_log 模式生效
cls_logs_{key}_beginning_regex
否
-
行首正则，仅 multiline_log 或 multiline_fullregex_log 模式生效
cls_logs_{key}_time_key
否
-
时间字段名，不写则使用采集时间
cls_logs_{key}_time_format
否
-
时间格式（strftime 风格，例如 %Y-%m-%d %H:%M:%S），必须与 _time_key 成对使用

过滤配置

环境变量
必填
默认值
说明
cls_logs_{key}_filter_keys
否
-
过滤字段名，逗号分隔
cls_logs_{key}_filter_regex
否
-
过滤正则，与 _filter_keys 相互对应
cls_logs_{key}_un_match_upload
否
true
是否上传解析失败的日志
cls_logs_{key}_un_matched_key
否
LogParseFailure
解析失败日志的键名，仅 _un_match_upload 为 true 时生效

采集范围与标签

环境变量
必填
默认值
说明
cls_logs_{key}_tags
否
-
自定义元数据标签，格式 k1=v1,k2=v2，会追加到 LogConfig CR 的 customLabels 中
cls_logs_{key}_exclude_paths
否
-
黑名单排除路径，逗号分隔，仅文件采集模式（container_file / host_file）生效
cls_logs_{key}_max_depth
否
1
最大目录深度，0表示仅当前目录，仅文件采集模式生效

系统固定配置项（不可修改）

以下配置由系统自动设定，不支持通过环境变量修改：
分类
配置项
默认值
说明
日志主题
日志集名（Logset Name）
k8s-<cluster-id>
按集群 ID 自动命名，不可自定义
日志主题
日志主题名（Topic Name）
{namespace}-{key}
按命名空间和 key 自动命名，不可自定义
日志主题
存储类型
hot（标准存储）
固定为标准存储
日志主题
沉降周期
7天
仅 storageType=hot 时生效
日志主题
自动分裂
开启（true），最大50分区
固定开启
采集行为
采集策略（起始位置）
增量采集
从文件当前位置开始采集，不回溯历史数据
采集行为
编码模式
UTF-8
固定使用 UTF-8编码，不支持 GBK
采集行为
文件超时
不超时
不对文件设置超时，持续监听文件变更
采集行为
解析失败合并
关闭
解析失败的日志不做合并处理
索引
全文索引
开启
默认开启全文索引
索引
分词符
@&()='",;:<>[]{}/\\n\\t\\r
CRD 标准分词符集合
索引
大小写敏感
false
不区分大小写
索引
包含中文
false
不包含中文分词
索引
键值索引
关闭
默认不开启键值索引
注意：
索引配置仅在自动创建 Topic 时生效。
中国站