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

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

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

导读

本文基于 Vector 开源仓库的 Component Specification（docs/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暴露以下两种形式之一：

选项	类型	语义
endpoint	string	单个端点
endpoints	string[]	多个端点组成的数组

此外存在一条强约束：如果组件通过多个选项自动拼接出端点，那么endpoint(s)选项 MUST 覆盖（override）该自动拼接过程。这意味着显式配置的端点拥有最高优先级，是组件的"最终决定权"。

从源码结构看，仓库中的网络型 Sink（如 http、aws_s3、elasticsearch 等）普遍遵循这一模式：用endpoint或endpoints作为服务地址的入口，同时保留region、bucket等辅助选项用于在未显式指定端点时自动推导完整地址。

listen选项

当组件监听入站连接时，SHOULD暴露listen选项，其值为<protocol>:<address>形式的字符串。协议可选值如下：

协议值	地址格式	说明
unix+stream	文件路径	Unix 域套接字，流式
unix+datagram	文件路径	Unix 域套接字，数据报
unix	文件路径	等价于unix+stream
tcp	<host>:<port>	TCP 监听
udp	<host>:<port>	UDP 监听

组件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落地后被弃用。

ComponentBytesReceived（Sources MUST 发出）

表示字节的接收（发生在字节被解析成事件之前）。

• 发出时机：MUST 在从上游接收、解压并过滤字节后、创建 Vector 事件之前立即发出；
• 属性：
  • byte_size：UDP/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); } );

ComponentBytesSent（Sinks MUST 发出）

表示字节的下游传输。

• 发出时机：MUST 在成功向下游目标发送字节后立即发出；报告的字节数必须在压缩之前；
• 例外：只暴露数据、发送后不删除数据的 Sink（如prometheus_exporter）SHOULD NOT发出该指标；
• 属性：byte_size（各协议定义与接收侧对称，但压缩前统计）、protocol、endpoint（HTTP 下必须是主机与路径，不含查询字符串）、file（如相关，文件的绝对路径）；
• 指标：MUST 累加component_sent_bytes_total计数器；
• 日志：MUST 以trace级别记录Bytes sent.，MUST NOT 限流。

ComponentEventsSent（所有组件 MUST 发出）

表示向下一个下游组件发送 Vector 事件。

• 发出时机：MUST 在事件成功传输后立即发出；传输失败MUST NOT发出；
• 例外：拉取型（pull-based）Sink 不发送事件，MUST NOT发出该事件（如prometheus_exporter）；
• 属性：count、byte_size（预估 JSON 字节）、output（OPTIONAL，多输出组件的输出名；发送到默认输出时该值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消息；intentional=true时以debug级别，intentional=false时以error级别，SHOULD 限流 10 秒；
• 边界：事件在 Vector 内被创建之前不得发出（例如源解码失败只发ComponentError而不发丢弃事件）；Vector 将重试的操作不得发出该事件（重试成功则不丢数据）。

源码实现见 component_events_dropped.rs。它通过泛型常量INTENTIONAL区分两类丢弃，并据此选择debug!或error!日志级别：

pub const INTENTIONAL: bool = true; pub const UNINTENTIONAL: bool = false; impl<const 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); } }

SinkNetworkBytesSent（to be implemented，Sinks 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 限流。

SourceNetworkBytesReceived（to be implemented，Sources 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 遵循<Namespace><Noun><Verb>[Error]模板（camelcase），如ComponentEventsReceived；
• 指标名 MUST 遵循<namespace>_<name>_<unit>_[total]模板（snakecase），计数器必须以total结尾（如component_received_events_total、component_sent_bytes_total）；
• 指标 SHOULD 用途宽泛，用标签区分特征（如component_received_events_total{component_type="socket",mode="tcp"}）。

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 中的StatefulBatch<FinalizersBatch<B>>使用，从而保证 finalizer 跟随批次生命周期、只在投递完成后统一执行。

Acknowledgements（端到端确认）

在上述要求之上，所有 Sink 组件 MUST 支持确认（acknowledgements），具体包含两点：

1. 配置项：必须提供名为acknowledgements的配置选项，且类型符合AcknowledgementsConfig；
2. finalizer 状态更新：在事件投递完成后，必须更新上述被推迟的 finalizer 的状态。

规范特别指出：所有使用新版StreamSink框架的 Sink 都会自动处理状态更新，无需手工实现。StreamSink的定义与默认实现位于 sink.rs（通过vector_lib::sink::StreamSink重导出，vector-lib 同时重导出了AcknowledgementsConfig等配置类型）。这意味着新 Sink 只要基于StreamSink构建，就免费获得正确的确认语义。

此外，Sink 的单元测试SHOULD验证：投递成功的批次与投递出错的批次，其 finalizer 状态都被正确更新。

结语：一份"开发新组件"的行动清单

综合全文，为 Vector 开发一个新组件时，可以按如下清单逐项核对：

1. 命名：source/sink 用协议或服务名词（必要时带logs/metrics/traces后缀）；transform 用动词；
2. 配置：出站连接暴露endpoint/endpoints（且显式配置覆盖自动拼接）；入站监听暴露listen（<protocol>:<address>，可带默认协议）；
3. 可观测性：按规范发出全部 MUST 事件（接收/发送/错误/丢弃等），批次发出时保证遥测状态等价，并遵守事件与指标命名模板；
4. 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.rs
• Sink 框架：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