企业官网建设流程全解析

Vector 0.12 升级指南：encoding.codec 强制化、check_fields 弃用与 VRL 迁移实战

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

Vector 0.12 是一次以「破坏性变更极少、弃用项显著」为特征的版本升级：sink 级别的encoding.codec从可选变为必填、check_fields条件被弃用并转向 VRL（Vector Remap Language）布尔表达式、generatorsource 新增了format选项，同时一批传统 transform 被弃用、filesource 的start_at_beginning选项被ignore_checkpoints与read_from取代。读完本文，你将能够逐项对照修改现有配置完成升级，并理解每项变更背后的设计动机与当前仓库中的源码实现。

变更总览

0.12 的升级涉及三类内容，升级前建议先通读一遍以便定位自己配置中受影响的组件：

下面逐项展开，并在结尾给出可直接执行的升级检查清单。

破坏性变更一：所有相关 sink 必须显式指定encoding.codec

0.12 移除了 sink 级encoding.codec选项的默认值。此前各 sink 都带有「有主见的」编码默认值（如默认text或默认json），用户若未显式指定，实际输出格式可能出乎意料；显式必填后，编码行为完全由配置决定，杜绝了这类隐式行为。

受影响的 sink 及其旧默认值如下：

• aws_s3（原默认text）
• file（原默认text）
• humio（原默认json）
• kafka（原默认text）
• nats（原默认text）
• new_relic_logs（原默认json）
• pulsar（原默认text）
• splunk_hec（原默认text）

升级方式很简单：在受影响 sink 中补上encoding.codec，取值为你期望的格式（json或text）：

[sinks.backup] type = "aws_s3" inputs = ["..."] bucket = "my-bucket" compression = "gzip" region = "us-east-1" +encoding.codec = "json"

如何选择json与text

• text：丢弃全部结构化数据，仅传递message字段的值。它面向「Vector 作为透传代理、不应改写数据」的场景；
• json：保留全部结构化数据，对绝大多数使用场景都更合适，也是官方推荐。

仓库自带的示例配置也印证了「显式声明编码」的规范写法，例如 file_to_prometheus.yaml 中 sink 段即包含独立的encoding:配置块，vector.yaml 的示例配置同样在 sink 下显式给出encoding:段。升级后可对照这些示例检查自己的配置。

破坏性变更二：check_fields条件弃用，需显式type或迁移到 VRL 表达式

伴随 VRL 的发布，0.12 弃用了check_fields条件语法，转而推荐使用 VRL 布尔表达式。旧语法受限于 TOML 这类配置语言本身不擅长表达布尔条件，用户能用来路由（route）、过滤（filter）、归约（reduce）数据的方式十分有限，存在多处配置语法陷阱。

check_fields虽然被弃用但仍受支持，升级只需显式加入type选项「opt-in」该特性：

[transforms.route] type = "route" +lanes.errors.type = "check_field" lanes.errors."level.eq" = "error"

更推荐的做法是迁移到 VRL 语法，条件从「key-path 风格的 TOML 键值对」变成一行字符串表达式：

[transforms.route] type = "route" -lanes.errors."level.eq" = "error" +lanes.errors = '.level = "error"'

在 VRL 中，.level = "error"是一个直接可求值为布尔量的比较表达式，route的每条 lane 只要给出这样的布尔表达式即可，表达能力远超旧的check_fields键值模式（如level.eq、message.contains等受限组合）。

一个值得注意的现状：在当前仓库的src/源码中已经搜索不到check_fields相关实现——从源码结构看，这一弃用语法在后续版本中已被完全移除，而非停留在「弃用但仍可用」的状态。也就是说，如果你的配置还停留在check_fields写法，迁移到 VRL 表达式已不是「建议」而是「必须」。

破坏性变更三：generatorsource 要求format选项

generatorsource 常用于测试与压测，0.12 为其引入了format选项，用于指定产生日志的格式。按原文档描述该选项为必填，升级示例为：

[sources.generator] type = "generator" +format = "apache_common" # or "apache_error" or "syslog"

