Vector Filter Transform 完全指南基于条件的日志过滤与路由实战【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读本文围绕 Vector 可观测性数据管道中的filtertransform讲解如何基于一套可组合的“条件”conditions对日志、指标与 trace 事件进行精准筛选并深入源码揭示其实现原理、替代的旧组件以及与之配套的routetransform。读完本文你将掌握filter的完整配置语法、condition 的多种写法VRL 表达式、Datadog Search 查询、事件类型判断以及如何把它与route配合实现复杂分流。一、背景从 conditions 概念到 filter transform1.1 什么是 filter transformfilter是 Vector 在 0.9.0 版本引入的 transform原始发布说明见 website/content/en/highlights/2020-03-31-filter-transform.md其定位一句话概括Filter events based on a set of conditions.基于一组条件过滤事件在数据管道中source 产生的每个事件event会依次流经各 transformfilter的作用是满足条件的放行不满足条件的丢弃。它是日志清理、降噪、选择性下发等场景的基础设施。1.2 conditions 概念的历史铺垫为什么 filter 有底气直接用一个条件表达式完成过滤因为 Vector 在此之前已经系统性引入了conditions条件这一抽象并已在两个场景落地routetransform将事件按多个条件分流到不同输出单元测试unit tests特性在测试中校验事件是否满足预期。正是 conditions 的成熟才让 filter 得以“站在巨人肩膀上”——它只需把 condition 的结果变成“放行/丢弃”的二元决策。官方发布说明中明确指出filter取代了旧的field_filtertransform因为后者只能按字段做等值匹配表达能力远不如前者。二、快速上手第一个 filter 配置以下是最简配置完整继承了发布说明中的示例transforms: haproxy_errors: # General type: filter inputs: [my-source-id] # Conditions condition: level.eq: error service.eq: haproxy该配置的含义只放行level error且service haproxy的事件其余全部丢弃。注意发布说明中的level.eq/service.eq写法是早期版本的字段比较语法。在当前仓库的源码实现中condition 的统一入口是 src/conditions/mod.rs 中的AnyCondition其推荐写法为 VRL 布尔表达式或枚举式 condition见下文第三节。若你的 Vector 版本较新请优先采用下述写法例如transforms: haproxy_errors: type: filter inputs: [my-source-id] condition: .level error .service haproxy两种写法的效果等价满足条件即放行否则丢弃。三、核心机制condition 的三种形态3.1 统一入口 AnyCondition从源码看filter 的配置结构非常简单见 src/transforms/filter.rspub struct FilterConfig { /// 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. condition: AnyCondition, }其中condition的类型是AnyCondition定义于 src/conditions/mod.rs它是一个untagged 枚举意味着配置时可以有两种形态pub enum AnyCondition { /// 直接把 VRL 布尔表达式写成字符串 String(String), /// 完整的、带 type 标签的 condition 对象 Map(ConditionConfig), }也就是说condition既可以是一个裸字符串自动按 VRL 解析也可以是一个带type字段的对象。对应的反序列化测试见 src/conditions/mod.rs。3.2 形态一VRL 布尔表达式最常用VRLVector Remap Language是 Vector 内置的表达式语言。把布尔表达式直接作为字符串即可transforms: keep_errors: type: filter inputs: [in] condition: .level error也可以组合逻辑condition: .level error || (.status_code 500 .service api)VRL condition 的两个硬性约束由 src/conditions/vrl.rs 在编译期强制校验表达式必须返回布尔值——编译时若program.final_type_info().result.is_boolean()为 false构建直接报错VRL conditions must return a boolean.编译期即校验——validate_with_context会在配置校验阶段就调用condition.build语法错误或类型错误会在启动前暴露而不是运行时才发现见 src/transforms/filter.rs。若表达式运行时报错如字段缺失导致的类型错误Vrl::check会发出VrlConditionExecutionError内部事件并返回false即丢弃该事件见 src/conditions/vrl.rs。3.3 形态二枚举式 condition带 type 标签当需要非 VRL 的匹配方式时使用带type的对象形态。ConditionConfig支持以下类型见 src/conditions/mod.rstype说明主要配置项源码位置vrlVRL 布尔表达式source表达式字符串src/conditions/vrl.rsdatadog_searchDatadog Search 查询语法source查询串如NOT foo、service:websrc/conditions/datadog_search.rsis_log/is_metric/is_trace按事件类型匹配无src/conditions/is_log.rs 等示例——用 Datadog Search 语法过滤transforms: keep_web: type: filter inputs: [in] condition: type: datadog_search source: service:web AND NOT debug示例——只保留指标事件transforms: metrics_only: type: filter inputs: [in] condition: type: is_metric3.4 运行时决策check 与事件透传所有 condition 最终统一收敛为Condition枚举其check方法返回(bool, Event)——即“是否匹配 原始事件”见 src/conditions/mod.rs。之所以要把事件原样返回是因为 VRL 求值时事件需要可变访问但 condition 保证不修改事件。filter的运行时逻辑极简src/transforms/filter.rsimpl FunctionTransform for Filter { 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)); // 未命中计数并丢弃 } } }命中即放行、未命中即丢弃整个 transform 是无状态stateless的配置元数据中stateful: false也印证了这一点见 website/cue/reference/components/transforms/filter.cue。四、监控与可观测性被过滤掉的事件去哪儿了被丢弃的事件并非无声无息。Filter内部注册了一个FilterEventsDropped内部事件见 src/internal_events/filter.rsvector_lib::registered_event! ( FilterEventsDropped { events_dropped: RegisteredComponentEventsDroppedstatic, INTENTIONAL register!(ComponentEventsDropped::INTENTIONAL::from( Events matched filter condition. )), } ... );要点指标标签为INTENTIONAL表示“主动丢弃”filter 语义上就是有意的降噪区别于错误导致的意外丢弃统计口径是ComponentEventsDropped即会带上组件维度的元信息你可以在 Vector 内部遥测internal metrics / component events dropped 指标中按组件查看 drop 数量用于评估 filter 的过滤效果是否合理。五、与 route transform 的分工协作发布说明中提到 conditions 最先在routetransform 中落地。理解两者差异才能选对工具维度filterroute输出单一输出命中保留、未命中丢弃多个命名输出每个事件按条件进入对应子流配置核心condition单个条件route条件映射路由名 → 条件未匹配处理直接丢弃默认送入transform._unmatched输出可配置reroute_unmatched: false丢弃源码src/transforms/filter.rssrc/transforms/route.rs典型组合用法用route先分流再用filter对每个子流二次精筛。例如按服务名分流再对每个服务流单独过滤级别transforms: split_by_service: type: route inputs: [in] route: api: .service api web: .service web api_errors: type: filter inputs: [split_by_service.api] condition: .level error web_errors: type: filter inputs: [split_by_service.web] condition: .level errorroute的每条路由条件与 filter 一样都走AnyCondition因此 VRL、datadog_search、is_* 全部通用见 src/transforms/route.rs。六、适用场景与注意事项6.1 典型场景降噪丢弃 debug 级别日志只保留 info 及以上官方 cue 示例正是Drop debug logs见 website/cue/reference/components/transforms/filter.cue按业务规则筛选如只转发特定服务、特定状态码的错误类型筛选在同一管道中混有日志与指标时用is_metric/is_log选择性放行filter 的输入类型覆盖 logs、metrics、traces见同文件input块节省下游成本在下发到昂贵的 sink如 SaaS 平台之前先就地过滤掉无关事件。6.2 注意事项condition 是必填项生成的配置元数据中condition标记为required: true见 website/cue/reference/components/transforms/generated/filter.cue漏写会在校验阶段报错VRL 必须返回布尔返回字符串、数字等非布尔值的表达式无法通过编译旧field_filter已被取代新项目请使用filter condition事件类型透传filter 不改变事件本身输出 schema 与输入保持一致outputs方法直接克隆输入定义见 src/transforms/filter.rs。七、源码验证测试用例是如何保证正确性的src/transforms/filter.rs 内置了两类测试可供你深入理解行为约定generate_config验证FilterConfig能生成合法的默认配置condition: .message valuefilter_basic在完整拓扑中构造一条 log 与一条 metric 事件验证log 被放行与期望输出相等、metric 被丢弃无输出——这直接验证了“条件不满足即丢弃”的核心语义。condition 层同样有详尽的单测例如 src/conditions/vrl.rs 的check_vrl覆盖了布尔表达式求值、to_bool兜底、非布尔返回值的编译报错、以及 metric 事件的字段访问.name、.tags.host、.kind等场景src/conditions/mod.rs 则验证了裸字符串与带 type 对象两种反序列化路径。总结filtertransform 是 Vector 管道中“做减法”的核心组件它把 conditions 抽象提炼为一次干净的二元决策——命中转发、未命中丢弃并记录 INTENTIONAL 丢弃指标。从 0.9.0 取代field_filter起它已经支持 VRL 布尔表达式、Datadog Search 查询与事件类型匹配三种条件形态且与route、单元测试共享同一套 condition 基础设施。掌握它你就掌握了在管道中精准控制数据流向的第一把钥匙。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vector Filter Transform 完全指南：基于条件的日志过滤与路由实战
Vector Filter Transform 完全指南基于条件的日志过滤与路由实战【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读本文围绕 Vector 可观测性数据管道中的filtertransform讲解如何基于一套可组合的“条件”conditions对日志、指标与 trace 事件进行精准筛选并深入源码揭示其实现原理、替代的旧组件以及与之配套的routetransform。读完本文你将掌握filter的完整配置语法、condition 的多种写法VRL 表达式、Datadog Search 查询、事件类型判断以及如何把它与route配合实现复杂分流。一、背景从 conditions 概念到 filter transform1.1 什么是 filter transformfilter是 Vector 在 0.9.0 版本引入的 transform原始发布说明见 website/content/en/highlights/2020-03-31-filter-transform.md其定位一句话概括Filter events based on a set of conditions.基于一组条件过滤事件在数据管道中source 产生的每个事件event会依次流经各 transformfilter的作用是满足条件的放行不满足条件的丢弃。它是日志清理、降噪、选择性下发等场景的基础设施。1.2 conditions 概念的历史铺垫为什么 filter 有底气直接用一个条件表达式完成过滤因为 Vector 在此之前已经系统性引入了conditions条件这一抽象并已在两个场景落地routetransform将事件按多个条件分流到不同输出单元测试unit tests特性在测试中校验事件是否满足预期。正是 conditions 的成熟才让 filter 得以“站在巨人肩膀上”——它只需把 condition 的结果变成“放行/丢弃”的二元决策。官方发布说明中明确指出filter取代了旧的field_filtertransform因为后者只能按字段做等值匹配表达能力远不如前者。二、快速上手第一个 filter 配置以下是最简配置完整继承了发布说明中的示例transforms: haproxy_errors: # General type: filter inputs: [my-source-id] # Conditions condition: level.eq: error service.eq: haproxy该配置的含义只放行level error且service haproxy的事件其余全部丢弃。注意发布说明中的level.eq/service.eq写法是早期版本的字段比较语法。在当前仓库的源码实现中condition 的统一入口是 src/conditions/mod.rs 中的AnyCondition其推荐写法为 VRL 布尔表达式或枚举式 condition见下文第三节。若你的 Vector 版本较新请优先采用下述写法例如transforms: haproxy_errors: type: filter inputs: [my-source-id] condition: .level error .service haproxy两种写法的效果等价满足条件即放行否则丢弃。三、核心机制condition 的三种形态3.1 统一入口 AnyCondition从源码看filter 的配置结构非常简单见 src/transforms/filter.rspub struct FilterConfig { /// 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. condition: AnyCondition, }其中condition的类型是AnyCondition定义于 src/conditions/mod.rs它是一个untagged 枚举意味着配置时可以有两种形态pub enum AnyCondition { /// 直接把 VRL 布尔表达式写成字符串 String(String), /// 完整的、带 type 标签的 condition 对象 Map(ConditionConfig), }也就是说condition既可以是一个裸字符串自动按 VRL 解析也可以是一个带type字段的对象。对应的反序列化测试见 src/conditions/mod.rs。3.2 形态一VRL 布尔表达式最常用VRLVector Remap Language是 Vector 内置的表达式语言。把布尔表达式直接作为字符串即可transforms: keep_errors: type: filter inputs: [in] condition: .level error也可以组合逻辑condition: .level error || (.status_code 500 .service api)VRL condition 的两个硬性约束由 src/conditions/vrl.rs 在编译期强制校验表达式必须返回布尔值——编译时若program.final_type_info().result.is_boolean()为 false构建直接报错VRL conditions must return a boolean.编译期即校验——validate_with_context会在配置校验阶段就调用condition.build语法错误或类型错误会在启动前暴露而不是运行时才发现见 src/transforms/filter.rs。若表达式运行时报错如字段缺失导致的类型错误Vrl::check会发出VrlConditionExecutionError内部事件并返回false即丢弃该事件见 src/conditions/vrl.rs。3.3 形态二枚举式 condition带 type 标签当需要非 VRL 的匹配方式时使用带type的对象形态。ConditionConfig支持以下类型见 src/conditions/mod.rstype说明主要配置项源码位置vrlVRL 布尔表达式source表达式字符串src/conditions/vrl.rsdatadog_searchDatadog Search 查询语法source查询串如NOT foo、service:websrc/conditions/datadog_search.rsis_log/is_metric/is_trace按事件类型匹配无src/conditions/is_log.rs 等示例——用 Datadog Search 语法过滤transforms: keep_web: type: filter inputs: [in] condition: type: datadog_search source: service:web AND NOT debug示例——只保留指标事件transforms: metrics_only: type: filter inputs: [in] condition: type: is_metric3.4 运行时决策check 与事件透传所有 condition 最终统一收敛为Condition枚举其check方法返回(bool, Event)——即“是否匹配 原始事件”见 src/conditions/mod.rs。之所以要把事件原样返回是因为 VRL 求值时事件需要可变访问但 condition 保证不修改事件。filter的运行时逻辑极简src/transforms/filter.rsimpl FunctionTransform for Filter { 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)); // 未命中计数并丢弃 } } }命中即放行、未命中即丢弃整个 transform 是无状态stateless的配置元数据中stateful: false也印证了这一点见 website/cue/reference/components/transforms/filter.cue。四、监控与可观测性被过滤掉的事件去哪儿了被丢弃的事件并非无声无息。Filter内部注册了一个FilterEventsDropped内部事件见 src/internal_events/filter.rsvector_lib::registered_event! ( FilterEventsDropped { events_dropped: RegisteredComponentEventsDroppedstatic, INTENTIONAL register!(ComponentEventsDropped::INTENTIONAL::from( Events matched filter condition. )), } ... );要点指标标签为INTENTIONAL表示“主动丢弃”filter 语义上就是有意的降噪区别于错误导致的意外丢弃统计口径是ComponentEventsDropped即会带上组件维度的元信息你可以在 Vector 内部遥测internal metrics / component events dropped 指标中按组件查看 drop 数量用于评估 filter 的过滤效果是否合理。五、与 route transform 的分工协作发布说明中提到 conditions 最先在routetransform 中落地。理解两者差异才能选对工具维度filterroute输出单一输出命中保留、未命中丢弃多个命名输出每个事件按条件进入对应子流配置核心condition单个条件route条件映射路由名 → 条件未匹配处理直接丢弃默认送入transform._unmatched输出可配置reroute_unmatched: false丢弃源码src/transforms/filter.rssrc/transforms/route.rs典型组合用法用route先分流再用filter对每个子流二次精筛。例如按服务名分流再对每个服务流单独过滤级别transforms: split_by_service: type: route inputs: [in] route: api: .service api web: .service web api_errors: type: filter inputs: [split_by_service.api] condition: .level error web_errors: type: filter inputs: [split_by_service.web] condition: .level errorroute的每条路由条件与 filter 一样都走AnyCondition因此 VRL、datadog_search、is_* 全部通用见 src/transforms/route.rs。六、适用场景与注意事项6.1 典型场景降噪丢弃 debug 级别日志只保留 info 及以上官方 cue 示例正是Drop debug logs见 website/cue/reference/components/transforms/filter.cue按业务规则筛选如只转发特定服务、特定状态码的错误类型筛选在同一管道中混有日志与指标时用is_metric/is_log选择性放行filter 的输入类型覆盖 logs、metrics、traces见同文件input块节省下游成本在下发到昂贵的 sink如 SaaS 平台之前先就地过滤掉无关事件。6.2 注意事项condition 是必填项生成的配置元数据中condition标记为required: true见 website/cue/reference/components/transforms/generated/filter.cue漏写会在校验阶段报错VRL 必须返回布尔返回字符串、数字等非布尔值的表达式无法通过编译旧field_filter已被取代新项目请使用filter condition事件类型透传filter 不改变事件本身输出 schema 与输入保持一致outputs方法直接克隆输入定义见 src/transforms/filter.rs。七、源码验证测试用例是如何保证正确性的src/transforms/filter.rs 内置了两类测试可供你深入理解行为约定generate_config验证FilterConfig能生成合法的默认配置condition: .message valuefilter_basic在完整拓扑中构造一条 log 与一条 metric 事件验证log 被放行与期望输出相等、metric 被丢弃无输出——这直接验证了“条件不满足即丢弃”的核心语义。condition 层同样有详尽的单测例如 src/conditions/vrl.rs 的check_vrl覆盖了布尔表达式求值、to_bool兜底、非布尔返回值的编译报错、以及 metric 事件的字段访问.name、.tags.host、.kind等场景src/conditions/mod.rs 则验证了裸字符串与带 type 对象两种反序列化路径。总结filtertransform 是 Vector 管道中“做减法”的核心组件它把 conditions 抽象提炼为一次干净的二元决策——命中转发、未命中丢弃并记录 INTENTIONAL 丢弃指标。从 0.9.0 取代field_filter起它已经支持 VRL 布尔表达式、Datadog Search 查询与事件类型匹配三种条件形态且与route、单元测试共享同一套 condition 基础设施。掌握它你就掌握了在管道中精准控制数据流向的第一把钥匙。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
