企业官网建设流程全解析

Vector 0.25.0 升级指南：六项破坏性变更与三项废弃机制的完整迁移手册

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

Vector 0.25.0 是一次包含多项破坏性变更的版本：移除了 VRL 取模运算符、new_relic_logssink、vector组件 v1 协议，并改变了internal_metrics与lokisink 的默认行为。本文基于 0.25 升级指南 完整梳理这六项 Breaking Changes 与三项 Deprecations 的迁移方法，并结合当前仓库源码（new_relicsink 配置、internal_metrics标签逻辑、loki压缩默认值）逐项给出可验证的实现证据，帮助你在升级时快速定位配置改动点。

版本变更总览

0.25.0 的变更分为两类：

破坏性变更（Breaking Changes）：

1. 移除 VRL 取模运算符%
2. 移除new_relic_logssink
3. internal_metrics默认写入host标签
4. 移除vector源和 sink 的 v1 协议
5. 移除vector源的shutdown_timeout_secs配置项
6. lokisink 请求编码方式改变

废弃项（Deprecations）：

1. 废弃 VRL 的 metadata 函数
2. 废弃 Elasticsearch sink 的endpoint选项
3. 废弃 Lua transform 的 version 1 API

破坏性变更详解

移除 VRL 的取模运算符%

VRL 的取模运算符%在 0.24.0 中已被标记为废弃，0.25.0 正式移除，改用mod函数实现相同计算。

改造前：

5 % 2 == 1

改造后：

mod(5, 2) == 1

升级时全局检索 VRL 脚本（transform 的source字段）中的%字符即可定位所有需要修改的位置，替换为mod(被除数, 除数)形式即可。

移除new_relic_logssink，统一迁移到new_relic

0.24.0 已宣布new_relic_logssink 废弃，推荐改用同时支持日志、指标和链路的new_relicsink。从new_relic_logs切换到new_relic不是简单改一下type字段，需要三处调整：

1. 将type从new_relic_logs改为new_relic；
2. 新增api字段，值为"logs"，指明发送的是日志数据；
3. 调整凭据：new_relic_logs支持 Insights insert key（insert_key）或 License key（license_key）两种凭据，而new_relicsink 不再接受 Insights insert key，必须使用 license key，且必须额外提供账号 ID（account_id）。

完整的配置转换示例：

sinks: new_relic_logs: type: "new_relic_logs" license_key: "xxxx" new_relic: type: "new_relic" license_key: "xxxx" account_id: "yyyy" api: "logs"

当前仓库源码印证了这一设计。NewRelicConfig 结构体中license_key和account_id均为必填字段（无Option包裹、无默认值），api字段对应的 NewRelicApi 枚举提供events、metrics、logs三个取值，默认值为events。也就是说，如果你不显式写api: "logs"，日志会被错误地路由到 Insights Events API 而非 Logs API。

此外从 NewRelicCredentials::try_get_uri 的实现可以看出，不同api与region组合会路由到不同端点：Logs API 在美国区指向log-api.newrelic.com/log/v1，欧盟区指向log-api.eu.newrelic.com/log/v1；Events API 则需要在 URL 中拼入account_id。这也解释了为什么account_id成为必填项——它是 Events 端点 URI 的一部分，源码中的 validate 测试用例 还专门验证了非法account_id会在配置校验阶段直接报错。

internal_metrics默认写入host标签

internal_metrics源现在默认会为发出的每个指标添加 host 标签。这一行为解决了多实例部署的常见问题：当多个 Vector 实例向同一个 metrics sink 发布指标时，如果未显式通过tags.host_key配置该标签，各实例的指标会因标签相同而互相覆盖、无法区分。

默认使用的标签键名取自全局log_schema.host_key配置（其默认值为host）。internal_metrics 源码 展示了这一默认逻辑：tags.host_key未配置时回退到log_schema().host_key()。

标签配置项的完整定义见 TagsConfig：

• host_key：覆盖用于添加对端主机（含端口，如1.2.3.4:9000）的标签键名，默认取全局log_schema.host_key；
• pid_key：设置用于添加当前进程 ID 的标签键名，默认不添加。

