Vectorkubernetes_logs源深度解析Kubernetes 集群 Pod 日志采集与元数据富化实战指南【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本篇技术指南聚焦于 Vector 可观测性数据管道中的kubernetes_logs源组件讲解如何以 DaemonSet 方式部署在集群每个节点上从/var/log/pods目录持续采集 Pod 日志并通过 Kubernetes API 自动富化 Pod、Namespace、Node 等元数据。读完本文你将掌握该源组件的完整配置参数、过滤与排除机制、Docker/CRI 日志格式解析原理、部分消息合并逻辑以及 RBAC 权限配置与资源调优方法。组件定位与工作方式kubernetes_logs是 Vector 提供的稳定级development: stable日志源组件负责从运行 Vector 的 Kubernetes Node 主机上采集 Pod 日志。它以 DaemonSet 形式在每个节点部署一个 Agent读取 kubelet 写入宿主机/var/log/pods目录下的容器日志文件并自动通过 Kubernetes API 为每条日志补充丰富的元数据上下文。该组件属于尽力交付best effort模式采用流式输出egress method: stream自身不维护状态stateful: false仅依赖文件系统的 checkpoint 机制恢复读取进度。从源码结构看该源组件由多个模块协同工作位于 src/sources/kubernetes_logs/ 目录mod.rs组件Config定义与Source主流程reflector 初始化、文件服务器配置、事件管道装配k8s_paths_provider.rs根据 Pod 元数据实时推导需要读取的日志文件路径pod_metadata_annotator.rs/namespace_metadata_annotator.rs/node_metadata_annotator.rs分别向事件注入 Pod、Namespace、Node 元数据parser/负责 Docker json-file 与 CRI 两种容器日志格式的解析partial_events_merger.rs将容器运行时拆分的部分消息合并为完整日志。部署前提与要求根据组件元数据 kubernetes_logs.cue 中的support.requirements该源组件有两个硬性前提需要指定版本的 Kubernetes 集群以当前仓库 CUE 数据中的services.kubernetes.versions为准必须拥有对宿主机/var/log/pods目录的读权限——在集群内运行时通过挂载hostPath卷提供。同时存在一条明确警告该组件仅在 Linux 上经过测试在 Windows 集群上的表现无法保证。仓库自带的 DaemonSet 清单 daemonset.yaml 展示了完整挂载方式将宿主机的/var/log/与/var/lib以hostPath只读方式挂载进容器同时挂载/host/proc与/host/sys供系统相关采集使用。关键的环境变量包括env: - name: VECTOR_SELF_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeNameVECTOR_SELF_NODE_NAME通过 Kubernetes Downward API 注入当前节点名这正是配置项self_node_name的默认取值来源见下文。最小可用配置该源组件无需任何必填配置项即可运行官方示例配置如下sources: my_source_id: type: kubernetes_logs将其接入下游 sink 的完整示例sources: k8s_logs: type: kubernetes_logs sinks: console: type: console inputs: [k8s_logs] encoding: codec: json从GenerateConfig实现mod.rs可见生成的最小配置会显式写入self_node_name: ${VECTOR_SELF_NODE_NAME}与auto_partial_merge: true其余参数全部采用默认值。完整配置参数详解以下参数定义来源于自动生成的配置元数据 generated/kubernetes_logs.cue并与源码Config结构mod.rs一一对应。连接与 API 相关参数类型默认值说明self_node_namestring${VECTOR_SELF_NODE_NAME}当前运行节点名。默认通过环境变量由 Kubernetes 在 Pod 创建时注入若配置为空或等于默认模板则回退读取VECTOR_SELF_NODE_NAME环境变量未设置会直接报错kube_config_filestring无可选的 kubeconfig 文件路径。未设置时使用集群内in-cluster配置连接 APIuse_apiserver_cacheboolfalse是否允许对 kube-apiserver 的请求由本地缓存服务。开启后 watcher 使用ListSemantic::Any语义并增大分页见源码watcher::Config构造extra_field_selectorstring附加的 Pod 字段选择器field selector在内置 Node 过滤之外使用例如metadata.name!pod-name-to-exclude,metadata.namemypodextra_label_selectorstring附加的 Pod 标签选择器label selector例如my_custom_label!my_value,my_other_custom_labelmy_valueextra_namespace_label_selectorstring附加的 Namespace 标签选择器insert_namespace_fieldsbooltrue是否富化 Namespace 字段。设为false可停止拉取 Namespace 列表降低 kube-apiserver 负载与 DaemonSet 内存占用在 Namespace 很多的集群中尤其有效delay_deletion_msuint (毫秒)60000收到 Pod 删除事件后延迟多久才从元数据缓存中移除该 Pod 的元数据。延迟越长Pod 删除后仍能持续富化其日志例如崩溃现场若元数据已被移除日志将以未富化状态转发并产生告警文件读取相关参数类型默认值说明data_dirstring全局data_dir持久化文件 checkpoint 位置的目录指定后会尝试自动创建运行用户需具备写权限include_paths_glob_patternsarray[**/*]按文件名与路径包含 Kubernetes 日志文件的 glob 模式列表默认包含全部exclude_paths_glob_patternsarray[**/*.gz, **/*.tmp]按文件名与路径排除日志文件的 glob 模式列表。默认忽略压缩文件与临时文件。先评估 include 再评估 excluderead_fromstringbeginning读取新文件时的起始位置beginning从头读或end从文件当前末尾开始oldest_firstbooltrue优先排空最旧文件而非在所有被监控文件中公平分配读取能力max_read_bytesuint (字节)2048单个文件一次最多读取的字节数之后切换到下一个文件用于在文件间均衡读取oldest_first: true时该参数不生效ignore_older_secsuint (秒)无忽略数据修改时间早于该秒数的文件glob_minimum_cooldown_msuint (毫秒)60000轮询文件系统发现新文件的间隔。该值同时与底层文件服务器的校验和落盘耦合设得过低会引入显著开销rotate_wait_secsuint (秒)9223372036854775807轮转日志文件后保持句柄打开的时间默认值表示无限制fingerprint_linesuint (行)1生成文件校验和指纹时读取的行数若文件行数少于该值则完全不会读取max_line_bytesuint (字节)32768单行最大字节数超过则丢弃用于防止畸形行或误读错误文件max_merged_line_bytesuint (字节)无合并部分消息后单行允许的最大字节数仅在auto_partial_merge为 true 时生效max_merged_line_actionstringdrop合并行超过max_merged_line_bytes时的行为drop丢弃整行默认truncate截断到限制并追加..TRUNCATED后缀后作为部分事件输出ingestion_timestamp_fieldstring无覆盖写入事件中的采集时间戳字段名可用于计算日志写入到被处理之间的延迟例如.ingest_timestamp或ingest_tstimezonestring无无显式时区时间戳的默认时区如local、America/New_York、EST5EDTinternal_metricsobject无基于文件组件内部指标的配置元数据富化字段映射通过pod_annotation_fields、namespace_annotation_fields、node_annotation_fields三个对象可以自定义元数据写入事件中的字段路径将值设为可抑制不输出该字段。各选项默认值如下pod_annotation_fields旧名annotation_fields源码中以#[serde(alias annotation_fields)]兼容子选项默认字段路径container_id.kubernetes.container_idcontainer_image.kubernetes.container_imagecontainer_image_id.kubernetes.container_image_idcontainer_name.kubernetes.container_namepod_annotations.kubernetes.pod_annotationspod_ip.kubernetes.pod_ippod_ips.kubernetes.pod_ipspod_labels.kubernetes.pod_labelspod_name.kubernetes.pod_namepod_namespace.kubernetes.pod_namespacepod_node_name.kubernetes.pod_node_namepod_owner.kubernetes.pod_ownerpod_uid.kubernetes.pod_uidnamespace_annotation_fieldsnamespace_labels默认.kubernetes.namespace_labels。node_annotation_fieldsnode_labels默认.kubernetes.node_labels。输出数据结构kubernetes_logs输出的是日志事件每条事件对应Pod 日志文件中的一行。完整字段定义见 kubernetes_logs.cue 中的output.logs.line。必选字段字段类型说明filestring源文件绝对路径形如/var/log/pods/pod-namespace_pod-name_pod-uid/container/1.logmessagestringPod 日志文件的原始行内容source_typestring固定值kubernetes_logsstreamstring日志行写入的流名称stdout或stderrtimestamptimestampKubernetes 处理该事件的确切时间可选元数据字段字段类型说明kubernetes.container_idstring容器 ID例如docker://f24c81dcd531c5d353751c77fe0556a4f602f7714c72b9a58f9b26c0628f1fa6kubernetes.container_imagestring容器镜像名例如busybox:1.30kubernetes.container_image_idstring容器镜像 ID含 digestkubernetes.container_namestring容器名例如corednskubernetes.namespace_labelsobjectNamespace 上的标签集合例如{mylabel: myvalue}kubernetes.pod_ipstringPod 的 IPv4 地址例如192.168.1.1kubernetes.pod_ipsstringPod 的 IPv4 与 IPv6 地址集合kubernetes.pod_labelsobjectPod 标签集合kubernetes.pod_annotationsobjectPod 注解集合kubernetes.pod_namestringPod 名称例如coredns-qwertyuiop-qwertkubernetes.pod_namespacestringPod 所在 Namespace例如kube-systemkubernetes.pod_node_namestringPod 所在节点名例如minikubekubernetes.pod_ownerstringPod 的属主引用例如ReplicaSet/coredns-565d847f94kubernetes.pod_uidstringPod UID例如ba46d8c9-9541-4f6b-bbf9-d23b36f2f136官方示例输出CUE 数据中给出了完整样例kubernetes_logs.cue输入一行 kubelet 错误日志后输出事件形如{ file: /var/log/pods/kube-system_storage-provisioner_93bde4d0-9731-4785-a80e-cd27ba8ad7c2/storage-provisioner/1.log, kubernetes.container_image: gcr.io/k8s-minikube/storage-provisioner:v3, kubernetes.container_name: storage-provisioner, kubernetes.namespace_labels: { kubernetes.io/metadata.name: kube-system }, kubernetes.pod_ip: 192.168.1.1, kubernetes.pod_ips: [192.168.1.1, ::1], kubernetes.pod_labels: { addonmanager.kubernetes.io/mode: Reconcile, gcp-auth-skip-secret: true, integration-test: storage-provisioner }, kubernetes.pod_annotations: { prometheus.io/scrape: false }, kubernetes.pod_name: storage-provisioner, kubernetes.pod_namespace: kube-system, kubernetes.pod_node_name: minikube, kubernetes.pod_uid: 93bde4d0-9731-4785-a80e-cd27ba8ad7c2, message: F1015 11:01:46.499073 1 main.go:39] error getting server version: ..., source_type: kubernetes_logs, stream: stderr, timestamp: 2020-10-15T11:01:46.499555308Z }过滤与排除机制kubernetes_logs提供了多层过滤手段官方文档将其总结为 Filtering 一节kubernetes_logs.cue基于标签/注解的内置排除规则Pod 排除默认启用默认跳过带有vector.dev/exclude: true标签的 Pod 的日志。可以通过extra_label_selector、extra_field_selector追加额外排除规则。Namespace 排除默认启用默认跳过带有vector.dev/exclude: true标签的 Namespace 中所有 Pod 的日志。可通过extra_namespace_label_selector追加规则。Container 排除注解驱动可为单个 Pod 添加注解vector.dev/exclude-containers值用逗号分隔需要排除的容器名vector.dev/exclude-containers: container1,container2Vector 将跳过该 Pod 中container1与container2的日志而其余容器的日志照常采集。这也解释了仓库自带 DaemonSet 清单中为何给 Vector 自身 Pod 打上vector.dev/exclude: true标签见 daemonset.yaml防止 Vector 采集自己的日志形成回环。基于路径 glob 的过滤include_paths_glob_patterns按文件名与路径包含日志文件默认**/*包含全部exclude_paths_glob_patterns按文件名与路径排除日志文件默认排除**/*.gz与**/*.tmp两者同时配置时先执行 include 再执行 exclude。Globbing 与文件发现日志文件的发现依赖 glob 轮询轮询间隔由glob_minimum_cooldown_ms控制。在文件轮转迅速的集群环境中官方建议降低glob_minimum_cooldown以便在日志文件被压缩前及时捕捉Globbing 一节kubernetes_logs.cue。选择器的源码级实现从源码 mod.rs 可以看到这些选择器最终被组装进三个独立的 reflector watcherPod watcherfield_selector由self_node_name与extra_field_selector拼接label_selector合并vector.dev/exclude内置规则与extra_label_selectorNamespace watcher仅当insert_namespace_fields: true时启动使用namespace_label_selectorNode watcher使用node_selector精确匹配self_node_name。三个 watcher 均通过kube库的reflectorMetaCache构建本地缓存并以delay_deletion延迟删除缓存条目。Pod 移除后 Vector 仍会继续采集其日志一段时间以获取崩溃细节等关键数据Pod removal 一节kubernetes_logs.cue。日志格式解析Docker 与 CRIKubernetes 容器运行时可能使用 Dockerjson-file 驱动或 CRI如 containerd、CRI-O两种日志格式。Parser模块采用首行格式探测 状态固化的策略parser/mod.rs当收到第一条事件时检查 message 的首字节是否为{若以{开头 → 判定为Docker 格式后续全部走 Docker 解析器否则 → 判定为CRI 格式后续全部走 CRI 解析器。Docker json-file 格式Docker 解析器parser/docker.rs期望日志为 JSON Lines每条形如{log: The actual log line\n, stream: stderr, time: 2016-10-05T00:00:30.082640485Z}解析时分别处理三个键log写入 message 字段去除末尾换行符、stream写入stream字段、time解析为 RFC3339 时间戳。对于部分消息partial message源码采用启发式判断当消息长度恰好等于 Docker 单条消息上限DOCKER_MESSAGE_SPLIT_THRESHOLD 16 * 1024字节时视为部分消息并写入_partial元数据标记若消息虽达上限但以换行符结尾则视为完整消息parser/docker.rs。CRI 格式CRI 解析器parser/cri.rs处理 kubelet CRI 日志格式每条为空格分隔的文本行等价于正则(?-u)^(?Ptimestamp.*) (?Pstream(stdout|stderr)) (?Pmultiline_tag(P|F)) (?Pmessage.*)(?Pnew_line_tag\n?)$示例2016-10-06T00:17:09.669794202Z stdout F The content of the log entry 1 2016-10-06T00:17:09.669794202Z stdout P First line of log entry 2其中multiline_tag为PPartial时标记为部分消息为FFull时是完整消息timestamp按%格式解析后转为 UTC 时间戳。测试用例覆盖了非 UTF-8 消息、超长部分消息等边界场景parser/cri.rs。部分消息自动合并默认情况下auto_partial_merge: trueVector 会自动合并被容器运行时按大小拆分例如 Docker 16KiB 上限的部分消息。合并逻辑位于 partial_events_merger.rs以file字段为键对部分事件分桶缓存合并时把各段消息字节拼接若超过max_merged_line_bytes则按max_merged_line_action执行drop或truncate截断并追加..TRUNCATED后缀桶内事件超过 30 秒无新数据即过期。相应的丢弃/截断都会产生内部指标见下文。对于栈追踪等需要自定义合并逻辑的场景官方建议关闭自动合并改用reduce转换器transform进行定制化处理Partial message merging 一节kubernetes_logs.cue。状态管理与断点续传作为 Agent 角色部署时Vector 将状态保存在宿主机映射目录下的静态路径中State management 一节kubernetes_logs.cue。从源码看Checkpointer::new(data_dir)以data_dir为根目录持久化文件读取位置FileServer配置ignore_checkpoints: false因此DaemonSet 重新部署后能从上次中断的位置继续读取不会重复采集或遗漏。仓库 DaemonSet 清单通过hostPath将宿主机/var/lib/vector挂载到容器的/vector-data-dir并作为数据卷确保 checkpoint 在 Pod 重建后依然存在daemonset.yaml。Kubernetes API 通信与 RBAC 权限Vector 通过 Kubernetes API 富化日志具体使用/api/v1/pods、/api/v1/namespaces、/api/v1/nodes三个端点执行list与watchKubernetes API access control 一节kubernetes_logs.cue。为保证通信安全可靠Vector 实现了完善的退避desync handling/backoff机制避免压垮 API server。在启用 RBAC 的现代集群中需要为 Vector 授予相应权限。仓库自带的 rbac.yaml 定义了最小权限集rules: - apiGroups: [] resources: [namespaces, nodes, pods] verbs: [list, watch]ClusterRoleBinding 将该权限绑定到 ServiceAccountserviceaccount.yaml。要点总结RBAC 集群开箱即用上述清单已包含全部所需配置无访问控制集群无需额外配置ABAC 集群官方不支持虽然正确配置后可能可用建议迁移到 RBAC自定义访问控制方案需确保 Vector 的 Pod/ServiceAccount 对上述三个资源拥有list与watch权限。资源限制建议官方推荐在 Agent 角色每个节点一个下使用以下资源限制Resource limits 一节kubernetes_logs.cueresources: requests: memory: 64Mi cpu: 500m limits: memory: 1024Mi cpu: 6000m官方同时强调这些数值只是参考起点复杂管道可能需要更多资源简单管道则可能更少需结合实际负载调整。测试与可靠性Vector 针对 Kubernetes 进行了大量测试Kubernetes 是其最流行的安装方式。仓库为自 1.19 起的所有次要版本 Kubernetes 提供了完整的端到端测试套件Testing reliability 一节kubernetes_logs.cue。相关验证脚本见 scripts/test-e2e-kubernetes.sh端到端测试用例位于 tests/e2e/。内部指标与观测该源组件通过 internal_events/kubernetes_logs.rs 暴露内部指标用于监控自身运行状况component_received_events_total/component_received_event_bytes_total按pod_name、pod_namespace维度计数的接收事件与字节数k8s_format_picker_edge_cases_total格式探测器遇到的边界情况计数如无 message 字段、message 非字节类型k8s_docker_format_parse_failures_totalDocker 格式解析失败计数component_errors_total元数据注解失败annotation_failed、文件服务器生命周期错误kubernetes_lifecycle等错误计数k8s_merged_line_truncated_total合并行被截断计数。这些指标可直接接入 Vector 自身的 internal_metrics 源或 Prometheus 进行告警与排障例如通过k8s_docker_format_parse_failures_total判断是否存在运行时日志格式异常。常见配置场景示例排除特定命名空间sources: k8s_logs: type: kubernetes_logs extra_namespace_label_selector: vector.dev/excludetrue排除特定 Podsources: k8s_logs: type: kubernetes_logs extra_label_selector: app.kubernetes.io/name!my-app extra_field_selector: metadata.name!pod-name-to-exclude文件路径级过滤sources: k8s_logs: type: kubernetes_logs include_paths_glob_patterns: [**/kube-system/**] exclude_paths_glob_patterns: [**/*.gz, **/*.tmp, **/exclude/**]降低文件发现延迟sources: k8s_logs: type: kubernetes_logs glob_minimum_cooldown_ms: 5000 # 文件轮转频繁时建议调低自定义元数据字段路径sources: k8s_logs: type: kubernetes_logs pod_annotation_fields: pod_name: k8s.pod_name pod_namespace: k8s.pod_ns node_annotation_fields: node_labels: # 抑制 Node 标签字段总结kubernetes_logs是 Vector 面向 Kubernetes 环境的一等公民采集方案以 DaemonSet 模式在每个节点就近读取/var/log/pods下的容器日志借助 Kubernetes API 实时富化 Pod、Namespace、Node 元数据通过内置标签/注解排除规则与 glob 路径过滤提供细粒度采集控制并以内置的格式探测与部分消息合并机制兼容 Docker 与 CRI 两类容器运行时。配合宿主机映射目录的 checkpoint 机制Agent 重部署后可无缝续传。合理配置extra_*_selector、glob_minimum_cooldown_ms与insert_namespace_fields等参数即可在采集完整性与 API server 负载之间取得良好平衡。如需进一步深入可继续阅读仓库内的组件元数据定义 kubernetes_logs.cue、自动生成的配置参考 generated/kubernetes_logs.cue以及核心实现 src/sources/kubernetes_logs/mod.rs。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考