Kubernetes标准输出（旧版）_日志服务(SLS)-阿里云帮助中心

Logtail输入配置支持采集容器标准输出。本文主要介绍旧版标准输出采集配置。

功能特点

Logtail支持采集容器内产生的标准输出，并附加容器的相关元数据信息一起上传到日志服务。Logtail具备以下功能特点。

支持采集标准输出信息（stdout）和标准出错信息（stderr）。
支持通过容器Label白名单指定待采集的容器。
支持通过容器Label黑名单排除不需要采集的容器。
支持通过环境变量白名单指定待采集的容器。
支持通过环境变量黑名单排除不需要采集的容器。
支持采集多行日志（例如Java Stack日志）。
支持上报容器日志时自动关联Meta信息（例如容器名、镜像、Pod、Namespace、环境变量等）。
当容器运行于Kubernetes时，Logtail还具有以下功能。
- 支持通过Kubernetes Namespace名称、Pod名称、容器名称指定待采集的容器。
- 支持通过Kubernetes Label白名单指定待采集的容器。
- 支持通过Kubernetes Label黑名单排除不需要采集的容器。
- 支持上报容器日志时自动关联Kubernetes Label信息。

实现原理

Logtail与Docker的Domain Socket进行通信，查询该Docker上运行的所有容器，并根据容器中的Label和环境变量定位需要被采集的容器。Logtail通过容器元信息获取容器标准输出log-file的位置进行数据采集。

Logtail在采集容器的标准输出时，会定期将采集的点位信息保存到checkpoint文件中。如果Logtail停止后再次启动，会从上一次保存的点位开始采集。实现原理

使用限制

此功能目前仅支持Linux操作系统，依赖Logtail 0.16.0及以上版本。版本查看与升级，请参见安装Logtail（Linux系统）。
Logtail支持Docker和Containerd两种容器引擎的数据采集，访问路径说明如下：
- Docker：Logtail通过/run/docker.sock访问Docker，请确保该路径存在且具备访问权限。
- Containerd：Logtail通过/run/containerd/containerd.sock访问Containerd，请确保该路径存在且具备访问权限。
多行日志限制：为保证多行组成的一条日志不因为输出延迟而被分割成多条，多行日志情况下，采集的最后一条日志默认都会缓存一段时间。默认缓存时间为3秒，可通过BeginLineTimeoutMs参数修改，但此值不能低于1000（毫秒），否则容易出现误判。
采集停止策略：当容器被停止后，Logtail监听到容器die的事件后会停止采集该容器的标准输出。如果此时采集出现延迟，则可能丢失停止前的部分输出。
Docker容器引擎限制：目前标准输出采集仅支持JSON类型的日志驱动。
上下文限制：默认同一Logtail配置下的所有容器的标准输出处于同一上下文中，即无法使用控制台的上下文查询及Livetail功能直接查看某一容器标准输出的上下文。如果需要使用这些功能，请添加日志上下文聚合插件。更多信息，请参见aggregators配置。
数据处理：采集到的数据默认保存在content字段中。Logtail对于采集到的容器标准输出，支持数据处理。更多信息，请参见使用Logtail插件处理数据。

功能入口

配置说明

表单配置（控制台配置）