如果希望保持 0.24 及以前的行为（不自动加 host 标签），将tags.host_key显式设为空字符串即可退出该默认行为：

sources: my_internal_metrics: type: internal_metrics tags: host_key: ""

移除vector源与 sink 的 v1 协议

vector源和 sink 的原始 v1 协议早在 0.20.0 中就被标记为废弃，0.25.0 移除了对该协议及其配置的支持。升级要点：

• 配置中的version字段仍然被接受，但只接受版本号2；
• 若你的配置中version: 1，需要升级为 v2 协议。

移除vector源的shutdown_timeout_secs

vectorv2 源的shutdown_timeout_secs配置项实际并不产生任何效果（死配置），因此被直接移除。升级时只需从配置中删除该项，无需替代方案。

lokisink 请求编码的默认值变更

Vector 现在默认以snappy 压缩的 protobuf格式向 Loki 发送请求，而不再是 JSON 编码。这一变更带来更小的请求体积和更高的吞吐效率。

当前仓库中 loki sink 的配置 明确将默认压缩设为Compression::Snappy，且该模式下 Content-Type 为application/x-protobuf（见 service.rs）。

如需保留 0.24 及以前的 JSON 行为，将compression选项设为none或gzip即可，其中none对应旧的默认行为：

sinks: my_loki: type: loki endpoint: "http://localhost:3100" compression: none # 或 gzip；snappy 为 0.25 新默认值

废弃项详解（Deprecations）

以下三项在 0.25.0 中仍可用，但已被标记为废弃，将在未来版本移除，建议尽快迁移。

废弃 VRL 的 metadata 函数

0.25.0 在 VRL 中引入了新的 metadata 路径语法，可以直接用%前缀寻址事件 metadata，因此原有的 metadata 函数不再必要。对照迁移表：

废弃 Elasticsearch sink 的endpoint选项

0.25.0 为 Elasticsearch sink 引入了向多个端点分发事件的能力，配套新增了endpoints配置项，用于配置一个或多个事件分发目标。原有的单端点配置endpoint因此被废弃，未来版本将移除。升级建议：将endpoint的值迁移到endpoints列表中。

sinks: my_elasticsearch: type: elasticsearch endpoints: - "http://es1:9200" - "http://es2:9200"

废弃 Lua transform 的 version 1 API

luatransform 的 version 2 API 自 0.9.0 引入以来已完全成熟，而 version 1 API 除了仅支持 logs 数据类型外没有任何维护价值，因此被废弃。

改造前（v1 语法）：

transforms: example: type: "lua" version: 1 source: | event["a"] = "some value" event["b"] = nil

改造后（v2 hooks 语法）：

transforms: example: type: "lua" version: 2 hooks: process: | function (event, emit) event.log.a = "some value" event.log.b = nil emit(event) end

注意 v2 语法的两个关键差异：脚本从顶层source移到hooks下按钩子（如process）组织；事件访问从event["key"]改为结构化访问event.log.key，且处理完必须显式调用emit(event)把事件重新发出。

升级检查清单

按以下顺序逐项核对，可覆盖 0.25.0 的全部变更：

1. 全局搜索 VRL 脚本中的%取模运算，替换为mod(...)；
2. 将type: "new_relic_logs"的 sink 改为new_relic，补上api: "logs"与account_id，并确认凭据为 license key；
3. 检查多实例部署场景下internal_metrics是否依赖"不带 host 标签"的旧行为，如需要则设置tags.host_key: ""；
4. 将vector源/sink 配置中的version: 1升级为version: 2，并删除shutdown_timeout_secs；
5. 评估lokisink 是否可切换到默认的 snappy/protobuf 编码，如需维持 JSON 行为则显式设置compression: none或gzip；
6. 计划性迁移：VRL metadata 函数改%路径、Elasticsearchendpoint改endpoints、Lua transform 从 v1 升级到 v2 hooks 语法。

参考文件

• 升级指南原文：website/content/en/highlights/2022-10-04-0-25-0-upgrade-guide.md
• new_relicsink 配置与凭据实现：src/sinks/new_relic/config.rs
• internal_metrics源 host 标签逻辑：src/sources/internal_metrics.rs
• lokisink 压缩默认值：src/sinks/loki/config.rs

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