Vector 0.16 升级指南：五大破坏性变更的完整迁移实操

Vector 0.16 升级指南：五大破坏性变更的完整迁移实操

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

本文聚焦 Vector 0.16.0 版本的 5 项破坏性变更（breaking changes），逐一给出配置迁移方法：组件标识字段name统一为ID、datadog_logssink 的encoding.codec选项移除、memory_use_bytes内部指标更名、datadog_logssource 更名为datadog_agent、kubernetes_logssource 新增 Namespace RBAC 要求。读完后你可以安全地将存量 Vector 部署升级至 0.16.0，并避免升级后出现的组件启动失败、指标断档或权限报错。

破坏性变更总览

Vector 0.16.0 包含以下五项破坏性变更，本文按原文档的脉络逐项展开：

1. 组件 name 字段更名为 ID——配置中组件标识的术语统一为ID
2. Datadog Logs sink 的 encoding 选项移除——不再支持text编码
3. memory_use_bytes内部指标更名——Lua 运行时内存指标改名为lua_memory_use_bytes
4. datadog_logssource 更名为datadog_agent——组件类型名变化
5. kubernetes_logssource 的新 RBAC 要求——需为 ClusterRole 增加namespaces资源权限

组件 name 字段更名为 ID

变更内容

Vector 历史上在部分地方把组件标识字段称为name，在另一些地方称为id。0.16.0 决定统一标准术语为ID，因为该字段的本意是"组件的不变标识符"（an unchanging identifier for components）。

以如下组件配置为例：

transforms: parse_nginx: type: "remap" inputs: [] source: ""

其中parse_nginx这个部分（即组件配置段落的 key），在文档中现在只被称为ID。注意：配置文件中组件的 key 写法本身没有变化，变化的只是文档与工具链中的术语。

对internal_metrics用户的影响

这是对使用内部指标的用户影响最实质的地方。为了兼容已有的component_name用法，0.16.0 保留了该 tag，同时新增了component_idtag：

• 如果你曾在指标查询中按component_name分组，或是在remap/luatransform 中引用过该 tag，应更新为component_id；
• component_name将在未来版本被移除，建议尽快迁移。

对 GraphQL API 用户的影响

在 GraphQL API 中，所有Component上对name的引用已更新为componentId。之所以不用简单的Id字段名，是因为Id在 GraphQL 生态中有特殊语义（spec 规定的 ID 标量类型），而团队可能后续再为其提供支持。

Datadog Logs sink 的 encoding 选项移除

变更内容

在较早版本中，datadog_logssink 可以配置以text或json编码发送日志。虽然 Datadog Logs Ingest API 接受文本格式，但该 API 的原生格式是 JSON——文本格式存在限制，仅用于与旧客户端的向后兼容。

从 0.16.0 起，不再允许设置 Datadog logs sink 的 payload 编码。如果你的配置原本如下：

sinks: dd_logs_egress: type: "datadog_logs" inputs: ["datadog_agent"] encoding: codec: "json"

需要完全移除encoding.codec，得到：

sinks: dd_logs_egress: type: "datadog_logs" inputs: ["datadog_agent"]

注意：encoding下除codec以外的其他字段仍然有效，可以保留。

源码印证

当前仓库中 Datadog 系列 sink 的实现位于 src/sinks/datadog 目录下，按数据类型拆分为logs（events）、metrics、traces三个子模块，分别对应 Datadog 的不同 Ingest API。这一结构印证了 0.16 时期"Datadog 各数据类型走各自协议格式"的设计方向——logs 固定 JSON，metrics 与 traces 则各走其 protobuf/JSON 协议。

memory_use_bytes内部指标更名

变更内容

Vector 此前文档声称internal_metrics中的memory_use_bytes指标表示"Vector 当前使用的总内存（字节）"，但实际上该指标是由luatransform 发布的，只反映Lua 运行时的内存占用，而非整个进程的内存。

为消除歧义，0.16.0 将该指标从memory_use_bytes更名为lua_memory_use_bytes。如果你此前用memory_use_bytes来观测 Lua 运行时内存，请将查询更新为lua_memory_use_bytes，该指标的文档说明也同步更新。

datadog_logssource 更名为datadog_agent

变更内容

0.16.0 将datadog_logssource 更名为datadog_agent。原名称存在歧义：datadog_logs这个名字容易让人误以为它对应datadog_logssink、或模拟 Datadog Logs API；而该 source 的真实定位是专门从运行中的 Datadog Agent 采集数据。