参数	说明
标准输出	打开标准输出后，Logtail将采集容器标准输出。
标准错误	打开标准错误后，Logtail将采集容器标准错误。
允许标准输出多次采集	默认情况下，一个容器的标准输出日志只能匹配一个Logtail新版标准输出采集配置。如果标准输出需要被多个新版标准输出采集配置采集，需打开允许标准输出多次采集开关。
启用容器元信息预览	打开启用容器元信息预览后，您可以在创建Logtail配置后，查看容器元信息，包括匹配容器信息和全量容器信息。
容器过滤	过滤条件说明重要容器Label为Docker inspect中的Label，不是Kubernetes中的Label。如何获取，请参见获取容器Label。环境变量为容器启动中配置的环境变量信息。如何获取，请参见获取容器环境变量。 Kubernetes场景下，推荐使用Kubernetes层级的信息（K8s Pod名称正则匹配、K8s Namespace正则匹配、K8s容器名称正则匹配、K8s Pod标签白名单等）进行容器过滤。 Kubernetes中的Namespace和容器名称会映射到容器Label中，分别为`io.kubernetes.pod.namespace`和`io.kubernetes.container.name`，推荐使用这两个容器Label进行容器过滤。例如，某Pod所属的命名空间为`backend-prod`，容器名为`worker-server`，如果您要采集包含该容器的日志，可以设置容器Label白名单为`io.kubernetes.pod.namespace : backend-prod`或`io.kubernetes.container.name : worker-server`。如果以上两个容器Label不满足过滤需求，请使用环境变量的黑白名单进行容器过滤。 K8s Pod名称正则匹配通过Pod名称指定待采集的容器，支持正则匹配。例如设置为`^(nginx-log-demo.)$`，表示匹配以nginx-log-demo开头的Pod下的所有容器。 K8s Namespace正则匹配* 通过Namespace名称指定采集的容器，支持正则匹配。例如设置为`^(default\|nginx)$`，表示匹配nginx命名空间、default命名空间下的所有容器。 K8s容器名称正则匹配通过容器名称指定待采集的容器（Kubernetes容器名称是定义在spec.containers中），支持正则匹配。例如设置为`^(container-test)$`，表示匹配所有名为container-test的容器。容器label白名单容器Label白名单，用于指定待采集的容器。默认为空，表示采集所有容器的标准输出。如果您要设置容器Label白名单，那么LabelKey必填，LabelValue可选填。如果LabelValue为空，则容器Label中包含LabelKey的容器都匹配。如果LabelValue不为空，则容器Label中包含LabelKey=LabelValue的容器才匹配。 LabelValue默认为字符串匹配，即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如：配置LabelKey为`io.kubernetes.container.name`，配置LabelValue为`^(nginx\|cube)$`，表示可匹配名为nginx、cube的容器。多个白名单之间为或关系，即只要容器Label满足任一白名单即可被匹配。容器label黑名单容器Label黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置容器Label黑名单，那么LabelKey必填，LabelValue可选填。如果LabelValue为空，则容器Label中包含LabelKey的容器都将被排除。如果LabelValue不为空，则容器Label中包含LabelKey=LabelValue的容器才会被排除。 LabelValue默认为字符串匹配，即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如：设置LabelKey为`io.kubernetes.container.name`，设置LabelValue为`^(nginx\|cube)$`，表示可匹配名为nginx、cube的容器。多个黑名单之间为或关系，即只要容器Label满足任一黑名单对即可被排除。环境变量白名单环境变量白名单，用于指定待采集的容器。默认为空，表示采集所有容器的标准输出。如果您要设置环境变量白名单，那么EnvKey必填，EnvValue可选填。如果EnvValue为空，则容器环境变量中包含EnvKey的容器都匹配。如果EnvValue不为空，则容器环境变量中包含EnvKey=EnvValue的容器才匹配。 EnvValue默认为字符串匹配，即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配，例如：设置EnvKey为`NGINX_SERVICE_PORT`，设置EnvValue为`^(80\|6379)$`，表示可匹配服务端口为80、6379的容器。多个白名单之间为或关系，即只要容器的环境变量满足任一键值对即可被匹配。环境变量黑名单环境变量黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置环境变量黑名单，那么EnvKey必填，EnvValue可选填。如果EnvValue为空，则容器环境变量中包含EnvKey的容器的日志都将被排除。如果EnvValue不为空，则容器环境变量中包含EnvKey=EnvValue的容器才会被排除。 EnvValue默认为字符串匹配，即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配，例如：设置EnvKey为`NGINX_SERVICE_PORT`，设置EnvValue为`^(80\|6379)$`，表示可匹配服务端口为80、6379的容器。多个黑名单之间为或关系，即只要容器的环境变量满足任一键值对即可被排除。 K8s Pod标签白名单通过Kubernetes Label白名单指定待采集的容器。如果您要设置Kubernetes Label白名单，那么LabelKey必填，LabelValue可选填。如果LabelValue为空，则Kubernetes Label中包含LabelKey的容器都匹配。如果LabelValue不为空，则Kubernetes Label中包含LabelKey=LabelValue的容器才匹配。 LabelValue默认为字符串匹配，即只有LabelValue和Kubernetes Label的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如设置LabelKey为`app`，设置LabelValue为`^(test1\|test2)$`，表示匹配Kubernetes Label中包含app:test1、app:test2的容器。多个白名单之间为或关系，即只要Kubernetes Label满足任一白名单即可被匹配。说明由于在Kubernetes管控类资源（例如Deployment）运行时更改Label，不会重启具体的工作资源Pod，因此Pod无法感知此变更，可能导致匹配规则失效。设置K8s Label黑白名单时，请以Pod中的Kubernetes Label为准。关于Kubernetes Label的更多信息，请参见Labels and Selectors。 K8s Pod标签黑名单通过Kubernetes Label黑名单排除不采集的容器。如果您要设置Kubernetes Label黑名单，那么LabelKey必填，LabelValue可选填。如果LabelValue为空，则Kubernetes Label中包含LabelKey的容器都被排除。如果LabelValue不为空，则Kubernetes Label中包含LabelKey=LabelValue的容器才会被排除。 LabelValue默认为字符串匹配，即只有LabelValue和Kubernetes Label的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如设置LabelKey为`app`，设置LabelValue为`^(test1\|test2)$`，表示匹配Kubernetes Label中包含app:test1、app:test2的容器。多个黑名单之间为或关系，即只要Kubernetes Label满足任一黑名单对即可被排除。说明由于在Kubernetes管控类资源（例如Deployment）运行时更改Label，不会重启具体的工作资源Pod，因此Pod无法感知此变更，可能导致匹配规则失效。设置K8s Label黑白名单时，请以Pod中的Kubernetes Label为准。关于Kubernetes Label的更多信息，请参见Labels and Selectors。
日志标签富化	您可以将环境变量和Kubernetes Label添加到日志，作为日志标签。环境变量相关设置环境变量扩展字段后，日志服务将在日志中新增环境变量相关字段。例如设置环境变量名为`VERSION`，设置tag名为`env_version`，当容器中包含环境变量`VERSION=v1.0.0`时，会将该信息添加到日志中，即添加字段__tag__:__env_version__: v1.0.0。 Pod标签相关设置Kubernetes Pod扩展字段后，日志服务将在日志中新增Kubernetes Pod相关字段。例如设置Pod标签名为`app`，设置tag名为`k8s_pod_app`，当Kubernetes中包含Label`app=serviceA`时，会将该信息添加到日志中，即添加字段__tag__:__k8s_pod_app__: serviceA。
首次采集大小	配置首次生效时，标准输出日志文件的起始采集位置距离文件结尾的大小。首次采集大小设定值为1024 KB。首次采集时，如果文件小于1024 KB，则从文件内容起始位置开始采集。首次采集时，如果文件大于1024 KB，则从距离文件末尾1024 KB的位置开始采集。您可以通过此处修改首次采集大小，取值范围为0~10485760，单位为KB。
高级参数	Logtail配置的部分参数需要手动输入，请参见创建Logtail流水线配置。

