尧图网站建设 
Vector VRL 测试框架指南为 Vector Remap Language 编写与运行测试【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读Vector Remap LanguageVRL是 Vector 可观测性数据管线内置的表达式语言用于对日志、指标等事件进行转换。本指南围绕仓库中 lib/vector-vrl/tests/README.md 展开介绍 VRL 专用测试框架Test Harness的设计目标、测试文件的组织方式与语法规范、测试运行命令及 CLI 参数并深入源码讲解其底层实现。读完本文你将能够在不了解 VRL 内部实现和 Rust 语言的前提下为 VRL 新增测试用例、运行并调试测试理解UI testing模式带来的预期失败以及如何规避常见问题。测试框架的定位与设计目标VRL 测试框架位于 lib/vector-vrl/tests 目录它的核心目标是让测试运行在最新构建的 VRL 之上并尽可能降低贡献者编写测试的门槛。从设计意图上看框架刻意做到了以下几点贡献者无需了解 VRL 的内部实现细节也无需掌握 Rust 语言只需编写.vrl脚本文件即可加入测试测试用例统一存放在独立目录中每个子目录都附带各自的文档说明哪类测试应放在哪里测试以输入对象 VRL 程序 期望结果的形式组织本质上是一种快照/输出对比式的行为测试。这一点在 tests 目录结构 中体现得很直观目前仓库中只保留了一个example.vrl示例文件它展示了测试用例的完整结构而实际的测试用例会以.vrl文件的形式持续累积。测试用例的结构与语法前置注释声明输入与期望结果每个测试文件以#开头的注释行声明测试的前提条件# object: { bar: bar, baz: true } # result: { bar: foo, baz: 5, foo: test }# object:声明测试的输入事件对象JSON 格式测试框架会把它作为 VRL 程序执行时的.根对象# result:声明期望输出JSON 格式框架会将程序实际执行结果与此值做严格对比。参考 tests/example.vrl 中的完整示例# object: { bar: bar, baz: true } # result: { bar: foo, baz: 5, foo: test } .foo test .bar foo .baz (to_int(.baz) ?? 0) 4 .这个用例演示了三类典型的 VRL 操作操作说明.foo test在根对象上新增字段foo值为字符串test.bar foo覆盖已有字段bar将bar改为foo.baz (to_int(.baz) ?? 0) 4使用to_int把布尔值true转成整数??提供兜底值再执行加法运算最终得到5.返回整个根对象作为程序结果其中to_int、??coalesce 兜底、算术运算都是 VRL 标准库的典型能力。程序以.结尾将整个对象暴露给测试框架做断言这也是 docs 类测试在比对输出时自动追加; .的原因见下文源码分析。测试文件的存放位置新增测试统一放在tests子目录中即 lib/vector-vrl/tests/tests。每个子目录都有各自的说明文档用来约束哪类测试放哪。编写时如果拿不准可以直接参考example.vrl的写法或在提交时让维护者帮忙调整归属目录。如何运行测试前置条件本地运行测试需要先安装 Rust 已固定了项目使用的工具链版本首次编译会拉取对应组件。由于测试需要编译整个测试二进制第一次运行耗时较长属正常现象。运行命令在lib/vector-vrl/tests目录下执行cargo run即可对当前仓库最新的 VRL 构建运行全部测试。若希望在修改 VRL 或测试文件时持续自动重跑可以借助 cargo-watchcargo watch -x runCLI 参数说明测试二进制基于clap构建参数定义集中在 tests/src/main.rs 的Cmd结构体中。虽然 README 指出当前没有--help但实际支持以下参数参数短选项说明--pattern-p只运行名称包含指定字符串的测试用于过滤--fail-early-f遇到第一个失败即停止适合快速定位回归--verbose-v输出每个测试的详细结果无论通过还是失败--no-diff-d失败时不打印输入/输出的差异对比--logging-l开启 INFO 及以上级别的日志输出--timings-t显示每个测试的执行耗时--timezone-z指定测试时区如UTC、Asia/Shanghai默认 UTC--runtime-r选择 VRL 运行模式VM 或其他默认值见VrlRuntime--ignore-cue—跳过 Cue 文档示例测试加快运行速度注意通过 Cargo 传递参数时需要在cargo run与参数之间加--分隔符cargo run -- --verbose cargo run -- -p example cargo run -- --ignore-cue过滤逻辑在should_run函数中当测试名category/name拼接包含--pattern传入的字符串时才执行此外名为tests/example.vrl的示例文件会被永远跳过避免把模板样例误当成真实测试。底层实现测试从哪来main函数通过get_tests汇总三类测试来源见 tests/src/main.rs 的get_tests与docs.rs1..vrl文件测试框架使用glob匹配tests/**/*.vrl下的所有文件逐文件调用Test::from_path解析出前置注释与程序源码。这是贡献者最常用、也唯一需要直接接触的测试来源。2. Cue 文档示例测试docs 测试通过执行scripts/cue.sh export -e remap从 website/cue 的 VRL 参考文档中提取函数、表达式与程序的示例动态生成测试逻辑见 tests/src/docs.rs。这些示例以结构化字段描述输入input、源码source、返回值return、输出output与预期报错raises。转换时有几个值得注意的细节对非确定性函数如random_bytes、uuid_v4、uuid_v7、now、get_env_var、get_hostname、strip_ansi_escape_codes等通过SKIP_FUNCTION_EXAMPLES常量统一跳过避免测试结果不稳定若示例同时声明了return和output会直接panic报错强制二选一涉及 metric 事件的示例会被跳过当比对对象输出时框架会在程序末尾追加; .保证能正确求值外部对象。3. 函数示例测试框架通过get_tests_from_functions从 vector-vrl-functions 收集函数自带的示例。为避免与 VRL 标准库示例重复代码会用vrl::stdlib::all()生成的functions/{name}类别做过滤。测试运行环境的定制main还通过回调注册了两个自定义测试设施test_enrichment.rs注册一张名为test的静态 enrichment 表find_table_row返回 Bob Smith、find_table_rows返回两条 Smith 记录供依赖 enrichment 能力的 VRL 函数如get_enrichment_table_record测试使用test_vrl_metrics.rs向指标存储中预置一个utilizationGauge 指标值为 0.5带component_idtest标签供 VRL 指标函数测试使用。关于UI testing模式的失败预期当修改 VRL 导致大量测试失败时README 明确说明这是UI testing输出对比型测试模式的正常副作用任何对类型推导、格式输出或程序语义的改动都可能让大量断言的期望值同步变化。目前的应对方式是手动逐个更新测试。框架维护者已计划增加--update-tests标志用于批量更新但在该功能落地前若失败用例数量过大建议直接开 issue 说明情况——这可能比手动更新更省力也便于维护者评估是否需要优先实现批量更新功能。贡献建议如何为 VRL 贡献测试综合 README 与源码向本框架提交测试时的最佳实践如下大胆提交只要测试合理维护者基本都会接纳可能只会建议调整目录、重命名或小幅修改遵守格式.vrl文件必须包含# object:与# result:或# error:类断言前置注释程序以.结尾返回结果对象注意目录归属按各子目录文档把用例放到合适位置不确定时提交后由维护者协助归类善用过滤与排查运行cargo run -- --verbose查看每个用例细节用-p过滤到单个用例快速迭代遇到文档不清晰时开 issue 描述不明确之处维护者会在 issue 中协助解决同时改进文档。如果你更偏好独立的命令行体验仓库还提供了 lib/vector-vrl/cli 这一轻量 CLI 入口见 cli/src/main.rs它注册了全部 Vector 自定义 VRL 函数并复用vrl::cli的命令处理逻辑适合在本地快速试跑单条 VRL 表达式。总结VRL 测试框架用最少的约定注释头 .vrl脚本换来了极低的贡献门槛并通过文件测试 文档示例测试 函数示例测试三层来源把 VRL 标准库、Vector 扩展函数与官方文档示例统一纳入回归保护。理解它的用例格式、运行参数与UI testing特性是参与 Vector 项目贡献、或为 VRL 编写可靠测试的起点。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vector VRL 测试框架指南：为 Vector Remap Language 编写与运行测试
Vector VRL 测试框架指南为 Vector Remap Language 编写与运行测试【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读Vector Remap LanguageVRL是 Vector 可观测性数据管线内置的表达式语言用于对日志、指标等事件进行转换。本指南围绕仓库中 lib/vector-vrl/tests/README.md 展开介绍 VRL 专用测试框架Test Harness的设计目标、测试文件的组织方式与语法规范、测试运行命令及 CLI 参数并深入源码讲解其底层实现。读完本文你将能够在不了解 VRL 内部实现和 Rust 语言的前提下为 VRL 新增测试用例、运行并调试测试理解UI testing模式带来的预期失败以及如何规避常见问题。测试框架的定位与设计目标VRL 测试框架位于 lib/vector-vrl/tests 目录它的核心目标是让测试运行在最新构建的 VRL 之上并尽可能降低贡献者编写测试的门槛。从设计意图上看框架刻意做到了以下几点贡献者无需了解 VRL 的内部实现细节也无需掌握 Rust 语言只需编写.vrl脚本文件即可加入测试测试用例统一存放在独立目录中每个子目录都附带各自的文档说明哪类测试应放在哪里测试以输入对象 VRL 程序 期望结果的形式组织本质上是一种快照/输出对比式的行为测试。这一点在 tests 目录结构 中体现得很直观目前仓库中只保留了一个example.vrl示例文件它展示了测试用例的完整结构而实际的测试用例会以.vrl文件的形式持续累积。测试用例的结构与语法前置注释声明输入与期望结果每个测试文件以#开头的注释行声明测试的前提条件# object: { bar: bar, baz: true } # result: { bar: foo, baz: 5, foo: test }# object:声明测试的输入事件对象JSON 格式测试框架会把它作为 VRL 程序执行时的.根对象# result:声明期望输出JSON 格式框架会将程序实际执行结果与此值做严格对比。参考 tests/example.vrl 中的完整示例# object: { bar: bar, baz: true } # result: { bar: foo, baz: 5, foo: test } .foo test .bar foo .baz (to_int(.baz) ?? 0) 4 .这个用例演示了三类典型的 VRL 操作操作说明.foo test在根对象上新增字段foo值为字符串test.bar foo覆盖已有字段bar将bar改为foo.baz (to_int(.baz) ?? 0) 4使用to_int把布尔值true转成整数??提供兜底值再执行加法运算最终得到5.返回整个根对象作为程序结果其中to_int、??coalesce 兜底、算术运算都是 VRL 标准库的典型能力。程序以.结尾将整个对象暴露给测试框架做断言这也是 docs 类测试在比对输出时自动追加; .的原因见下文源码分析。测试文件的存放位置新增测试统一放在tests子目录中即 lib/vector-vrl/tests/tests。每个子目录都有各自的说明文档用来约束哪类测试放哪。编写时如果拿不准可以直接参考example.vrl的写法或在提交时让维护者帮忙调整归属目录。如何运行测试前置条件本地运行测试需要先安装 Rust 已固定了项目使用的工具链版本首次编译会拉取对应组件。由于测试需要编译整个测试二进制第一次运行耗时较长属正常现象。运行命令在lib/vector-vrl/tests目录下执行cargo run即可对当前仓库最新的 VRL 构建运行全部测试。若希望在修改 VRL 或测试文件时持续自动重跑可以借助 cargo-watchcargo watch -x runCLI 参数说明测试二进制基于clap构建参数定义集中在 tests/src/main.rs 的Cmd结构体中。虽然 README 指出当前没有--help但实际支持以下参数参数短选项说明--pattern-p只运行名称包含指定字符串的测试用于过滤--fail-early-f遇到第一个失败即停止适合快速定位回归--verbose-v输出每个测试的详细结果无论通过还是失败--no-diff-d失败时不打印输入/输出的差异对比--logging-l开启 INFO 及以上级别的日志输出--timings-t显示每个测试的执行耗时--timezone-z指定测试时区如UTC、Asia/Shanghai默认 UTC--runtime-r选择 VRL 运行模式VM 或其他默认值见VrlRuntime--ignore-cue—跳过 Cue 文档示例测试加快运行速度注意通过 Cargo 传递参数时需要在cargo run与参数之间加--分隔符cargo run -- --verbose cargo run -- -p example cargo run -- --ignore-cue过滤逻辑在should_run函数中当测试名category/name拼接包含--pattern传入的字符串时才执行此外名为tests/example.vrl的示例文件会被永远跳过避免把模板样例误当成真实测试。底层实现测试从哪来main函数通过get_tests汇总三类测试来源见 tests/src/main.rs 的get_tests与docs.rs1..vrl文件测试框架使用glob匹配tests/**/*.vrl下的所有文件逐文件调用Test::from_path解析出前置注释与程序源码。这是贡献者最常用、也唯一需要直接接触的测试来源。2. Cue 文档示例测试docs 测试通过执行scripts/cue.sh export -e remap从 website/cue 的 VRL 参考文档中提取函数、表达式与程序的示例动态生成测试逻辑见 tests/src/docs.rs。这些示例以结构化字段描述输入input、源码source、返回值return、输出output与预期报错raises。转换时有几个值得注意的细节对非确定性函数如random_bytes、uuid_v4、uuid_v7、now、get_env_var、get_hostname、strip_ansi_escape_codes等通过SKIP_FUNCTION_EXAMPLES常量统一跳过避免测试结果不稳定若示例同时声明了return和output会直接panic报错强制二选一涉及 metric 事件的示例会被跳过当比对对象输出时框架会在程序末尾追加; .保证能正确求值外部对象。3. 函数示例测试框架通过get_tests_from_functions从 vector-vrl-functions 收集函数自带的示例。为避免与 VRL 标准库示例重复代码会用vrl::stdlib::all()生成的functions/{name}类别做过滤。测试运行环境的定制main还通过回调注册了两个自定义测试设施test_enrichment.rs注册一张名为test的静态 enrichment 表find_table_row返回 Bob Smith、find_table_rows返回两条 Smith 记录供依赖 enrichment 能力的 VRL 函数如get_enrichment_table_record测试使用test_vrl_metrics.rs向指标存储中预置一个utilizationGauge 指标值为 0.5带component_idtest标签供 VRL 指标函数测试使用。关于UI testing模式的失败预期当修改 VRL 导致大量测试失败时README 明确说明这是UI testing输出对比型测试模式的正常副作用任何对类型推导、格式输出或程序语义的改动都可能让大量断言的期望值同步变化。目前的应对方式是手动逐个更新测试。框架维护者已计划增加--update-tests标志用于批量更新但在该功能落地前若失败用例数量过大建议直接开 issue 说明情况——这可能比手动更新更省力也便于维护者评估是否需要优先实现批量更新功能。贡献建议如何为 VRL 贡献测试综合 README 与源码向本框架提交测试时的最佳实践如下大胆提交只要测试合理维护者基本都会接纳可能只会建议调整目录、重命名或小幅修改遵守格式.vrl文件必须包含# object:与# result:或# error:类断言前置注释程序以.结尾返回结果对象注意目录归属按各子目录文档把用例放到合适位置不确定时提交后由维护者协助归类善用过滤与排查运行cargo run -- --verbose查看每个用例细节用-p过滤到单个用例快速迭代遇到文档不清晰时开 issue 描述不明确之处维护者会在 issue 中协助解决同时改进文档。如果你更偏好独立的命令行体验仓库还提供了 lib/vector-vrl/cli 这一轻量 CLI 入口见 cli/src/main.rs它注册了全部 Vector 自定义 VRL 函数并复用vrl::cli的命令处理逻辑适合在本地快速试跑单条 VRL 表达式。总结VRL 测试框架用最少的约定注释头 .vrl脚本换来了极低的贡献门槛并通过文件测试 文档示例测试 函数示例测试三层来源把 VRL 标准库、Vector 扩展函数与官方文档示例统一纳入回归保护。理解它的用例格式、运行参数与UI testing特性是参与 Vector 项目贡献、或为 VRL 编写可靠测试的起点。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考