官方选择以破坏性变更（而非保留datadog_logs别名）的方式处理，因为本次发布的变更并不向后兼容，更名正是对这一点的如实反映。未来可能会重新引入一个模拟 Datadog API 的datadog_logssource，供 Agent 以外的其他 Datadog 客户端使用。

迁移方法

将配置中的组件类型从datadog_logs改为datadog_agent：

[sources.datadog] -type = "datadog_logs" +type = "datadog_agent" address = "0.0.0.0:8080" store_api_key = true

当前源码印证：能力已大幅扩展

0.16 时该 source "只采集 Agent 转发的日志，未来将扩展到 metrics 和 traces"——这一规划在仓库中已经兑现。查看 src/sources/datadog_agent/mod.rs 可以看到，组件现定义为：

#[configurable_component(source( "datadog_agent", "Receive logs, metrics, and traces collected by a Datadog Agent." ))]

当前DatadogAgentConfig的配置项已远超 0.16 时代，包括：

• address：监听地址，必须包含端口（默认示例0.0.0.0:8080）
• store_api_key（默认true）：当入站事件携带 Datadog API key 时，将其存入事件元数据，若事件最终发往 Datadog sink 可直接复用
• disable_logs/disable_metrics/disable_traces/disable_llmobs：分别关闭各数据类型（metrics 为 beta、traces 为 alpha）
• multiple_outputs（默认false）：开启后 logs、metrics、traces 分流到不同输出，如名为agent的组件可通过agent.logs、agent.metrics、agent.traces分别作为其他组件的输入
• parse_ddtags（默认false）：将日志中 Agent 设置的ddtags键值对字符串展开为数组
• split_metric_namespace（默认true）：将指标名按第一个.拆分为 namespace 和 name
• send_timeout_secs：下游组件未就绪时的响应超时——若设置，Vector 会返回 HTTP 503 并递增component_timed_out_events_total；若不设置，请求会阻塞直到 Agent 侧超时，导致事件丢弃并递增component_discarded_events_total

如果你正从 0.16 继续向前升级，这份配置项清单可直接用于排查现有配置。

kubernetes_logssource 的新 RBAC 要求

变更内容

0.16.0 起，kubernetes_logssource 会用事件来源 Namespace 的标签来丰富事件，这一增强功能需要访问 Kubernetes 中的额外资源。仓库提供的 Kubernetes manifests 和 Helm chart 已更新：创建的ClusterRole现在授予对namespaces资源的访问权限。

如果你没有使用官方提供的安装方式，需要自行更新ClusterRole：

apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: vector-agent rules: - apiGroups: - "" resources: + - namespaces - pods verbs: - watch

升级到 0.16.0 时，如果使用官方安装方式，需同步升级到对应版本的 Helm chart 或 Kubernetes manifests。

当前仓库中的 manifests 印证

查看 distribution/kubernetes/vector-agent/rbac.yaml 可确认当前 manifests 中vectorClusterRole 的rules已包含namespaces资源（与nodes、pods并列，verbs为list和watch），说明 0.16 引入的 RBAC 要求一直延续至今——从 0.16 升级而来的部署若一直沿用官方 manifests，该权限已经就位；自建 RBAC 的用户则应核对上面的 diff。

升级检查清单

按以下顺序完成 0.16.0 升级前的配置审查：

检查项	操作	适用人群
术语与 tag	将remap/luatransform 与指标查询中的component_name更新为component_id	使用内部指标或 transform 的场景
GraphQL API	将Component的name字段引用改为componentId	使用 GraphQL API 的用户
Datadog logs 出口	移除encoding.codec配置项	使用datadog_logssink 的用户
Lua 内存指标	将memory_use_bytes查询更新为lua_memory_use_bytes	监控 Lua transform 内存的用户
Datadog 日志入口	组件类型datadog_logs改为datadog_agent	从 Datadog Agent 接收数据的所有用户
Kubernetes RBAC	为 ClusterRole 增加namespaces资源，或升级到 0.16 官方 Helm chart / manifests	自建 RBAC 且使用kubernetes_logs的用户

完成以上迁移后，升级至 0.16.0 即可平稳过渡。建议升级后观察component_idtag 是否已在内部指标中生效、以及 Datadog 出口是否有编码相关报错，以确认迁移完整。

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector