Vector v0.28.0 发布说明：配置文档自动生成、VRL 压缩函数与一批破坏性变更

• 可观测性
• 数据工程
• 数据集成
• 日志分析

本文基于 Vector 开源仓库中 v0.28.0 的官方发布数据（发布数据源 与 0.28 升级指南），系统梳理该版本的核心变化：包括"由代码结构自动生成参考文档"的文档工程化里程碑、VRL 新增的 gzip/zlib/zstd 编解码与 seahash 函数、各组件的新配置项、以及必须关注的破坏性变更与弃用项，帮助读者评估是否升级以及如何迁移。

版本定位与发布背景

Vector v0.28.0 发布于 2023-02-23，是一个偏维护性质的次要版本：主要以 bug 修复与小型增强为主，同时为后续新特性做后台准备。从提交记录看，该版本包含大量文档生成化（autogen docs）提交——几乎每个 source/sink 都在该版本切换为"由配置结构自动生成参考文档"，这正是发布说明中提到的重点：

本版本完成了一项里程碑式工作：Vector 的参考文档（reference documentation）现在直接从代码中的配置结构自动生成，这显著减少了已发布文档与实际实现之间的不一致。

这一机制对用户的实际影响是：组件文档、默认值、字段说明都直接与 Rust 中的配置结构定义同步，读文档即读代码（例如 config 目录 与各组件config.rs中的#[configurable(metadata(...))]注解）。

已知问题（Known Issues）

官方发布数据明确列出的 5 个已知问题及修复版本如下，升级到 0.28.0 前建议先确认是否受影响：

新功能与新增配置项

1. VRL 标准库：压缩/解压与快速哈希

v0.28.0 为 VRL 语言新增了 6 个函数，覆盖数据压缩与哈希场景（对应提交16039、16059、16060、16073）：

• encode_gzip(value)/decode_gzip(value)：与 gzip 压缩数据交互；
• encode_zlib(value)/decode_zlib(value)：与 zlib 压缩数据交互；
• encode_zstd(value)/decode_zstd(value)：与 zstd 压缩数据交互；
• seahash(value)：非加密的快速哈希函数，适合不需要抗碰撞安全性的场景（如负载均衡分流、采样分桶）。

典型用法示例（在 remap transform 中对字段做 gzip 编码后再发往下游）：

transforms: compress: type: remap inputs: [logs] source: | .payload = encode_gzip(.(原字段)) # 按实际字段名调整

2.httpsink：payload_prefix/payload_suffix

httpsink 新增payload_prefix与payload_suffix两个选项，用于在批次编码完成后在 HTTP body 前后追加文本（PR 15696）。典型场景是把整个批次包裹进 JSON envelope：

sinks: my_http: type: http inputs: [logs] uri: https://example.com/ingest encoding: codec: json payload_prefix: '{"events":' payload_suffix: '}'

该选项在批次编码之后生效，因此不会破坏编码器内部的 framing/log 结构。

3.reducetransform：max_events限制单批事件数

reducetransform 新增max_events配置项，用于限制一个合并批次中的事件总数（PR 14817）。在源码层面，该选项定义于 src/transforms/reduce/config.rs 的pub max_events: Option<NonZeroUsize>，并在 src/transforms/reduce/transform.rs 中于事件并入时检查是否达到上限、触发 flush；max_events = 1时每次合并即立即输出，等价于不做跨事件聚合。仓库中的单元测试（max_events_0、max_events_1、max_events等，见 transform.rs）验证了0会被拒绝、1与多值上限的边界行为。

配置示例：

transforms: merge: type: reduce inputs: [logs] merge_strategies: message: concat max_events: 1000

同版本还对该 transform 做了性能优化：只在事件确实可 flush 时才触发 flush，避免反复检查过期事件（PR 9502）。

4.pulsarsink：批量支持

pulsarsink 新增batch.max_events配置项，为 Pulsar 写入增加批量能力（PR 16063）。注意提交16582（"Rename batch size option"）对该选项命名做了修正，配置时以当前发布说明中的batch.max_events为准。

5.kafkasource：consumer lag 指标与优雅关闭

kafkasource 现在可以通过internal_metricssource 暴露 consumer lag 指标（PR 15106），开关为：

sources: kafka_in: type: kafka bootstrap_servers: "localhost:9092" topics: ["my-topic"] group_id: "vector" metrics: topic_lag_metric: true

注意：该指标按 topic 与 partition 打标签，可能产生高基数指标，生产环境需评估成本。另外，kafkasource 在关闭时会尝试同步提交 offset（PR 15870），以降低重启后重复消费的概率。

6. 其他组件增强

• aws_kinesis_firehosesource：新增store_access_key选项（PR 15904），与splunk_hec、datadog_agentsource 一致，将请求携带的 token 存入事件 secrets，可在后续 VRL 中读取以驱动行为；
• azure_blobsink：新增自定义endpoint选项（PR 15336），用于对接 USGov、China 等替代性 Azure 云；
• clickhousesink：新增date_time_best_effort选项（PR 15787），让 ClickHouse 解析更广泛的时间戳格式（如 RFC3339）；
• redissource：对失败请求改为指数退避重试（PR 16518），替代原先的立即重试，避免高资源占用；
• gcp相关 sink：修复禁用 healthcheck 时认证 token 无法刷新的问题（PR 15827）；gcp_stackdriver_metricssink 修复指标编码问题（PR 16394）。

破坏性变更与升级指南

v0.28.0 包含5 项破坏性变更，升级前务必逐项对照 0.28 升级指南。

1.journaldsource：移除units选项

units自 v0.10 起就已被include_units取代，本版本彻底移除。请将配置中的units全部改为include_units：

sources: journald_in: type: journald include_units: ["ssh.service"] # 原来是 units

2. VRL 元数据函数移除：改用%路径语法

v0.25.0 引入的元数据路径语法（%<字段名>）已可直接指向事件元数据，因此三个元数据函数被正式移除（PR 14821）。若运行 0.25.0 及以上版本，编译器会给出带正确迁移语法的警告。对照迁移表：

3.apexsink 移除

Apex 服务已于 2022 年 12 月 EOL，apexsink 随之从代码库中删除（PR 16533，删除了约 600 行实现）。仍在使用的用户需改用其他可用 sink。

4.disk_v1buffer 类型移除

废弃已久的disk_v1buffer 类型已删除（PR 15928，同时移除了 LevelDB 实现，删除约 2500 行代码）。若你仍在使用该类型，必须先降级到 v0.27.1将 buffer 迁移到新磁盘缓冲实现，再升级：

-type = "disk_v1" +type = "disk"

迁移本身是透明的，但 v0.28.0 起已不存在自动迁移行为，直接升级将无法识别该类型。

5.datadog_logssink：host重命名为hostname

该 sink 之前会把事件中来自全局 log schema 或事件 host 路径的host键重命名为host；本版本改为重命名为hostname，以对齐 Datadog Agent intake API 的字段约定（PR 15473 相关）。

弃用通知（Deprecations）

以下选项本版本仍可用，但已标记弃用，建议尽早迁移：

• redissink 的url→endpoint：为与其它 Vector sink 命名一致，url更名为endpoint；url暂时仍可用但将在后续版本移除。
• aws_s3source 的strategy选项从文档隐藏：当前该选项只有sqs一个值且为默认值，属于纯文档变更，用户无需修改（未来若新增策略会重新公开）。
• axiomsink 硬编码timestamp-field头：实现上事件时间戳始终存放在@timestamp，因此不再读取全局log_schema的配置值，而是将该请求头固定为@timestamp。
• datadog_logs/datadog_metricssink 的api_key将被移除：正式弃用api_key，官方文档名为default_api_key，api_key将在 v0.29.0 移除，请改用default_api_key。

可能影响但通常无需操作的变化

AWS 组件切换 TLS 实现：rustls → OpenSSL

Vector 的 AWS 组件 TLS 实现从rustls切换为 OpenSSL（PR 16335，提交 "Switch to native-tls"）。官方预期对终端用户无可见影响，主要收益是：由于大部分依赖已使用 OpenSSL，可降低维护负担，并允许这些组件在 FIPS 合规系统上运行。若遇到异常可反馈社区。

azure_monitor_logssink：时间戳编码位置可配置

该 sink 原先按log_schema决定的时间戳路径写入格式化时间戳，并设置time-generated-field头告知 Azure Monitor 填充TimeGenerated标准列。本版本新增time_generated_key选项决定该字段的写入位置；未设置时默认回退到log_schema配置值。

重点修复速览

除上述功能外，v0.28.0 还修复了一批影响日常使用的问题：

• 配置热重载更精确（PR 15868）：重载时能更好识别哪些组件真正发生了变化——对于值类型为 map 且键值均未变的配置项，不再触发无关组件的重载；
• Secret 可多次复用（PR 15815）：此前同一 secret 在配置中出现两次及以上会报"undefined"，现已修复；
• filesource 的 checksum 失效范围收窄（PR 15899）：修改max_line_bytes不再导致所有历史 checksum 失效，仅当新值小于原校验行长时才失效；
• VRL 短路表达式类型推导修复（PR 16391）：正确计算布尔短路表达式的类型定义，避免在少数情况下 panic 或无法编写合法 VRL 程序；
• 内存分配跟踪不再 panic（PR 16201）：配置中组件超过 254 个（或单元测试大量并发组件）时，不再因创建第 255 个 allocation group 而 panic。

总结

v0.28.0 虽是小版本，却完成了"配置结构自动生成参考文档"的基础设施级改造，并为 VRL 补齐了 gzip/zlib/zstd 编解码能力；同时移除了journald.units、VRL 元数据函数、apexsink、disk_v1buffer 等历史包袱。升级前请重点对照 0.28 升级指南 中的 5 项破坏性变更；若使用 AWS 组件且需 FIPS 合规，可关注 TLS 实现切换带来的收益。完整变更清单与逐条提交记录见 发布数据源。

• 可观测性
• 数据工程
• 数据集成
• 日志分析