Kubernetes标准输出(新版)

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

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

功能特点

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

  • 支持采集标准输出信息(stdout)和标准出错信息(stderr)。

  • 支持通过容器Label白名单指定待采集的容器。

  • 支持通过容器Label黑名单排除不需要采集的容器。

  • 支持通过环境变量白名单指定待采集的容器。

  • 支持通过环境变量黑名单排除不需要采集的容器。

  • 支持采集多行日志(例如Java Stack日志)。

  • 支持上报容器日志时自动关联Meta信息(例如容器名、镜像、Pod、Namespace、环境变量等)。

  • 当容器运行于Kubernetes时,Logtail还具有以下功能。

    • 支持通过Kubernetes Namespace名称、Pod名称、容器名称指定待采集的容器。

    • 支持通过Kubernetes Label白名单指定待采集的容器。

    • 支持通过Kubernetes Label黑名单排除不需要采集的容器。

    • 支持上报容器日志时自动关联Kubernetes Label信息。

使用限制

  • 新版标准输出采集插件目前仅支持Linux操作系统,并且不支持通过主机方式采集标准输出日志,支持Logtail2.1.5及以上版本。版本查看与升级,请参见安装Logtail组件(阿里云Kubernetes集群)安装Logtail组件(自建Kubernetes集群)

  • Logtail支持DockerContainerd两种容器引擎的数据采集,访问路径说明如下:

    • Docker:Logtail通过/run/docker.sock访问Docker,请确保该路径存在且具备访问权限。

    • Containerd:Logtail通过/run/containerd/containerd.sock访问Containerd,请确保该路径存在且具备访问权限。

  • 每条日志读取的最大值:默认值:524288(512 KB),最大值:8388608(8 MB)。单位:Byte。 如果您的单条日志超过524288 Byte,可给Logtail容器添加环境变量 max_read_buffer_size 进行修改。

  • 采集停止策略:当容器被停止后,Logtail监听到容器die的事件后会停止采集该容器的标准输出。如果此时采集出现延迟,则可能丢失停止前的部分输出。

  • Docker容器引擎限制:目前标准输出采集仅支持JSON类型的日志驱动。

  • 数据处理:采集到的数据默认保存在content字段中。Logtail对于采集到的容器标准输出,支持数据处理。更多信息,请参见使用Logtail插件处理数据。新版标准输出采集插件支持原生处理插件(性能高,支持多线程)和扩展插件的组合使用。

  • CRD方式支持AliyunPipelineConfig。

  • API方式支持CreateLogtailPipelineConfig - 创建Logtail流水线配置UpdateLogtailPipelineConfig - 更新Logtail流水线配置等流水线配置。

功能优势

相较于旧版标准输出采集,新版标准输出的优势如下:

类型

新版标准输出插件优势(C++版本)

性能大幅提升

采用C++重构,性能较旧版标准输出插件提升100%以上。

支持原生插件处理数据,多线程并行处理,充分利用系统资源。

原生插件与Go插件灵活组合。

更强的可靠性

支持标准输出日志轮转队列,日志采集机制和文件采集机制统一,在标准输出日志快速轮转时的场景可靠性高。

更低的资源消耗

CPU使用率降低20%。

内存占用减少20%。

运维一致性

新版标准输出采集插件的参数和文件采集插件的参数进行了统一。

容器元信息字段命名和Tag日志存储位置,与文件采集场景进行了统一,消费端只需维护同套处理逻辑。

配置说明

表单配置(控制台配置)

参数

说明

标准输出

打开标准输出后,Logtail将采集容器标准输出。

标准错误

打开标准错误后,Logtail将采集容器标准错误。

允许标准输出多次采集

默认情况下,一个容器的标准输出日志只能匹配一个Logtail新版标准输出采集配置。如果标准输出需要被多个新版标准输出采集配置采集,需打开允许标准输出多次采集开关。

启用容器元信息预览

