Vector 组件开发规范（Component Specification）全解析：命名、配置、可观测性与 Sink 运维要求

Vector 组件开发规范Component Specification全解析命名、配置、可观测性与 Sink 运维要求【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读本文基于 Vector 开源仓库的 Component Specificationdocs/specs/component.md展开系统梳理 Vector 中 source、transform、sink 三类组件必须遵守的统一行为规范从命名约定、配置项设计到组件可观测性事件的强制/建议清单再到 Sink 健康检查、事件 finalization 与端到端确认acknowledgements的运维要求。读完本文你将掌握为 Vector 开发新组件时的完整行为契约并能对照仓库源码如 events_received.rs、sink.rs理解这些规范在实现层面的落地方式。引言为什么需要组件规范Vector 是一款高性能可观测性数据管道其核心处理模型是有向无环图DAG图中的每个节点都是一个 Vector 组件source、transform 或 sink。为了让这些组件在拓扑中无缝协作、提供一致的用户体验每个组件都必须遵守一组公共行为规则。这份 Component Specification 就是这些规则的权威定义用于指导新组件的开发与存量组件的持续维护。文档全文使用 RFC 2119 级别的关键字来区分义务强度MUST / MUST NOT / REQUIRED强制性要求组件必须满足SHALL / SHALL NOT强制性要求规范性用语SHOULD / SHOULD NOT / RECOMMENDED建议性要求在合理前提下应满足MAY / OPTIONAL可选行为完全由实现者决定。这套语义贯穿全文例如组件 MUST 发出ComponentEventsReceived事件表示这是硬性契约而Sink SHOULD 定义健康检查则属于强烈建议。适用范围Scope本规范只约束组件自身的直接行为不包括组件免费继承的全局能力。最典型的例子是遥测中的component_id标签——所有组件只要成为 Vector 拓扑中的一员就会自动获得这类全局上下文无需在组件代码中单独处理。此外除特别注明外规范中的每一节默认适用于全部三类组件sources、transforms、sinks。例如事件接收相关要求对 source 而言指从上游网络/文件接收对 transform 而言指从上游组件接收。命名规范Naming组件命名必须与组件逻辑边界对齐使组件名称能直观反映其职责。规范按组件类型给出了不同要求。Source 与 Sink 命名MUST只包含 ASCII 字母小写、数字与下划线MUST用名词命名且名词取自组件所集成的协议或服务如kubernetes_logs、apache_metrics仅当组件特定于某种事件类型时MAY追加事件类型后缀logs、metrics或traces。以仓库为例sources/datadog_agent、sources/kubernetes_logs、sinks/aws_s3都是协议/服务名词命名而kubernetes_logs、apache_metrics、host_metrics、eventstoredb_metrics、nginx_metrics则展示了metrics后缀的用法——它们都明确只消费对应来源的指标事件。datadog_agent、splunk_hec这类组件同时接收 logs 与 traces/metrics因此不带事件类型后缀。Transform 命名MUST只包含 ASCII 字母小写、数字与下划线MUST使用动词描述 transform 的广义目的如route、sample、delegate。这与 transform 的本质相吻合它是对事件流的动作而非外部实体。仓库中 transforms 目录的命名正是如此filter过滤、route路由、sample采样、reduce归并、dedupe去重、throttle限流、log_to_metric日志转指标等全部是动词形态。配置规范Configuration本规范在配置规范之上针对组件补充了两类端点类配置项的设计要求。endpoint(s)选项当组件需要连接下游目标时SHOULD暴露以下两种形式之一选项类型语义endpointstring单个端点endpointsstring[]多个端点组成的数组此外存在一条强约束如果组件通过多个选项自动拼接出端点那么endpoint(s)选项 MUST 覆盖override该自动拼接过程。这意味着显式配置的端点拥有最高优先级是组件的最终决定权。从源码结构看仓库中的网络型 Sink如 http、aws_s3、elasticsearch 等普遍遵循这一模式用endpoint或endpoints作为服务地址的入口同时保留region、bucket等辅助选项用于在未显式指定端点时自动推导完整地址。listen选项当组件监听入站连接时SHOULD暴露listen选项其值为protocol:address形式的字符串。协议可选值如下协议值地址格式说明unixstream文件路径Unix 域套接字流式unixdatagram文件路径Unix 域套接字数据报unix文件路径等价于unixstreamtcphost:portTCP 监听udphost:portUDP 监听组件MAY提供默认协议。例如一个statsd组件可以默认使用udp协议用户只需提供host:port即可完成绑定。仓库中的 statsd 源 正是这种做法的典型它以 UDP 为默认协议接收指标数据同时支持 TCP 与 Unix 套接字模式。可观测性规范Instrumentation本规范扩展自可观测性规范核心要求是Vector 组件 MUST 被插桩instrumented以获得最佳可观测性。Vector 采用事件驱动的遥测模式见 RFC 2064内部事件是遥测的载体指标与日志由事件驱动发出而不是在代码中直接散落metrics::increment_counter与tracing::log调用。事件清单与实现弹性本规范列出组件 MUST 发出的事件以及 RECOMMENDED仍属 OPTIONAL的事件。组件被期望在列出的基础事件之外发出体现自身特性的自定义事件。规范为实现预留了合理弹性事件MAY附加组件特定的上下文。例如socket源会额外添加mode属性事件命名MAY为满足实现而调整。例如socket源可以把EventReceived重命名为SocketEventReceived以携带更多套接字上下文组件MAY出于性能原因按批次发出事件但产生的遥测状态必须与逐条发出等价例如一次发出 10 个事件的EventsReceived必须让component_received_events_total计数器累加 10。这一点在源码中有直接体现。以 events_received.rs 为例其核心实现为crate::registered_event!( EventsReceived { events_count: Histogram histogram!(HistogramName::ComponentReceivedEventsCount), events: Counter counter!(CounterName::ComponentReceivedEventsTotal), event_bytes: Counter counter!(CounterName::ComponentReceivedEventBytesTotal), } fn emit(self, data: CountByteSize) { let CountByteSize(count, byte_size) data; trace!(message Events received., count %count, byte_size %byte_size); self.events_count.record(count as f64); self.events.increment(count as u64); self.event_bytes.increment(byte_size.get() as u64); } );可见每个事件同时驱动一条trace级日志与多个计数器/直方图且事件名、指标名与规范一一对应。事件定义集中在 lib/vector-common/src/internal_event/mod.rs包括EventsReceived、BytesReceived、BytesSent、EventsSent、ComponentEventsDropped等均通过registered_event!宏统一注册便于集中管理。ComponentEventsReceived所有组件 MUST 发出表示从上游组件接收到 Vector 事件。发出时机MUST 在创建或接收到 Vector 事件后、任何修改或元数据附加之前立即发出属性count事件数量、byte_size所有收到事件的预估 JSON 字节大小指标MUST 按quantity属性累加component_received_events_total计数器、按byte_size属性累加component_received_event_bytes_total计数器其余属性作为指标标签日志MUST 以trace级别记录Events received.消息属性作为键值对MUST NOT 限流。注意规范标注该事件将在SourceNetworkBytesReceived落地后被弃用。ComponentBytesReceivedSources MUST 发出表示字节的接收发生在字节被解析成事件之前。发出时机MUST 在从上游接收、解压并过滤字节后、创建 Vector 事件之前立即发出属性byte_sizeUDP/TCP/Unix 协议下为从套接字收到的总字节数不含分隔符HTTP 类协议为解压后的 HTTP body 字节数文件场景为从文件读取的总字节数不含分隔符protocol发送字节所用的协议tcp、udp、unix、http、https、file等http_path如相关不含查询字符串的 HTTP 路径指标MUST 累加component_received_bytes_total计数器日志MUST 以trace级别记录Bytes received.MUST NOT 限流。源码实现见 bytes_received.rs其中protocol被作为计数器标签传入crate::registered_event!( BytesReceived { protocol: SharedString, } { received_bytes: Counter counter!(CounterName::ComponentReceivedBytesTotal, protocol self.protocol.clone()), protocol: SharedString self.protocol, } fn emit(self, data: ByteSize) { self.received_bytes.increment(data.0 as u64); trace!(message Bytes received., byte_size %data.0, protocol %self.protocol); } );ComponentBytesSentSinks MUST 发出表示字节的下游传输。发出时机MUST 在成功向下游目标发送字节后立即发出报告的字节数必须在压缩之前例外只暴露数据、发送后不删除数据的 Sink如prometheus_exporterSHOULD NOT发出该指标属性byte_size各协议定义与接收侧对称但压缩前统计、protocol、endpointHTTP 下必须是主机与路径不含查询字符串、file如相关文件的绝对路径指标MUST 累加component_sent_bytes_total计数器日志MUST 以trace级别记录Bytes sent.MUST NOT 限流。ComponentEventsSent所有组件 MUST 发出表示向下一个下游组件发送 Vector 事件。发出时机MUST 在事件成功传输后立即发出传输失败MUST NOT发出例外拉取型pull-basedSink 不发送事件MUST NOT发出该事件如prometheus_exporter属性count、byte_size预估 JSON 字节、outputOPTIONAL多输出组件的输出名发送到默认输出时该值MUST为_default指标MUST 累加component_sent_events_total与component_sent_event_bytes_total日志MUST 以trace级别记录Events sent.MUST NOT 限流。_default常量在源码中定义为 events_sent.rs 中的pub const DEFAULT_OUTPUT: str _default;。EventsSent事件携带可选的output标签多输出组件如routetransform 或支持多 endpoint 的 Sink据此区分事件流向同文件中的TaggedEventsSent变体还支持按source、service标签细分遥测。ComponentError所有组件 MUST 发出所有组件 MUST 依据可观测性规范中的 Error 事件要求发出错误事件。规范不列出组件必须实现的统一错误集合因为错误天然与组件相关。结合 instrumentation.md错误事件需满足属性error_code仅在比error_type提供更多信息时指定且取值必须是低基数有界集合如invalid_json禁止使用高可变性的 serde 原始错误消息、error_type必须取自 cue 文档枚举、stage必须是receiving、processing、sending之一指标属性作为标签MUST 累加namespace_errors_total指标日志MUST 以error级别记录描述性日志SHOULD 限流 10 秒联动若错误导致事件被丢弃MUST 再发出EventsDropped事件组件启动失败时无需发出错误事件Vector 将无法启动指标不会被采集但仍应记录日志。stage与error_type的取值常量定义在 prelude.rs如error_stage::RECEIVING、error_type::CONNECTION_FAILED、error_type::PARSER_FAILED等 20 余种类型并作为错误事件的固定标签参与指标聚合保证component_errors_total的可观测维度受控。ComponentEventsDropped能丢弃事件的组件 MUST 发出所有可能丢弃事件的组件 MUST 依据可观测性规范中的 EventsDropped 事件发出该事件。要点如下属性count丢弃数量、intentional区分有意/无意丢弃如filtertransform 是故意丢弃remaptransform 因错误丢弃则属无意、reason简短友好的原因描述指标MUST 累加namespace_discarded_events_total指标标签只包含intentional及隐式继承的组件属性如component_type日志MUST 记录Events dropped消息intentionaltrue时以debug级别intentionalfalse时以error级别SHOULD 限流 10 秒边界事件在 Vector 内被创建之前不得发出例如源解码失败只发ComponentError而不发丢弃事件Vector 将重试的操作不得发出该事件重试成功则不丢数据。源码实现见 component_events_dropped.rs。它通过泛型常量INTENTIONAL区分两类丢弃并据此选择debug!或error!日志级别pub const INTENTIONAL: bool true; pub const UNINTENTIONAL: bool false; implconst INTENDED: bool InternalEventHandle for DroppedHandle_, INTENDED { fn emit(self, data: Self::Data) { let message Events dropped; if INTENDED { debug!(message, intentional INTENDED, count data.0, reason self.reason); } else { error!(message, intentional INTENDED, count data.0, reason self.reason); } self.discarded_events.increment(data.0 as u64); } }SinkNetworkBytesSentto be implementedSinks MUST 发出表示原始网络字节的出口流量。规范中标注该事件待实现to be implemented但其契约已经明确发出时机MUST 在原始网络字节出口后立即发出无论传输成功与否包括拉取型 Sink如prometheus_exporter在被拉取时应反映发给客户端的字节MUST 在字节处理之后加密、压缩、过滤等发出属性byte_size处理后的原始网络字节数SHOULD 尽可能贴近真实网络字节例如 HTTP 客户端无法给出总请求字节大小时用 payload/body 字节数指标MUST 累加component_sent_network_bytes_total日志MUST 以trace级别记录Network bytes sent.MUST NOT 限流。SourceNetworkBytesReceivedto be implementedSources MUST 发出表示原始网络字节的入口流量与上面镜像对称发出时机MUST 在原始网络字节入口后立即发出MUST 在字节处理之前解密、解压、过滤等发出包括发出请求摄取字节的拉取型源属性byte_size处理前的原始网络字节数例如 HTTP 客户端只暴露请求体时用原始请求体字节数指标MUST 累加component_received_network_bytes_total日志MUST 以trace级别记录Network bytes received.MUST NOT 限流。这两个待实现事件与ComponentEventsReceived/ComponentBytesReceived的弃用注释相互呼应——它们最终将取代后者成为网络字节计量的权威通道。指标命名补充源自 Instrumentation Specification由于本规范扩展自 instrumentation.md组件指标还必须遵守其中的命名模板事件名 MUST 遵循NamespaceNounVerb[Error]模板camelcase如ComponentEventsReceived指标名 MUST 遵循namespace_name_unit_[total]模板snakecase计数器必须以total结尾如component_received_events_total、component_sent_bytes_total指标 SHOULD 用途宽泛用标签区分特征如component_received_events_total{component_typesocket,modetcp}。Sink 运维要求Sink Operational Requirements本节聚焦 Sink 特有的三大运维契约健康检查、finalization 与确认acknowledgements。健康检查Health checks所有 Sink 组件SHOULD定义健康检查。这些检查在启动时以及vector validate命令执行时运行vector validate的校验流程定义在 validate.rs 与 config/validation.rs。健康检查 SHOULD尽可能贴近 Sink 的正常运行方式以给出Vector 配置正确的最佳信号。两条关键边界检查 SHOULDNOT 主动探测外部系统的健康状态但检查MAY因外部系统不健康而失败。例如aws_s3Sink 的健康检查在 AWS 故障时可能失败但检查本身不应去查询 AWS 的全局状态。更深入的实现指导可参考开发文档中的 Sink health checks 一节。Finalization最终化所有 Sink 组件MUST将事件的 finalization推迟到事件成功投递之后。finalization 的时机控制着事件何时从源端磁盘缓冲区中移除。具体做法是Sink 必须在事件投递前提取extract事件中的 finalizer并确保在投递完成前不丢弃这些 finalizer。从源码结构看这条要求通过批处理层落地src/sinks/util/batch.rs中的 FinalizersBatch 把普通Batch包装为携带 finalizer 的批次并被 sink.rs 中的StatefulBatchFinalizersBatchB使用从而保证 finalizer 跟随批次生命周期、只在投递完成后统一执行。Acknowledgements端到端确认在上述要求之上所有 Sink 组件 MUST 支持确认acknowledgements具体包含两点配置项必须提供名为acknowledgements的配置选项且类型符合AcknowledgementsConfigfinalizer 状态更新在事件投递完成后必须更新上述被推迟的 finalizer 的状态。规范特别指出所有使用新版StreamSink框架的 Sink 都会自动处理状态更新无需手工实现。StreamSink的定义与默认实现位于 sink.rs通过vector_lib::sink::StreamSink重导出vector-lib 同时重导出了AcknowledgementsConfig等配置类型。这意味着新 Sink 只要基于StreamSink构建就免费获得正确的确认语义。此外Sink 的单元测试SHOULD验证投递成功的批次与投递出错的批次其 finalizer 状态都被正确更新。结语一份开发新组件的行动清单综合全文为 Vector 开发一个新组件时可以按如下清单逐项核对命名source/sink 用协议或服务名词必要时带logs/metrics/traces后缀transform 用动词配置出站连接暴露endpoint/endpoints且显式配置覆盖自动拼接入站监听暴露listenprotocol:address可带默认协议可观测性按规范发出全部 MUST 事件接收/发送/错误/丢弃等批次发出时保证遥测状态等价并遵守事件与指标命名模板Sink 特有定义贴近真实运行的启动健康检查推迟事件 finalization 直到投递完成提供acknowledgements配置并通过StreamSink自动更新 finalizer 状态同时用单测覆盖正常投递与错误投递两条路径。按此清单开发的组件将天然满足 Vector 的统一行为契约在拓扑中与既有组件协同工作并为运维者提供高质量、可检索的遥测数据。参考文档与源码索引核心规范docs/specs/component.md扩展的基规范docs/specs/instrumentation.md、docs/specs/configuration.md事件实现lib/vector-common/src/internal_event/mod.rs、events_received.rs、bytes_received.rs、events_sent.rs、component_events_dropped.rs错误标签常量prelude.rsSink 框架sink.rs、batch.rs校验与开发文档validate.rs、docs/DEVELOPING.md用户体验期望docs/USER_EXPERIENCE_DESIGN.md【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考