Vector 数据转换实战用 VRL 与 Lua 对可观测性数据进行结构化、塑形与转换【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南基于 Vector 官方入门系列中的《Structuring, Shaping, and Transforming Data》面向已掌握 Vector 基础概念与基础管道搭建的读者完整演示如何使用remap变换与 Vector Remap LanguageVRL对 Syslog 等可观测性数据进行解析、字段增删、类型转换与条件逻辑处理并介绍 VRL 无法覆盖场景下的lua运行时变换及其取舍。读完本文你将能够独立编写一段可在vector.yaml中直接运行的数据转换拓扑并理解其背后的编译期检查与运行时行为。前置要求在开始之前本指南假设你已经具备以下基础理解 Vector 基本概念事件、组件、拓扑理解如何搭建一条基础管道source → transform → sink。Vector 的变换机制与为何首选 VRLVector 提供了多种变换transform组件用于在数据流经 topology管道模型 的过程中修改可观测性数据。在众多变换中你大概率最常使用的是remap变换——它使用一种专为数据转换设计的语言Vector Remap LanguageVRL来定义事件转换逻辑。从源码结构看remap是 Vector 生态的核心变换之一其配置结构体RemapConfig直接内建了 VRL 程序编译与缓存逻辑src/transforms/remap.rs#L51-L164并维护了一个基于 enrichment 表与 schema 定义的编译缓存避免对相同程序重复编译。VRL 之所以应作为转换数据的首选有以下几个关键理由丰富的可观测性专属函数VRL 提供了大量直接映射到可观测性场景的函数例如解析 Syslog 的parse_syslog、解析 JSON 的parse_json、时间戳转换的to_unix_timestamp、生成 UUID 的uuid_v4等为 Vector 日志与指标量身定制VRL 专为 Vector 日志和指标设计没有多余功能其数据模型与 Vector 内部数据模型直接对应性能与原生 Rust 相当。仓库中的 remap 基准测试与 lua 基准测试 正是对这种性能诉求的工程验证编译期检查Vector 内置的 VRL 编译器会在启动时执行多项编译期检查确保 VRL 代码健全——无死代码、无未处理错误、无类型不匹配。在 VRL 无法满足你的场景时Vector 还提供 Lua 运行时变换它比 VRL 更灵活但也伴随下文列出的、应当始终牢记的缺点。使用 VRL 转换数据一个完整拓扑示例让我们直接进入一个使用 VRL 修改数据的例子。我们将创建一个由三个组件构成的简单拓扑一个demo_logs源以每秒 10 条的速率产生随机 SyslogRFC 5424格式消息一个remap变换使用 VRL 将传入的 Syslog 行解析为命名字段severity、timestamp等一个consolesink将拓扑输出打印到 stdout方便在命令行直接查看结果。下面的配置即定义了该拓扑sources: logs: type: demo_logs format: syslog interval: 0.1 transforms: modify: type: remap inputs: - logs source: | # Parse Syslog input. The ! means that the script should abort on error. . parse_syslog!(.message) sinks: out: type: console inputs: - modify encoding: codec: json说明虽然这里使用 YAML 编写配置Vector 同样支持 TOML 与 JSON 格式。从源码看demo_logs源的配置项与上述用法完全对应interval控制每批输出的间隔秒数默认 1 秒设为0.0可去掉延迟尽可能快地输出format支持shuffle、apache_common、apache_error、syslogRFC 5424、bsd_syslogRFC 3164与json等多种随机格式count默认输出无限行src/sources/demo_logs.rs#L32-L77。使用该拓扑启动 Vectorvector --config /etc/vector/vector.yaml你应该会在 stdout 看到类似下面的输出行此处为便于阅读做了格式化{ appname: authsvc, facility: daemon, hostname: acmecorp.biz, message: #hugops to everyone who has to deal with this, msgid: ID486, procid: 5265, severity: notice, timestamp: 2021-01-19T18:16:40.027Z }到目前为止我们只是让 Vector解析了 Syslog 数据还没有真正修改这些数据。接下来更新remap变换的source脚本做一些临时性的转换transforms: modify: type: remap inputs: - logs source: | . parse_syslog!(.message) # Convert the timestamp to a Unix timestamp, aborting on error .timestamp to_unix_timestamp!(.timestamp) # Remove the facility and procid fields del(.facility) del(.procid) # Replace the msgid field with a unique ID .msgid uuid_v4() # If the log message contains the phrase Great Scott!, set the new field # critical to true, otherwise set it to false. If the contains function # errors, log the error (instead of aborting the script, as above). if (is_critical contains(.message, Great Scott!); is_critical) { log(It contains Great Scott!, level: info) } .critical is_critical关于这段脚本有几点值得注意所有 VRL 函数抛出的错误都必须被处理。例如如果我们忽略parse_syslog函数可能抛出的错误VRL 编译器会给出非常具体的警告Vector 将无法启动。这正是 VRL 编译期检查的体现VRL 具备完整的语言构造变量、if语句、注释以及日志输出log.充当事件数据的容器单独的.指向事件根对象你可以使用路径path如.foo、.foo[0]、.foo.bar、.foo.bar[0]等引用子字段、数组索引等。VRL 的路径语法在remap实现中由ValuePath等类型支撑src/transforms/remap.rs#L25-L27。注意VRL 函数在不同执行上下文中的行为可能不同。例如当编译器能检测到.message的类型是字符串时上面的contains函数在 Vector/Remap 进程内是 infallible不会出错的。同样的代码在 VRL Playground、VRL CLI 中运行或在schema.log_namespace设为true时行为可能不同。重启 Vector 后你应该看到类似下面的日志行同样为便于阅读做了重新格式化{ appname: authsvc, hostname: acmecorp.biz, message: Great Scott! Were never gonna reach 88 mph with the flux capacitor in its current state!, msgid: 4e4437b6-13e8-43b3-b51e-c37bd46de490, severity: notice, timestamp: 1611080200, critical: true }至此我们已经成功创建了一个会转换流经它的每个事件的 Vector 拓扑Syslog 原始文本被解析为结构化字段timestamp被转换为 Unix 时间戳facility与procid被删除msgid被替换为 UUID并基于消息内容新增了critical布尔字段。remap 变换的更多配置能力除了source内联脚本remap变换还支持把 VRL 程序放在外部文件中file单个文件路径相对路径以当前工作目录为根与files多个文件路径三者至少指定其一src/transforms/remap.rs#L58-L85。此外还有几个与错误处理密切相关的配置项drop_on_error默认false。当 VRL 程序处理事件出错时默认会把原始未修改事件继续下发设为true后则直接丢弃出错事件drop_on_abort默认true。控制 VRL 程序中手动调用abort中止时是下发原始未修改事件还是丢弃reroute_dropped默认false。开启后被drop_on_error或drop_on_abort丢弃的事件会被转发到名为dropped的特殊输出便于进一步分析、调试或重试metric_tag_values控制指标标签值如何暴露single/full/autoauto模式下单值标签暴露为字符串、多值标签暴露为数组timezone为不包含显式时区的时间戳转换指定时区覆盖全局timezone选项src/transforms/remap.rs#L101-L110。这些配置让remap不仅能成功时转换数据还能精确定义出错时数据流向何处。深入探索 VRL如果你想进一步了解 VRL推荐阅读以下内容VRL 函数完整列表——涵盖parse_syslog、to_unix_timestamp、uuid_v4、contains、del、log、abort等全部内置函数VRL 示例——仓库内置的 VRL 测试用例与示例VRL 表达式——详细描述 VRL 语法与类型系统的实现。仓库中 VRL 标准库的本地实现与 web-playground 也是阅读源码、理解函数执行上下文差异如schema.log_namespace对类型推断的影响的绝佳入口。Lua 运行时变换如果 VRL 无法覆盖你的用例——这种情况应当很少发生——Vector 还提供了lua运行时变换你可以用它代替 VRL。它允许你运行直接内嵌在 Vector 配置中的 Lua 代码。从源码结构看lua变换存在两个 API 版本v1 已标记为 deprecated将在未来版本中移除v2 采用基于生命周期钩子的编程模型通过hooks.init、hooks.process、hooks.shutdown三个钩子函数管理变换的初始化、事件处理与收尾并支持source初始化 Lua 代码可引入外部依赖与定义钩子函数与search_dirs自定义依赖搜索路径等配置src/transforms/lua/mod.rs#L59-L72、src/transforms/lua/v2/mod.rs#L72-L80。v2 还通过LuaMetricTagValues控制指标标签暴露方式single/full。lua变换提供了最大的灵活性因为你可以直接在 Vector 内部使用一门完整的编程语言。但我们建议只在确实必要时使用它原因如下lua变换很容易让你写出缓慢、易出错且难以阅读的脚本它要求你在使用 Vector 之外额外引入一套编码/测试/调试工作流——如果你的用例没有其他办法满足这一成本是值得的但如非必要最好避免与 VRL 相比它会带来性能开销。仓库中的 lua 基准测试 也从工程角度印证了这一点。因此实践中的推荐路径是优先用 VRL 描述转换逻辑仅在 VRL 确实无法表达例如需要复杂外部库或非结构化算法时才求助于 Lua。小结本文围绕 Vector 的核心变换组件remap与lua完整走通了一条解析 → 塑形 → 转换的数据管道用demo_logs源模拟 Syslog 数据用remap变换配合 VRL 的parse_syslog、to_unix_timestamp、del、uuid_v4、contains、log等函数完成字段级转换并通过consolesink 验证结果理解了 VRL 的编译期错误检查、.事件容器与路径语法以及执行上下文Vector 进程、VRL CLI、Playground、schema.log_namespace对函数行为的影响掌握了remap在错误处理drop_on_error、drop_on_abort、reroute_dropped与外部程序文件file/files方面的扩展能力了解了lua运行时变换的 v1/v2 演进、钩子式编程模型及其在灵活性与性能、可维护性之间的权衡。相关源码与配置均可在本仓库中继续深入研读remap 变换实现、demo_logs 源实现、lua 变换实现、VRL 函数与测试 以及 VRL 基准测试。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vector 数据转换实战：用 VRL 与 Lua 对可观测性数据进行结构化、塑形与转换
Vector 数据转换实战用 VRL 与 Lua 对可观测性数据进行结构化、塑形与转换【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南基于 Vector 官方入门系列中的《Structuring, Shaping, and Transforming Data》面向已掌握 Vector 基础概念与基础管道搭建的读者完整演示如何使用remap变换与 Vector Remap LanguageVRL对 Syslog 等可观测性数据进行解析、字段增删、类型转换与条件逻辑处理并介绍 VRL 无法覆盖场景下的lua运行时变换及其取舍。读完本文你将能够独立编写一段可在vector.yaml中直接运行的数据转换拓扑并理解其背后的编译期检查与运行时行为。前置要求在开始之前本指南假设你已经具备以下基础理解 Vector 基本概念事件、组件、拓扑理解如何搭建一条基础管道source → transform → sink。Vector 的变换机制与为何首选 VRLVector 提供了多种变换transform组件用于在数据流经 topology管道模型 的过程中修改可观测性数据。在众多变换中你大概率最常使用的是remap变换——它使用一种专为数据转换设计的语言Vector Remap LanguageVRL来定义事件转换逻辑。从源码结构看remap是 Vector 生态的核心变换之一其配置结构体RemapConfig直接内建了 VRL 程序编译与缓存逻辑src/transforms/remap.rs#L51-L164并维护了一个基于 enrichment 表与 schema 定义的编译缓存避免对相同程序重复编译。VRL 之所以应作为转换数据的首选有以下几个关键理由丰富的可观测性专属函数VRL 提供了大量直接映射到可观测性场景的函数例如解析 Syslog 的parse_syslog、解析 JSON 的parse_json、时间戳转换的to_unix_timestamp、生成 UUID 的uuid_v4等为 Vector 日志与指标量身定制VRL 专为 Vector 日志和指标设计没有多余功能其数据模型与 Vector 内部数据模型直接对应性能与原生 Rust 相当。仓库中的 remap 基准测试与 lua 基准测试 正是对这种性能诉求的工程验证编译期检查Vector 内置的 VRL 编译器会在启动时执行多项编译期检查确保 VRL 代码健全——无死代码、无未处理错误、无类型不匹配。在 VRL 无法满足你的场景时Vector 还提供 Lua 运行时变换它比 VRL 更灵活但也伴随下文列出的、应当始终牢记的缺点。使用 VRL 转换数据一个完整拓扑示例让我们直接进入一个使用 VRL 修改数据的例子。我们将创建一个由三个组件构成的简单拓扑一个demo_logs源以每秒 10 条的速率产生随机 SyslogRFC 5424格式消息一个remap变换使用 VRL 将传入的 Syslog 行解析为命名字段severity、timestamp等一个consolesink将拓扑输出打印到 stdout方便在命令行直接查看结果。下面的配置即定义了该拓扑sources: logs: type: demo_logs format: syslog interval: 0.1 transforms: modify: type: remap inputs: - logs source: | # Parse Syslog input. The ! means that the script should abort on error. . parse_syslog!(.message) sinks: out: type: console inputs: - modify encoding: codec: json说明虽然这里使用 YAML 编写配置Vector 同样支持 TOML 与 JSON 格式。从源码看demo_logs源的配置项与上述用法完全对应interval控制每批输出的间隔秒数默认 1 秒设为0.0可去掉延迟尽可能快地输出format支持shuffle、apache_common、apache_error、syslogRFC 5424、bsd_syslogRFC 3164与json等多种随机格式count默认输出无限行src/sources/demo_logs.rs#L32-L77。使用该拓扑启动 Vectorvector --config /etc/vector/vector.yaml你应该会在 stdout 看到类似下面的输出行此处为便于阅读做了格式化{ appname: authsvc, facility: daemon, hostname: acmecorp.biz, message: #hugops to everyone who has to deal with this, msgid: ID486, procid: 5265, severity: notice, timestamp: 2021-01-19T18:16:40.027Z }到目前为止我们只是让 Vector解析了 Syslog 数据还没有真正修改这些数据。接下来更新remap变换的source脚本做一些临时性的转换transforms: modify: type: remap inputs: - logs source: | . parse_syslog!(.message) # Convert the timestamp to a Unix timestamp, aborting on error .timestamp to_unix_timestamp!(.timestamp) # Remove the facility and procid fields del(.facility) del(.procid) # Replace the msgid field with a unique ID .msgid uuid_v4() # If the log message contains the phrase Great Scott!, set the new field # critical to true, otherwise set it to false. If the contains function # errors, log the error (instead of aborting the script, as above). if (is_critical contains(.message, Great Scott!); is_critical) { log(It contains Great Scott!, level: info) } .critical is_critical关于这段脚本有几点值得注意所有 VRL 函数抛出的错误都必须被处理。例如如果我们忽略parse_syslog函数可能抛出的错误VRL 编译器会给出非常具体的警告Vector 将无法启动。这正是 VRL 编译期检查的体现VRL 具备完整的语言构造变量、if语句、注释以及日志输出log.充当事件数据的容器单独的.指向事件根对象你可以使用路径path如.foo、.foo[0]、.foo.bar、.foo.bar[0]等引用子字段、数组索引等。VRL 的路径语法在remap实现中由ValuePath等类型支撑src/transforms/remap.rs#L25-L27。注意VRL 函数在不同执行上下文中的行为可能不同。例如当编译器能检测到.message的类型是字符串时上面的contains函数在 Vector/Remap 进程内是 infallible不会出错的。同样的代码在 VRL Playground、VRL CLI 中运行或在schema.log_namespace设为true时行为可能不同。重启 Vector 后你应该看到类似下面的日志行同样为便于阅读做了重新格式化{ appname: authsvc, hostname: acmecorp.biz, message: Great Scott! Were never gonna reach 88 mph with the flux capacitor in its current state!, msgid: 4e4437b6-13e8-43b3-b51e-c37bd46de490, severity: notice, timestamp: 1611080200, critical: true }至此我们已经成功创建了一个会转换流经它的每个事件的 Vector 拓扑Syslog 原始文本被解析为结构化字段timestamp被转换为 Unix 时间戳facility与procid被删除msgid被替换为 UUID并基于消息内容新增了critical布尔字段。remap 变换的更多配置能力除了source内联脚本remap变换还支持把 VRL 程序放在外部文件中file单个文件路径相对路径以当前工作目录为根与files多个文件路径三者至少指定其一src/transforms/remap.rs#L58-L85。此外还有几个与错误处理密切相关的配置项drop_on_error默认false。当 VRL 程序处理事件出错时默认会把原始未修改事件继续下发设为true后则直接丢弃出错事件drop_on_abort默认true。控制 VRL 程序中手动调用abort中止时是下发原始未修改事件还是丢弃reroute_dropped默认false。开启后被drop_on_error或drop_on_abort丢弃的事件会被转发到名为dropped的特殊输出便于进一步分析、调试或重试metric_tag_values控制指标标签值如何暴露single/full/autoauto模式下单值标签暴露为字符串、多值标签暴露为数组timezone为不包含显式时区的时间戳转换指定时区覆盖全局timezone选项src/transforms/remap.rs#L101-L110。这些配置让remap不仅能成功时转换数据还能精确定义出错时数据流向何处。深入探索 VRL如果你想进一步了解 VRL推荐阅读以下内容VRL 函数完整列表——涵盖parse_syslog、to_unix_timestamp、uuid_v4、contains、del、log、abort等全部内置函数VRL 示例——仓库内置的 VRL 测试用例与示例VRL 表达式——详细描述 VRL 语法与类型系统的实现。仓库中 VRL 标准库的本地实现与 web-playground 也是阅读源码、理解函数执行上下文差异如schema.log_namespace对类型推断的影响的绝佳入口。Lua 运行时变换如果 VRL 无法覆盖你的用例——这种情况应当很少发生——Vector 还提供了lua运行时变换你可以用它代替 VRL。它允许你运行直接内嵌在 Vector 配置中的 Lua 代码。从源码结构看lua变换存在两个 API 版本v1 已标记为 deprecated将在未来版本中移除v2 采用基于生命周期钩子的编程模型通过hooks.init、hooks.process、hooks.shutdown三个钩子函数管理变换的初始化、事件处理与收尾并支持source初始化 Lua 代码可引入外部依赖与定义钩子函数与search_dirs自定义依赖搜索路径等配置src/transforms/lua/mod.rs#L59-L72、src/transforms/lua/v2/mod.rs#L72-L80。v2 还通过LuaMetricTagValues控制指标标签暴露方式single/full。lua变换提供了最大的灵活性因为你可以直接在 Vector 内部使用一门完整的编程语言。但我们建议只在确实必要时使用它原因如下lua变换很容易让你写出缓慢、易出错且难以阅读的脚本它要求你在使用 Vector 之外额外引入一套编码/测试/调试工作流——如果你的用例没有其他办法满足这一成本是值得的但如非必要最好避免与 VRL 相比它会带来性能开销。仓库中的 lua 基准测试 也从工程角度印证了这一点。因此实践中的推荐路径是优先用 VRL 描述转换逻辑仅在 VRL 确实无法表达例如需要复杂外部库或非结构化算法时才求助于 Lua。小结本文围绕 Vector 的核心变换组件remap与lua完整走通了一条解析 → 塑形 → 转换的数据管道用demo_logs源模拟 Syslog 数据用remap变换配合 VRL 的parse_syslog、to_unix_timestamp、del、uuid_v4、contains、log等函数完成字段级转换并通过consolesink 验证结果理解了 VRL 的编译期错误检查、.事件容器与路径语法以及执行上下文Vector 进程、VRL CLI、Playground、schema.log_namespace对函数行为的影响掌握了remap在错误处理drop_on_error、drop_on_abort、reroute_dropped与外部程序文件file/files方面的扩展能力了解了lua运行时变换的 v1/v2 演进、钩子式编程模型及其在灵活性与性能、可维护性之间的权衡。相关源码与配置均可在本仓库中继续深入研读remap 变换实现、demo_logs 源实现、lua 变换实现、VRL 函数与测试 以及 VRL 基准测试。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考