打开启用容器元信息预览后,您可以在创建Logtail配置后,查看容器元信息,包括匹配容器信息和全量容器信息。

容器过滤

  • 过滤条件说明

重要
  • 容器LabelDocker inspect中的Label,不是Kubernetes中的Label。如何获取,请参见获取容器Label

  • 环境变量为容器启动中配置的环境变量信息。如何获取,请参见获取容器环境变量

  • Kubernetes场景下,推荐使用Kubernetes层级的信息(K8s Pod名称正则匹配K8s Namespace正则匹配K8s容器名称正则匹配K8s Pod标签白名单等)进行容器过滤。

  1. Kubernetes中的Namespace和容器名称会映射到容器Label中,分别为io.kubernetes.pod.namespaceio.kubernetes.container.name,推荐使用这两个容器Label进行容器过滤。例如,某Pod所属的命名空间为backend-prod,容器名为worker-server,如果您要采集包含该容器的日志,可以设置容器Label白名单为io.kubernetes.pod.namespace : backend-prodio.kubernetes.container.name : worker-server

  2. 如果以上两个容器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的值完全相同才会匹配。如果该值以^开头并且以$结尾,则为正则匹配。例如:配置LabelKeyio.kubernetes.container.name,配置LabelValue^(nginx|cube)$,表示可匹配名为nginx、cube的容器。

多个白名单之间为或关系,即只要容器Label满足任一白名单即可被匹配。

容器label黑名单

容器Label黑名单,用于排除不采集的容器。默认为空,表示不排除任何容器。如果您要设置容器Label黑名单,那么LabelKey必填,LabelValue可选填。

  • 如果LabelValue为空,则容器Label中包含LabelKey的容器都将被排除。

  • 如果LabelValue不为空,则容器Label中包含LabelKey=LabelValue的容器才会被排除。

    LabelValue默认为字符串匹配,即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以^开头并且以$结尾,则为正则匹配。例如:设置LabelKeyio.kubernetes.container.name,设置LabelValue^(nginx|cube)$,表示可匹配名为nginx、cube的容器。

多个黑名单之间为或关系,即只要容器Label满足任一黑名单对即可被排除。

环境变量白名单

环境变量白名单,用于指定待采集的容器。默认为空,表示采集所有容器的标准输出。如果您要设置环境变量白名单,那么EnvKey必填,EnvValue可选填。

  • 如果EnvValue为空,则容器环境变量中包含EnvKey的容器都匹配。

  • 如果EnvValue不为空,则容器环境变量中包含EnvKey=EnvValue的容器才匹配。

    EnvValue默认为字符串匹配,即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以^开头并且以$结尾,则为正则匹配,例如:设置EnvKeyNGINX_SERVICE_PORT,设置EnvValue^(80|6379)$,表示可匹配服务端口为80、6379的容器。

多个白名单之间为或关系,即只要容器的环境变量满足任一键值对即可被匹配。

环境变量黑名单

环境变量黑名单,用于排除不采集的容器。默认为空,表示不排除任何容器。如果您要设置环境变量黑名单,那么EnvKey必填,EnvValue可选填。

  • 如果EnvValue为空,则容器环境变量中包含EnvKey的容器的日志都将被排除。

  • 如果EnvValue不为空,则容器环境变量中包含EnvKey=EnvValue的容器才会被排除。

    EnvValue默认为字符串匹配,即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以^开头并且以$结尾,则为正则匹配,例如:设置EnvKeyNGINX_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默认为字符串匹配,即只有LabelValueKubernetes Label的值完全相同才会匹配。如果该值以^开头并且以$结尾,则为正则匹配。例如设置LabelKeyapp,设置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默认为字符串匹配,即只有LabelValueKubernetes Label的值完全相同才会匹配。如果该值以^开头并且以$结尾,则为正则匹配。例如设置LabelKeyapp,设置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,设置tagenv_version,当容器中包含环境变量VERSION=v1.0.0时,会将该信息添加到日志中,即添加字段__tag__:__env_version__: v1.0.0