当前仓库中该 source 的实现位于 demo_logs.rs，其中OutputFormat枚举定义了可产生的日志格式，源码注释标明包括：

• Apache common 格式；
• Apache error 格式；
• Syslog 格式（分别对应 RFC 5424 与 RFC 3164）；
• 以及 JSON 格式的 HTTP server 日志等扩展格式。

可见当前版本支持的格式比 0.12 发布时更多，若你从 0.12 直接升级至今日版本，format的可选值可以对照 demo_logs.rs 中的OutputFormat枚举确认。

弃用项一：17 个 transform 被弃用，推荐统一迁移到remap

0.12 将以下 transform 整体弃用，官方推荐的替代方案是新的remaptransform：

• add_fields、add_tags、ansi_stripper
• aws_cloudwatch_logs_subscription_parser
• coercer、concat
• grok_parser、json_parser、key_value_parser、logfmt_parser
• merge、regex_parser
• remove_fields、remove_tags、rename_fields
• split、tokenizer

这些旧 transform 的功能在 VRL 中大多可以用一行函数调用表达。原文档给出的json_parser迁移示例：

transforms: remap: type: "remap" source: | . = merge(., parse_json!(.message))

即「解析.message中的 JSON 并合并回根对象」，替代了整个json_parsertransform 的声明式配置。类似的，字段增删改名对应 VRL 的直接赋值与删除语法，解析类 transform 对应parse_grok、parse_regex、parse_key_value、parse_logfmt等 VRL 函数，split/tokenizer对应字符串切分函数，coercer对应 VRL 的类型强转函数。

原文档同时说明：这些 transform 不会立即被移除，计划保留到 Vector 1.0 才删除（0.12 发布时官方预计 2022 年末达到 1.0 里程碑）。若配置庞大，可优先迁移高频、复杂度高的 transform（如json_parser、regex_parser、grok_parser），收益最明显。

弃用项二：filesource 的start_at_beginning被ignore_checkpoints+read_from取代

start_at_beginning选项已被移除语义上的替代者：新选项ignore_checkpoints与read_from组合表达相同的意图，且粒度更细。迁移方式：

[sources.file] type = "file" -start_at_beginning = true +ignore_checkpoints = false # default +read_from = "beginning" # default

上述两个新值即为默认值，通常无需显式写出。当前仓库中这一迁移逻辑有明确的源码佐证：file.rs 中的reconcile_position_options函数（约 L694-L715）会检测到旧选项并打印弃用警告Use of deprecated option start_at_beginning. Please use ignore_checkpoints and read_from options instead，同时按以下规则推导新选项的取值：

• start_at_beginning = true时，ignore_checkpoints回退为true、read_from回退为Beginning；
• 未设置或为false时，两者分别回退为false与默认读取位置；
• 直接设置的新选项优先于由旧选项推导出的值。

从源码结构看，旧选项在当前版本中依然被解析（保持向后兼容），但会触发告警并逐步退场，建议尽早替换为ignore_checkpoints与read_from的显式配置。

升级检查清单

完成 0.12 升级可按以下清单逐项核对，全部通过后再重启 Vector：

1. Sink 编码：检查所有 sink（重点是aws_s3、file、humio、kafka、nats、new_relic_logs、pulsar、splunk_hec），确认均已显式声明encoding.codec；
2. 条件语法：搜索配置中的check_field键路径写法，要么补type = "check_field"，要么改写为 VRL 布尔表达式（推荐）；考虑到当前仓库已无check_fields实现，直接迁移是更安全的选择；
3. generator source：为generatorsource 补上format选项；
4. 旧 transform：盘点仍在使用的 17 个弃用 transform，优先把解析/合并类 transform 改写为remap；
5. file source：将start_at_beginning替换为ignore_checkpoints+read_from，注意默认值语义（详见 file.rs 中的reconcile_position_options推导规则）。

对照 vector.yaml 与 config/examples 目录下的示例配置，可以快速核对自己升级后的写法是否符合当前规范。

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