尧图网页设计 
Vector 条件谓词Condition Predicates完全指南从过滤、路由到单元测试的事件匹配体系【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读本文围绕 Vector 数据管道中的核心概念——**condition条件**展开深入讲解其在新版中如何用于filter与route旧称swimlanes变换、单元测试断言等场景并完整梳理begins_with、contains、ends_with、is_log、is_metric、regex等谓词的现代等价写法。读完本文你将掌握在 Vector 配置中以条件表达式精确筛选、分流与校验日志/指标事件的完整方案并能结合源码理解条件的底层执行机制。说明本文主题源自 Vector 0.9.0 引入的一组新条件谓词见 原始变更说明。当前仓库中旧式的字符串谓词已统一收敛为 VRL 表达式与结构化的条件类型本文会同时给出历史背景与现行写法保证配置可直接套用。什么是 Vector 的 conditionVector 中有一个名为condition的概念用于对事件进行资格判定qualify events。其核心定义位于 src/conditions/mod.rs源码注释明确指出An event matching condition. Many methods exist for matching events, such as using a VRL expression, a Datadog Search query string, or hard-coded matchers like must be a metric.即 condition 的职责是回答某个事件是否满足条件。它被广泛复用于三类场景单元测试特性在测试配置中断言某条输入事件是否通过期望条件routeswimlanes变换将事件流按多个条件拆分到不同输出分支filter变换按条件决定事件是放行还是丢弃。从 src/conditions/mod.rs 的ConditionConfig枚举可以看出condition 是一等配置类型支持condition: type: datadog_search source: NOT foo也支持直接传入 VRL 字符串表达式AnyCondition的String变体见 src/conditions/mod.rscondition: .message hooray新增的谓词历史版本与现行写法2020-04 发布的 0.9.0 版本为 condition 增加了以下谓词begins_withcontainsends_withis_logis_metricregex在当时的配置中它们以字段路径 短横线谓词的形式书写。例如原始变更说明给出的过滤示例transforms: errors: type: filter condition: message.contain: error即在事件字段message上应用containcontains 的缩写形式谓词命中即放行。当前仓库中的等价写法当前仓库中filter/route的条件统一通过AnyCondition解析src/conditions/mod.rs底层执行由 VRLVector Remap Language承担。因此上述示例的现行等价写法为transforms: errors: type: filter condition: contains!(.message, error)contains!与contains都是 VRL 内置函数前者在字段缺失/类型不符时抛出错误适合严格校验后者返回false适合宽松过滤谓词与字段的关系不再通过 YAML 键书写而是统一使用 VRL 的点号路径如.message与函数调用语法。下表给出新旧写法对照便于从旧配置迁移旧谓词含义现行 VRL 写法begins_with前缀匹配starts_with!(.message, prefix)contains包含匹配contains!(.message, substring)ends_with后缀匹配ends_with!(.message, suffix)regex正则匹配match!(.message, rregex-pattern)is_log是否为日志事件type log或结构化条件见下文is_metric是否为指标事件type metric或结构化条件事实边界旧谓词在 0.9.0 时代的精确短横线语法如message.contain在当前仓库配置文档中已不再出现上表的现行写法基于 src/transforms/filter.rs 对AnyCondition的解析实现与 VRL 函数体系推断得出请以你所用 Vector 版本的vector generate component输出为准。在 filter 变换中使用条件事件放行还是丢弃filter变换的语义非常明确见 src/transforms/filter.rs 的配置文档The condition that every input event is matched against. If an event is matched by the condition, it is forwarded. Otherwise, the event is dropped.匹配 → 转发forwarded不匹配 → 丢弃dropped。完整示例一过滤包含 error 的日志sources: app_logs: type: file include: [/var/log/app/*.log] transforms: errors: type: filter condition: contains!(.message, error) sinks: error_sink: type: console inputs: [errors] encoding: codec: json完整示例二同时过滤多个字段并组合逻辑VRL 支持、||与括号组合一次即可表达复杂条件transforms: high_severity_errors: type: filter condition: contains!(.message, error) .level critical源码级的执行链路从 src/transforms/filter.rs 可以看到每个进入filter的事件都会调用self.condition.check(event)fn transform(mut self, output: mut OutputBuffer, event: Event) { let (result, event) self.condition.check(event); if result { output.push(event); } else { self.events_dropped.emit(Count(1)); } }Condition::check的实现在 src/conditions/mod.rs对 VRL 条件执行编译后的程序对IsLog/IsMetric/IsTrace则走专门的快速判定。值得注意的是被丢弃的事件会通过FilterEventsDropped内部事件计数可在观测面板上看到丢弃量——排查事件莫名消失时可先看这个指标。按事件类型过滤如果你只想保留日志丢弃指标/追踪除了 VRL 的type判断还可以直接使用结构化的条件类型。历史版本中的is_log/is_metric谓词在当前仓库中对应ConditionConfig的IsLog/IsMetric/IsTrace变体src/conditions/mod.rs其判定实现分别在 src/conditions/is_log.rs 与 src/conditions/is_metric.rs// is_log pub(crate) const fn check_is_log(e: Event) - (bool, Event) { (matches!(e, Event::Log(_)), e) }对应的配置写法transforms: logs_only: type: filter condition: type: is_log而 src/transforms/filter.rs 的filter_basic测试用例恰好验证了这一组合先以ConditionConfig::IsLog构建 filter发送一条日志事件断言其被转发再发送一条 Counter 指标事件断言其被丢弃。在 route 变换中使用条件一进多出的事件分流route变换历史上叫swimlanes允许把单条事件流按用户给定的多组条件拆分成多个子流。其配置结构在 src/transforms/route.rs 中定义route是一个输出名 → 条件的映射表。transforms: router: type: route reroute_unmatched: true route: foo-exists: exists!(.foo) foo-does-not-exist: !exists!(.foo)上述示例直接取自 src/transforms/route.rs 的route_examples()生成配置每个路由分支对应一个独立的输出通道事件会依次对每个分支执行condition.check(event.clone())src/transforms/route.rs命中哪个分支就进入哪个输出reroute_unmatched为true时所有分支都不命中的事件会被转发到_unmatched输出避免静默丢失。组合谓词的分流示例结合 contains 与 is_log 可实现按内容分流transforms: router: type: route route: error_logs: type log contains!(.message, error) audit_events: type log contains!(.message, audit) metrics_only: type metric sinks: errors: type: console inputs: [router.error_logs] encoding: { codec: json } audits: type: console inputs: [router.audit_events] encoding: { codec: json }在单元测试中使用条件断言事件的通过/失败condition 的第三个核心应用场景是 Vector 的单元测试特性src/unit_test.rs。测试配置中的no_outputs_from、outputs[].conditions等断言都依赖条件判定例如断言某条输入在变换后不产生任何输出即被 filter 丢弃可写作tests: - name: drop non-error logs inputs: - type: log data: message: info message no_outputs_from: [errors] - name: keep error logs inputs: - type: log data: message: an error occurred outputs: - extract_from: errors conditions: - contains!(.message, error)这样新增谓词带来的表达能力可以直接沉淀为自动化回归测试保证过滤/路由逻辑在配置演进中不被破坏。底层机制Condition与AnyCondition的类型体系为了帮助你理解条件表达式在配置中的两种书写方式这里总结 src/conditions/mod.rs 中的类型层次ConditionConfig带type标签的枚举is_log、is_metric、is_trace、vrl、datadog_search五种结构化条件AnyConditionuntagged 枚举要么是裸字符串自动按 VRL 表达式编译src/conditions/mod.rs要么是完整 Map即ConditionConfigCondition运行时求值枚举由ConditionConfig::build在配置加载阶段构造持有编译后的 VRL 程序或类型判定函数Conditional/ConditionalConfigtraitfilter、route等组件依赖的抽象接口提供check与check_with_context两个求值入口。在配置校验阶段filter的validate_with_context会直接调用condition.validate(...)src/transforms/filter.rs这意味着非法的 VRL 条件在vector validate阶段就会被报错而不是运行到一半才失败——建议在 CI 中把vector validate --no-environment作为配置提交的强制检查。最佳实践小结字段缺失保护过滤类场景优先使用不带!的contains/starts_with/ends_with返回false而非报错避免因个别事件缺字段而整条管道报错正则注意转义match!(.message, r^5\d{2}$)这类正则建议使用r...原始字符串语法减少转义层级按类型分流用结构化条件纯日志/指标判定用condition.type: is_log等枚举形式比 VRL 字符串更直观且免编译开销关注丢弃指标filter丢弃事件会产出filter_events_dropped内部指标分流效果可通过该指标与各分支输出量交叉验证测试先行把每个 predicate 组合写成单元测试断言借助vector test命令在本地与 CI 中持续验证。延伸阅读filter 变换实现条件放行/丢弃的完整实现与测试用例route 变换实现多分支条件路由的实现与route_pass_all_route_conditions等测试条件类型体系Condition/ConditionConfig/AnyCondition的完整定义is_log 判定 与 is_metric 判定事件类型判定源码与对应测试单元测试实现基于条件断言配置级测试的运行入口VRL 函数目录contains、starts_with、ends_with、match等函数实现【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vector 条件谓词（Condition Predicates）完全指南：从过滤、路由到单元测试的事件匹配体系
Vector 条件谓词Condition Predicates完全指南从过滤、路由到单元测试的事件匹配体系【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读本文围绕 Vector 数据管道中的核心概念——**condition条件**展开深入讲解其在新版中如何用于filter与route旧称swimlanes变换、单元测试断言等场景并完整梳理begins_with、contains、ends_with、is_log、is_metric、regex等谓词的现代等价写法。读完本文你将掌握在 Vector 配置中以条件表达式精确筛选、分流与校验日志/指标事件的完整方案并能结合源码理解条件的底层执行机制。说明本文主题源自 Vector 0.9.0 引入的一组新条件谓词见 原始变更说明。当前仓库中旧式的字符串谓词已统一收敛为 VRL 表达式与结构化的条件类型本文会同时给出历史背景与现行写法保证配置可直接套用。什么是 Vector 的 conditionVector 中有一个名为condition的概念用于对事件进行资格判定qualify events。其核心定义位于 src/conditions/mod.rs源码注释明确指出An event matching condition. Many methods exist for matching events, such as using a VRL expression, a Datadog Search query string, or hard-coded matchers like must be a metric.即 condition 的职责是回答某个事件是否满足条件。它被广泛复用于三类场景单元测试特性在测试配置中断言某条输入事件是否通过期望条件routeswimlanes变换将事件流按多个条件拆分到不同输出分支filter变换按条件决定事件是放行还是丢弃。从 src/conditions/mod.rs 的ConditionConfig枚举可以看出condition 是一等配置类型支持condition: type: datadog_search source: NOT foo也支持直接传入 VRL 字符串表达式AnyCondition的String变体见 src/conditions/mod.rscondition: .message hooray新增的谓词历史版本与现行写法2020-04 发布的 0.9.0 版本为 condition 增加了以下谓词begins_withcontainsends_withis_logis_metricregex在当时的配置中它们以字段路径 短横线谓词的形式书写。例如原始变更说明给出的过滤示例transforms: errors: type: filter condition: message.contain: error即在事件字段message上应用containcontains 的缩写形式谓词命中即放行。当前仓库中的等价写法当前仓库中filter/route的条件统一通过AnyCondition解析src/conditions/mod.rs底层执行由 VRLVector Remap Language承担。因此上述示例的现行等价写法为transforms: errors: type: filter condition: contains!(.message, error)contains!与contains都是 VRL 内置函数前者在字段缺失/类型不符时抛出错误适合严格校验后者返回false适合宽松过滤谓词与字段的关系不再通过 YAML 键书写而是统一使用 VRL 的点号路径如.message与函数调用语法。下表给出新旧写法对照便于从旧配置迁移旧谓词含义现行 VRL 写法begins_with前缀匹配starts_with!(.message, prefix)contains包含匹配contains!(.message, substring)ends_with后缀匹配ends_with!(.message, suffix)regex正则匹配match!(.message, rregex-pattern)is_log是否为日志事件type log或结构化条件见下文is_metric是否为指标事件type metric或结构化条件事实边界旧谓词在 0.9.0 时代的精确短横线语法如message.contain在当前仓库配置文档中已不再出现上表的现行写法基于 src/transforms/filter.rs 对AnyCondition的解析实现与 VRL 函数体系推断得出请以你所用 Vector 版本的vector generate component输出为准。在 filter 变换中使用条件事件放行还是丢弃filter变换的语义非常明确见 src/transforms/filter.rs 的配置文档The condition that every input event is matched against. If an event is matched by the condition, it is forwarded. Otherwise, the event is dropped.匹配 → 转发forwarded不匹配 → 丢弃dropped。完整示例一过滤包含 error 的日志sources: app_logs: type: file include: [/var/log/app/*.log] transforms: errors: type: filter condition: contains!(.message, error) sinks: error_sink: type: console inputs: [errors] encoding: codec: json完整示例二同时过滤多个字段并组合逻辑VRL 支持、||与括号组合一次即可表达复杂条件transforms: high_severity_errors: type: filter condition: contains!(.message, error) .level critical源码级的执行链路从 src/transforms/filter.rs 可以看到每个进入filter的事件都会调用self.condition.check(event)fn transform(mut self, output: mut OutputBuffer, event: Event) { let (result, event) self.condition.check(event); if result { output.push(event); } else { self.events_dropped.emit(Count(1)); } }Condition::check的实现在 src/conditions/mod.rs对 VRL 条件执行编译后的程序对IsLog/IsMetric/IsTrace则走专门的快速判定。值得注意的是被丢弃的事件会通过FilterEventsDropped内部事件计数可在观测面板上看到丢弃量——排查事件莫名消失时可先看这个指标。按事件类型过滤如果你只想保留日志丢弃指标/追踪除了 VRL 的type判断还可以直接使用结构化的条件类型。历史版本中的is_log/is_metric谓词在当前仓库中对应ConditionConfig的IsLog/IsMetric/IsTrace变体src/conditions/mod.rs其判定实现分别在 src/conditions/is_log.rs 与 src/conditions/is_metric.rs// is_log pub(crate) const fn check_is_log(e: Event) - (bool, Event) { (matches!(e, Event::Log(_)), e) }对应的配置写法transforms: logs_only: type: filter condition: type: is_log而 src/transforms/filter.rs 的filter_basic测试用例恰好验证了这一组合先以ConditionConfig::IsLog构建 filter发送一条日志事件断言其被转发再发送一条 Counter 指标事件断言其被丢弃。在 route 变换中使用条件一进多出的事件分流route变换历史上叫swimlanes允许把单条事件流按用户给定的多组条件拆分成多个子流。其配置结构在 src/transforms/route.rs 中定义route是一个输出名 → 条件的映射表。transforms: router: type: route reroute_unmatched: true route: foo-exists: exists!(.foo) foo-does-not-exist: !exists!(.foo)上述示例直接取自 src/transforms/route.rs 的route_examples()生成配置每个路由分支对应一个独立的输出通道事件会依次对每个分支执行condition.check(event.clone())src/transforms/route.rs命中哪个分支就进入哪个输出reroute_unmatched为true时所有分支都不命中的事件会被转发到_unmatched输出避免静默丢失。组合谓词的分流示例结合 contains 与 is_log 可实现按内容分流transforms: router: type: route route: error_logs: type log contains!(.message, error) audit_events: type log contains!(.message, audit) metrics_only: type metric sinks: errors: type: console inputs: [router.error_logs] encoding: { codec: json } audits: type: console inputs: [router.audit_events] encoding: { codec: json }在单元测试中使用条件断言事件的通过/失败condition 的第三个核心应用场景是 Vector 的单元测试特性src/unit_test.rs。测试配置中的no_outputs_from、outputs[].conditions等断言都依赖条件判定例如断言某条输入在变换后不产生任何输出即被 filter 丢弃可写作tests: - name: drop non-error logs inputs: - type: log data: message: info message no_outputs_from: [errors] - name: keep error logs inputs: - type: log data: message: an error occurred outputs: - extract_from: errors conditions: - contains!(.message, error)这样新增谓词带来的表达能力可以直接沉淀为自动化回归测试保证过滤/路由逻辑在配置演进中不被破坏。底层机制Condition与AnyCondition的类型体系为了帮助你理解条件表达式在配置中的两种书写方式这里总结 src/conditions/mod.rs 中的类型层次ConditionConfig带type标签的枚举is_log、is_metric、is_trace、vrl、datadog_search五种结构化条件AnyConditionuntagged 枚举要么是裸字符串自动按 VRL 表达式编译src/conditions/mod.rs要么是完整 Map即ConditionConfigCondition运行时求值枚举由ConditionConfig::build在配置加载阶段构造持有编译后的 VRL 程序或类型判定函数Conditional/ConditionalConfigtraitfilter、route等组件依赖的抽象接口提供check与check_with_context两个求值入口。在配置校验阶段filter的validate_with_context会直接调用condition.validate(...)src/transforms/filter.rs这意味着非法的 VRL 条件在vector validate阶段就会被报错而不是运行到一半才失败——建议在 CI 中把vector validate --no-environment作为配置提交的强制检查。最佳实践小结字段缺失保护过滤类场景优先使用不带!的contains/starts_with/ends_with返回false而非报错避免因个别事件缺字段而整条管道报错正则注意转义match!(.message, r^5\d{2}$)这类正则建议使用r...原始字符串语法减少转义层级按类型分流用结构化条件纯日志/指标判定用condition.type: is_log等枚举形式比 VRL 字符串更直观且免编译开销关注丢弃指标filter丢弃事件会产出filter_events_dropped内部指标分流效果可通过该指标与各分支输出量交叉验证测试先行把每个 predicate 组合写成单元测试断言借助vector test命令在本地与 CI 中持续验证。延伸阅读filter 变换实现条件放行/丢弃的完整实现与测试用例route 变换实现多分支条件路由的实现与route_pass_all_route_conditions等测试条件类型体系Condition/ConditionConfig/AnyCondition的完整定义is_log 判定 与 is_metric 判定事件类型判定源码与对应测试单元测试实现基于条件断言配置级测试的运行入口VRL 函数目录contains、starts_with、ends_with、match等函数实现【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考