配置示例

CRD-AliyunPipelineConfig

参数	类型	是否必填	默认值	示例	说明
Type	string	是	/	service_docker_stdout	插件类型。固定为 service_docker_stdout。
Stdout	Boolean	否	true	true	是否采集标准输出 stdout。
Stderr	Boolean	否	true	true	是否采集标准出错信息 stderr。
StartLogMaxOffset	Integer	否	128×1024	131072	首次采集时回溯历史数据长度，单位：字节。建议取值在[131072,1048576]之间。
IncludeLabel	Map，其中 LabelKey 和 LabelValue 为 String 类型	否	空		容器 Label 白名单，用于指定待采集的Docker容器。默认为空，表示采集所有容器的标准输出。如果您要设置容器 Label 白名单，那么 LabelKey 必填，LabelValue 可选填。如果 LabelValue 为空，则容器 Label 中包含 LabelKey 的容器都匹配。如果 LabelValue 不为空，则容器 Label 中包含 LabelKey=LabelValue 的容器才匹配。 LabelValue 默认为字符串匹配，即只有 LabelValue 和容器 Label 的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如设置 LabelKey 为`io.kubernetes.container.name`，设置 LabelValue 为`^(nginx\|cube)$`，表示可匹配名为 nginx、cube 的容器。多个白名单之间为或关系，即只要容器 Label 满足任一白名单即可匹配。
ExcludeLabel	Map，其中 LabelKey 和 LabelValue 为 String 类型	否	空		容器 Label 黑名单，用于排除不采集的Docker容器。默认为空，表示不排除任何容器。如果您要设置容器 Label 黑名单，那么 LabelKey 必填，LabelValue 可选填。如果 LabelValue 为空，则容器 Label 中包含 LabelKey 的容器都将被排除。如果 LabelValue 不为空，则容器 Label 中包含 LabelKey=LabelValue 的容器才会被排除。 LabelValue 默认为字符串匹配，即只有 LabelValue 和容器 Label 的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如设置 LabelKey 为`io.kubernetes.container.name`，设置 LabelValue 为`^(nginx\|cube)$`，表示可匹配名为 nginx、cube 的容器。多个黑名单之间为或关系，即只要容器 Label 满足任一黑名单对即可被排除。
IncludeEnv	Map，其中 EnvKey 和 EnvValue 为 String 类型	否	空		设环境变量白名单，用于指定待采集的容器。默认为空，表示采集所有容器的标准输出。如果您要设置环境变量白名单，那么 EnvKey 必填，EnvValue 可选填。如果 EnvValue 为空，则容器环境变量中包含 EnvKey 的容器都匹配。如果 EnvValue 不为空，则容器环境变量中包含 EnvKey=EnvValue 的容器才匹配。 EnvValue 默认为字符串匹配，即只有 EnvValue 和环境变量的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配，例如设置 EnvKey 为`NGINX_SERVICE_PORT`，设置 EnvValue 为`^(80
ExcludeEnv	Map，其中 EnvKey 和 EnvValue 为 String 类型	否	空		环境变量黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置环境变量黑名单，那么 EnvKey 必填，EnvValue 可选填。如果 EnvValue 为空，则容器环境变量中包含 EnvKey 的容器的日志都将被排除。如果 EnvValue 不为空，则容器环境变量中包含 EnvKey=EnvValue 的容器才会被排除。 EnvValue 默认为字符串匹配，即只有 EnvValue 和环境变量的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配，例如设置 EnvKey 为`NGINX_SERVICE_PORT`，设置 EnvValue 为`^(80\|6379)$`，表示可匹配服务端口为 80、6379 的容器。多个黑名单之间为或关系，即只要容器的环境变量满足任一键值对即可被排除。
IncludeK8sLabel	Map，其中 LabelKey 和 LabelValue 为 String 类型	否	空		通过 Kubernetes Label（定义在 template.metadata 中）白名单指定待采集的容器。如果您要设置 Kubernetes Label 白名单，那么 LabelKey 必填，LabelValue 可选填。如果 LabelValue 为空，则 Kubernetes Label 中包含 LabelKey 的容器都匹配。如果 LabelValue 不为空，则 Kubernetes Label 中包含 LabelKey=LabelValue 的容器才匹配。 LabelValue 默认为字符串匹配，即只有 LabelValue 和 Kubernetes Label 的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如设置 LabelKey 为`app`，设置 LabelValue 为`^(test1\|test2)$`，表示匹配 Kubernetes Label 中包含 app:test1、app:test2 的容器。多个白名单之间为或关系，即只要 Kubernetes Label 满足任一白名单即可匹配。
ExcludeK8sLabel	Map，其中 LabelKey 和 LabelValue 为 String 类型	否	空		通过 Kubernetes Label（定义在 template.metadata 中）黑名单排除不采集的容器。如果您要设置 Kubernetes Label 黑名单，那么 LabelKey 必填，LabelValue 可选填。如果 LabelValue 为空，则 Kubernetes Label 中包含 LabelKey 的容器都被排除。如果 LabelValue 不为空，则 Kubernetes Label 中包含 LabelKey=LabelValue 的容器才会被排除。 LabelValue 默认为字符串匹配，即只有 LabelValue 和 Kubernetes Label 的值完全相同才会匹配。如果该值以`^`开头并且以`$`结尾，则为正则匹配。例如设置 LabelKey 为`app`，设置 LabelValue 为`^(test1\|test2)$`，表示匹配 Kubernetes Label 中包含 app:test1、app:test2 的容器。多个黑名单之间为或关系，即只要 Kubernetes Label 满足任一黑名单对即可被排除。
K8sNamespaceRegex	String	否	空	^(default\|nginx)$	通过 Namespace 名称指定采集的容器，支持正则匹配。例如设置为`^(default\|nginx)$`，表示匹配 nginx 命名空间、default 命名空间下的所有容器。
K8sPodRegex	String	否	空	^(nginx-log-demo.*)$	通过 Pod 名称指定待采集的容器，支持正则匹配。例如设置为`^(nginx-log-demo.*)$`，表示匹配以 nginx-log-demo 开头的 Pod 下的所有容器。
K8sContainerRegex	String	否	空	^(container-test)$	通过容器名称指定待采集的容器（Kubernetes 容器名称是定义在 spec.containers 中），支持正则匹配。例如设置为`^(container-test)$`，表示匹配所有名为 container-test 的容器。

数据处理参数

参数	类型	是否必填	默认值	示例	说明
BeginLineRegex	String	否	空		行首匹配的正则表达式。该配置项为空，表示单行模式。如果该表达式匹配某行的开头，则将该行作为一条新的日志，否则将此行拼接到上一条日志。
BeginLineCheckLength	Integer	否	空		行首匹配的长度，单位：字节。默认取值为 10×1024 字节。如果行首匹配的正则表达式在前 N 个字节即可体现，推荐设置此参数，提升行首匹配效率。
BeginLineTimeoutMs	Integer	否	空		行首匹配的超时时间，单位：毫秒。默认取值为 3000 毫秒。如果 3000 毫秒内没有出现新日志，则结束匹配，将最后一条日志上传到日志服务。
MaxLogSize	Integer	否	空		日志最大长度，默认取值为 0，单位：字节。默认取值为 512×1024 字节。如果日志长度超过该值，则不再继续查找行首，直接上传。
ExternalK8sLabelTag	Map，其中 LabelKey 和 LabelValue 为 String 类型	否	空		设置 Kubernetes Label（定义在 template.metadata 中）日志标签后，iLogtail 将在日志中新增 Kubernetes Label 相关字段。例如设置 LabelKey 为 app，LabelValue 为`k8s_label_app`，当 Pod 中包含 Label `app=serviceA`时，会将该信息 iLogtail 添加到日志中，即添加字段 k8s_label_app: serviceA；若不包含名为 app 的 label 时，添加空字段 k8s_label_app: 。
ExternalEnvTag	Map，其中 EnvKey 和 EnvValue 为 String 类型	否	空		设置容器环境变量日志标签后，iLogtail 将在日志中新增容器环境变量相关字段。例如设置 EnvKey 为`VERSION`，EnvValue 为`env_version`，当容器中包含环境变量`VERSION=v1.0.0`时，会将该信息以 tag 形式添加到日志中，即添加字段 env_version: v1.0.0；若不包含名为 VERSION 的环境变量时，添加空字段 env_version: 。

数据处理环境变量

环境变量

类型

是否必填

默认值

示例

说明

ALIYUN_LOG_ENV_TAGS

String

否

空

设置全局环境变量日志标签后，iLogtail 将在日志中新增 iLogtail 所在容器环境变量相关字段。多个环境变量名以|分隔。

例如设置为 node_name|node_ip，当 iLogtail 容器中暴露相关环境变量时，会将该信息以 tag 形式添加到日志中，即添加字段 node_ip:172.16.0.1 和 node_name:worknode。

配置示例

apiVersion: telemetry.alibabacloud.com/v1alpha1
# 创建一个 ClusterAliyunPipelineConfig
kind: ClusterAliyunPipelineConfig
metadata:
  # 设置资源名，在当前Kubernetes集群内唯一。该名称也是创建出的Logtail采集配置名。如果名称重复则不会生效。
  name: example-k8s-file
spec:
  # 指定目标project
  project:
    name: k8s-log-test
  # 创建用于存储日志的 Logstore
  logstores:
    - name: k8s-stdout
  # 定义Logtail采集配置
  config:
    # 日志样例（可不填写）
    sample: |
      2024-06-19 16:35:00 INFO test log
      line-1
      line-2
      end
    # 定义输入插件
    inputs:
          # 使用service_docker_stdout插件采集容器标准输出
      - Type: service_docker_stdout
        Stdout: true
        Stderr: true
        # 配置容器信息过滤条件，多个选项之间为“且”的关系。
        # 指定待采集容器所在 Pod 所属的命名空间，支持正则匹配。
        K8sNamespaceRegex: "^(default)$"
        # 启用容器元数据预览
        CollectContainersFlag: true
        # 采集Pod标签符合条件的容器。多个条目之间为或的关系
        IncludeK8sLabel:
          app: ^(.*test.*)$
        # 配置多行切分配置，单行日志采集无效配置
        # 配置行首正则表达式
        BeginLineRegex: \d+-\d+-\d+.*
    # 定义输出插件
    flushers:
      # 使用flusher_sls插件输出到指定Logstore。
      - Type: flusher_sls
        # 需要确保该 Logstore 存在
        Logstore: k8s-stdout
        # 需要确保 endpoint 正确
        Endpoint: cn-hangzhou.log.aliyuncs.com
        Region: cn-hangzhou
        TelemetryType: logs

预览容器元信息

说明

创建Logtail配置后，您可以在Logtail配置页面查看容器元信息以及容器未匹配过滤条件的原因。

在Project列表中，单击您在创建Logtail配置所使用的Project。
在日志存储 > 日志库页签中，选择您在创建Logtail配置所使用的Logstore，然后单击Logstore左侧的>，选择数据接入 > Logtail配置。
在Logtail配置列表中，单击目标Logtail配置。
在Logtail配置页面中，单击编辑。
打开启用容器元信息预览开关。
单击容器元信息预览。
在容器预览对话框中，查看容器的元信息。
- 匹配容器页签中展示匹配您所设置的过滤条件的容器的元信息。
- 全量容器页签中展示当前Kubernetes集群中所有容器的元信息以及容器未匹配过滤条件的原因。

日志字段

Kubernetes集群的每条日志默认上传的字段如下所示。

字段名称	说明
_time_	日志采集时间。
_source_	日志源类型，stdout或stderr。
_image_name_	镜像名
_container_name_	容器名
_pod_name_	Pod名
_namespace_	Pod所在的命名空间
_pod_uid_	Pod的唯一标识

问题排查

当您使用Logtail采集容器（标准容器、Kubernetes）日志遇到异常情况时，您可以参见如下内容进行排查。

当标准错误日志与访问日志格式不同，无法正常解析时，建议针对content加索引去搜索error。日志服务不支持使用提取字段的插件来做解析。更多信息，请参见创建索引。