Pod标签相关

设置Kubernetes Pod扩展字段后,日志服务将在日志中新增Kubernetes Pod相关字段。例如设置Pod标签名app,设置tagk8s_pod_app,当Kubernetes中包含Labelapp=serviceA时,会将该信息添加到日志中,即添加字段__tag__:__k8s_pod_app__: serviceA

首次采集大小

配置首次生效时,标准输出日志文件的起始采集位置距离文件结尾的大小。首次采集大小设定值为1024 KB。

  • 首次采集时,如果文件小于1024 KB,则从文件内容起始位置开始采集。

  • 首次采集时,如果文件大于1024 KB,则从距离文件末尾1024 KB的位置开始采集。

您可以通过此处修改首次采集大小,取值范围为0~10485760,单位为KB。

高级参数

Logtail配置的部分参数需要手动输入,请参见创建Logtail流水线配置

  • 配置示例image

CRD-AliyunPipelineConfig

警告

如果使用AliyunPipelineConfig,需要alibaba-log-controller的镜像版本不低于0.5.1。

参数

类型

是否必填

默认值

说明

Type

string

/

插件类型。固定为input_container_stdio。

IgnoringStdout

Boolean

false

是否忽略标准输出stdout。

IgnoringStderr

Boolean

false

是否忽略标准出错信息stderr。

TailSizeKB

uint

1024

配置首次生效时,标准输出文件的起始采集位置距离文件结尾的大小。如果文件大小小于该值,则从头开始采集,取值范围为0~10485760KB。

Multiline

object

多行聚合选项,详见1:多行聚合选项

ContainerFilters

object

容器过滤选项。多个选项之间为“且”的关系,详见2:容器过滤选项

ExternalK8sLabelTag

map

对于部署于K8s环境的容器,需要在日志中额外添加的与Pod标签相关的tag。map中的keyPod标签名,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:

FlushTimeoutSecs

uint

5

当文件超过指定时间未出现新的完整日志时,将当前读取缓存中的内容作为一条日志输出。

AllowingIncludedByMultiConfigs

bool

false

是否允许当前配置采集其它配置已匹配的容器标准输出日志。

  • 1:多行聚合选项

    参数

    类型

    是否必填

    默认值

    说明

    Mode

    string

    custom

    多行聚合模式。仅支持custom。

    StartPattern

    string

    Multiline.Mode取值为custom时必填

    行首正则表达式。

    UnmatchedContentTreatment

    string

    single_line

    对于无法匹配的日志段的处理方式,可选值如下:

    • discard:丢弃。

    • single_line:将不匹配日志段的每一行各自存放在一个单独的事件中。

  • 2:容器过滤选项

    参数

    类型

    是否必填

    默认值

    说明

    K8sNamespaceRegex

    string

    对于部署于K8s环境的容器,指定待采集容器所在Pod所属的命名空间条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。

    K8sPodRegex

    string

    对于部署于K8s环境的容器,指定待采集容器所在Pod的名称条件。如果未添加该参数,则表示采集所有容器。支持正则匹配。

    IncludeK8sLabel

    map

    对于部署于K8s环境的容器,指定待采集容器所在Pod的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map中的keyPod标签名,valuePod标签的值,说明如下:

    • 如果map中的value为空,则Pod标签中包含以key为键的Pod都会被匹配;

    • 如果map中的value不为空,则:

      • value^开头并且以$结尾,则当pod标签中存在以key为标签名且对应标签值能正则匹配value的情况时,相应的pod会被匹配。

      • 其他情况下,当Pod标签中存在以key为标签名且以value为标签值的情况时,相应的Pod会被匹配。

    ExcludeK8sLabel

    map

    对于部署于K8s环境的容器,指定需要排除采集容器所在Pod的标签条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map中的keyPod标签名,valuePod标签的值,说明如下:

    • 如果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为键的容器都会被匹配;

    • 如果map中的value不为空,则:

      • value^开头并且以$结尾,则当容器环境变量中存在以key为环境变量名且对应环境变量值能正则匹配value的情况时,相应的容器会被匹配。

      • 其他情况下,当容器环境变量中存在以key为环境变量名且以value为环境变量值的情况时,相应的容器会被匹配。

    ExcludeEnv

    map

    指定需要排除采集容器的环境变量条件。多个条件之间为“或”的关系,如果未添加该参数,则表示采集所有容器。支持正则匹配。 map中的key为环境变量名,value为环境变量的值,说明如下:

    • 如果map中的value为空,则容器环境变量中包含以key为键的容器都会被匹配;

    • 如果map中的value不为空,则:

      • value^开头并且以$结尾,则当容器环境变量中存在以key为环境变量名且对应环境变量值能正则匹配value的情况时,相应的容器会被匹配。

      • 其他情况下,当容器环境变量中存在以key为环境变量名且以value为环境变量值的情况时,相应的容器会被匹配。

    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为标签值的情况时,相应的容器会被匹配。

  • 配置示例

    AliyunPipelineConfig管理采集配置

    apiVersion: telemetry.alibabacloud.com/v1alpha1
    # 创建一个 ClusterAliyunPipelineConfig
    kind: ClusterAliyunPipelineConfig
    metadata:
      # 设置资源名,在当前Kubernetes集群内唯一。该名称也是创建出的iLogtail采集配置名
      name: example-k8s-stdout
    spec:
      # 指定目标project
      project:
        name: k8s-log-clusterid
      # 创建用于存储日志的 Logstore
      logstores:
        - name: k8s-stdout
      # 定义iLogtail采集配置
      config:
        # 日志样例(可不填写)
        sample: |
          2024-06-19 16:35:00 INFO test log
          line-1
          line-2
          end
          # 定义输入插件
        inputs:
          # 使用input_container_stdio插件采集容器标准输出
          - Type: input_container_stdio
            # 采集stdout日志
            IgnoringStdout: false
            # 不采集stderr日志
            IgnoringStderr: true
            # 配置容器信息过滤条件,多个选项之间为“且”的关系。
            ContainerFilters:
              # 指定待采集容器所在 Pod 所属的命名空间,支持正则匹配。
              K8sNamespaceRegex: "^(default)$"
              # 指定待采集容器的名称,支持正则匹配。
              K8sContainerRegex: "^(.*app.*)$"
            # 配置多行切分配置
            # 配置行首正则表达式
            Multiline:
              Mode: custom
              StartPattern: \d+-\d+-\d+.*
              UnmatchedContentTreatment: single_line
        # 定义输出插件
        flushers:
          # 使用flusher_sls插件输出到指定Logstore。
          - Type: flusher_sls
            Logstore: k8s-stdout
            Endpoint: cn-hangzhou.log.aliyuncs.com
            Region: cn-hangzhou
            TelemetryType: logs

预览容器元信息

说明

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

  1. Project列表中,单击您在创建Logtail配置所使用的Project。

  2. 日志存储 > 日志库页签中,选择您在创建Logtail配置所使用的Logstore,然后单击Logstore左侧的>,选择数据接入 > Logtail配置

  3. Logtail配置列表中,单击目标Logtail配置。

  4. Logtail配置页面中,单击编辑

  5. 打开启用容器元信息预览开关。

  6. 单击容器元信息预览

  7. 容器预览对话框中,查看容器的元信息。

    • 匹配容器页签中展示匹配您所设置的过滤条件的容器的元信息。

    • 全量容器页签中展示当前Kubernetes集群中所有容器的元信息以及容器未匹配过滤条件的原因。

日志字段

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

字段名称

说明

_time_

日志采集时间。

_source_

日志源类型,stdoutstderr。

__tag__:_image_name_

镜像名

__tag__:_container_name_

容器名

__tag__:_pod_name_

Pod

__tag__:_namespace_

Pod所在的命名空间

__tag__:_pod_uid_

Pod的唯一标识

问题排查

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

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