Vector 的 OpenTelemetry Source 接入指南通过 gRPC/HTTP 接收 OTLP 遥测数据【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本文是 Vector 高可观测性数据管道中opentelemetrysource 组件的完整技术指南。该组件让 Vector 能够作为 OpenTelemetry Collector 协议OTLP的接收端通过 gRPC默认端口 4317与 HTTP默认端口 4318两种传输协议接收日志logs、指标metrics与链路追踪traces三类遥测信号并将其转换为 Vector 原生事件或保留 OTLP 原始格式转发给下游。读完本文你将掌握opentelemetrysource 的完整配置项、OTLP 解码行为use_otlp_decoding、事件字段映射细节以及从源码层面理解其 gRPC/HTTP 双监听器的实现原理与可观测性指标。组件概览定位与适用场景opentelemetrysource 是 Vector 面向可观测性数据接入的核心组件之一。它的元数据定义位于 website/cue/reference/components/sources/opentelemetry.cue其中明确标注了该组件的关键特性交付保证delivery: at_least_once至少一次交付配合 source 级与端到端确认acknowledgements机制实现可靠投递部署角色支持daemon守护进程每台机器部署一个与aggregator聚合器集中汇总数据两种形态开发状态beta阶段其中 metrics 与 traces 支持被标记为实验性experimental接口可能随版本演进调整接收接口面向 socket 的入站 TCP 监听TLS 为可选配置ssl: optionalgRPC 与 HTTP 两个监听器均可独立启用 TLS。从架构视角看该 source 扮演OTLP 摄取网关的角色应用通过 OpenTelemetry SDK/Collector 导出的数据可以直接落地到 Vector再由 Vector 的路由、转换与 sink 能力分发到存储、监控或另一个 OTEL Collector。默认端口遵循 OTLP 规范约定gRPC 为4317HTTP 为4318。组件使用统一标识符opentelemetry注册于 src/sources/opentelemetry/config.rs#[configurable_component(source(opentelemetry, ...))]源码模块结构见 src/sources/opentelemetry/mod.rs包含config.rs配置定义、grpc.rsgRPC 服务实现、http.rsHTTP 服务实现、reply.rs与status.rs响应与状态码封装以及tests.rs、integration_tests.rs测试文件。最小可用配置opentelemetrysource 的grpc与http两个配置块均为必填项required: true这意味着你需要至少显式配置一个监听地址。以下是最小配置示例同时启用 gRPC 与 HTTP 两个监听器sources: otel: type: opentelemetry grpc: address: 0.0.0.0:4317 # gRPC 监听地址必须包含端口 http: address: 0.0.0.0:4318 # HTTP 监听地址必须包含端口配置生成逻辑见 src/sources/opentelemetry/config.rs 的GenerateConfig实现它生成默认配置时 gRPC 使用0.0.0.0:4317、HTTP 使用0.0.0.0:4318与 OTLP 标准端口保持一致。使用 Vector CLI 可通过vector generate opentelemetry快速生成该组件的默认配置骨架。该 source 输出三个命名端口输出流下游组件需以component_id.port形式引用输出端口数据类型说明logsLog接收到的日志事件输出流tracesTrace接收到的 trace 事件输出流metricsMetric接收到的 metric 事件输出流启用 OTLP 解码时变为 Log 类型sinks: my_sink: inputs: - otel.logs - otel.traces - otel.metrics type: ...完整配置项详解该组件的完整配置结构由 website/cue/reference/components/sources/generated/opentelemetry.cue 生成全部配置项整理如下grpcgRPC 服务配置必填参数类型必填默认值说明addressstring是—监听 socket 地址必须包含端口示例0.0.0.0:4317、localhost:4317tlsobject否无入站连接 TLS 配置TlsEnableableConfigkeepaliveobject否见下gRPC server keepalive 参数grpc.keepalive的底层定义位于 src/sources/util/grpc/mod.rs 的GrpcKeepaliveConfig参数类型说明max_connection_age_secsinteger秒连接在被服务器主动关闭前允许存在的最大时长不设置则不按年龄关闭连接示例值300max_connection_age_grace_secsinteger秒附加在max_connection_age_secs之上的宽限期仅在设置了max_connection_age_secs时生效示例值30gRPC keepalive 的解析与校验可参考 src/sources/opentelemetry/tests.rs 中的config_grpc_keepalive测试其验证了 TOML 配置中max_connection_age_secs 300、max_connection_age_grace_secs 30可被正确解析。httpHTTP 服务配置必填参数类型必填默认值说明addressstring是—监听 socket 地址必须包含端口示例0.0.0.0:4318、localhost:4318headersarray of string否[]需要放入事件的 HTTP 请求头列表支持通配符*tlsobject否无入站连接 TLS 配置keepaliveobject否见下HTTP server keepalive 参数http.headers支持通配匹配指定*表示将所有请求头纳入事件支持模式化匹配如X-*、User-Agent、X-My-Custom-Header。需要留意的是在 legacy 日志命名空间模式下若事件中已存在同名字段请求头不会被覆盖写入而 metrics 与 traces 事件的请求头始终被添加到事件元数据中。该参数在源码中经由 src/sources/opentelemetry/http.rs 的build_param_matcher与remove_duplicates处理后构建匹配器。http.keepalive对应vector::http::KeepaliveConfig包含tcp_keepaliveTCP 层 keepalive、max_connection_age_secs连接最大存活时长与max_connection_age_jitter_factor抖动因子默认0.1用于错峰关闭连接避免惊群。use_otlp_decodingOTLP 解码行为可选该参数控制三类信号logs/metrics/traces的 OTLP 解码行为定义于 src/sources/opentelemetry/config.rs 的OtlpDecodingConfig当某个信号启用 OTLP 解码时保留原始 OTLP 格式数据可直接passthrough转发给下游 OTEL Collector无需remap转换未启用时信号被转换为Vector 原生事件格式默认行为。支持两种写法# 简单布尔形式统一控制所有信号 use_otlp_decoding: true # 所有信号保留 OTLP 格式 # use_otlp_decoding: false # 所有信号使用 Vector 原生格式默认# 按信号分别配置 use_otlp_decoding: logs: false # 转换为 Vector 原生格式 metrics: false # 转换为 Vector 原生格式 traces: true # 保留 OTLP 格式三个子选项的默认值均为false子选项默认值说明logsfalsetrue时日志保留 OTLP 格式metricsfalsetrue时指标保留 OTLP 格式但以日志事件形式处理tracesfalsetrue时链路保留 OTLP 格式该配置在源码中通过bool_or_struct反序列化器支持布尔或结构体两种形态Frombool实现src/sources/opentelemetry/config.rs保证了向后兼容性true为所有信号启用 OTLP 解码false全部使用 Vector 原生格式。get_signal_deserializer方法同文件 L244-L263会按信号类型查询对应开关启用时构造OtlpDeserializer。重要限制当为 metrics 启用 OTLP 解码时OTLP 格式的指标会被解析为日志事件保留 OTLP 结构该输出与 Vector 的 metric 转换器如aggregate不兼容事件可直接透传给下游 OTEL Collector适合做 OTLP 中继场景。配置中存在混合模式部分信号启用、部分不启用时source 启动会打印信息日志提示各类信号的解码方式src/sources/opentelemetry/config.rs。acknowledgements已废弃source 级别的acknowledgements参数已废弃启用或禁用它对确认行为不再有任何影响确认行为应通过全局配置global acknowledgements或 sink 级别设置。source 的can_acknowledge()返回true表明其具备端到端确认能力。log_namespace内部隐藏选项用于覆盖全局日志命名空间设置Vector 命名空间或 legacy 命名空间。双监听器架构gRPC 与 HTTP 的实现原理opentelemetrysource 的核心是同时运行 gRPC 与 HTTP 两个异步服务器二者通过futures::join组合任一服务器失败都会终止整个 source见 src/sources/opentelemetry/config.rs 的build_with_tls_reloaders。两个监听器共享同一事件管道SourceSender与EventsReceived计数。gRPC 服务端tonic 实现gRPC 侧基于tonic框架实现三个 OTLP Collector 服务src/sources/opentelemetry/grpc.rs服务gRPC 方法对应输出LogsServiceServerExportLogsServiceRequest→ExportLogsServiceResponselogsMetricsServiceServerExportMetricsServiceRequest→ExportMetricsServiceResponsemetricsTraceServiceServerExportTraceServiceRequest→ExportTraceServiceResponsetraces三个服务注册到tonic::transport::server::RoutesBuilder后由run_grpc_server_with_routes启动。每个服务都通过.max_decoding_message_size(max_decompressed_size_bytes())设置了消息解码上限与全局解压缩大小上限对齐见 src/sources/util/decompression.rs 的DEFAULT_MAX_DECOMPRESSED_SIZE_BYTES防止超大请求造成内存压力。gzip、zstd 等压缩协商由sources::util::grpc中的DecompressionAndMetricsLayer统一处理因此服务实现本身不重复调用.accept_compressed(..)。gRPC 服务在处理事件时handle_events若启用了 OTLP 解码则把 protobuf 请求重新编码为字节流交给OtlpDeserializer解析输出事件为保留 OTLP 结构的日志否则直接调用into_event_iter转换为 Vector 原生事件。事件经send_batch_named送入指定端口管道并通过BatchNotifier等待下游确认Delivered返回成功响应Errored映射为 gRPCinternal状态Rejected映射为data_loss状态src/sources/opentelemetry/grpc.rs。HTTP 服务端warp 实现HTTP 侧基于warp构建路由过滤器src/sources/opentelemetry/http.rs。build_warp_filter将日志、指标、trace 三类过滤器合并每条路由约束如下POST /v1/logs Content-Type: application/x-protobuf POST /v1/traces POST /v1/metrics路由构建逻辑见build_ingest_filtersrc/sources/opentelemetry/http.rs它要求HTTP 方法为POST路径为/v1/signallogs / traces / metrics与 OTLP/HTTP 规范一致Content-Type必须精确匹配忽略大小写application/x-protobuf支持Content-Encoding声明的压缩体decompress_body解压并受capped_body的 body 大小上限约束。请求体经 prost 反序列化为对应的Export*ServiceRequest后与 gRPC 路径一样转换为事件流。响应方面成功时返回 protobuf 编码的空Export*ServiceResponse解码失败时返回Statuscode2 UNKNOWN与 400 状态码下游投递失败时返回 500。HTTP 服务器还支持 keepalive 连接年龄限制MaxConnectionAgeLayer与请求追踪层build_http_trace_layer。事件转换从 OTLP 到 Vector 原生事件日志事件字段映射当use_otlp_decoding.logs为false时OTLPLogRecord被转换为 Vector 日志事件字段结构定义于 website/cue/reference/components/sources/opentelemetry.cueschema 声明见 src/sources/opentelemetry/config.rs 的outputs方法字段类型必填说明attributesobject否描述具体事件发生的属性如http.status.code、http.url、自定义应用标签resourcesobject否描述资源的属性集如service.name、service.version、k8s.pod.uid、container.namescope.namestring否插桩作用域名称通常为 logger 名称示例some.module.namescope.versionstring否插桩作用域版本示例1.2.3scope.attributesobject否属于插桩作用域的属性集scope.dropped_attributes_countuint否插桩作用域被丢弃的属性数量非零时存在messagestring否日志记录主体示例20200415T072306-0700 INFO I like donutstrace_idstring否W3C Trace Context 定义的请求 trace id示例66346462623365646437363566363230span_idstring否日志所属处理 span 的 id示例43222c2d51a7abe3severity_numberuint否严重级别数值数值越小越不严重debug越大越严重error/critical示例 3、9、17、24severity_textstring否严重级别文本即日志级别示例TRACE3、INFO、ERROR、FATAL4flagsuint否W3C Trace Context 规范定义的 trace flagtimestamptimestamp是事件发生时间UTC由 protobuftime_unix_nano转换未设置或为 0 时取observed_timestampobserved_timestamptimestamp是采集系统观察到事件的时间UTC由observed_time_unix_nano转换未设置或为 0 时取当前时间dropped_attributes_countuint是因采集限制而丢弃的属性计数上述映射行为在 src/sources/opentelemetry/tests.rs 的receive_grpc_logs_vector_namespace测试中被逐字段验证包括opentelemetry.resources、opentelemetry.attributes、opentelemetry.scope.name/version/attributes/dropped_attributes_count、opentelemetry.trace_id/span_id/severity_text/severity_number/flags/observed_timestamp/timestamp/dropped_attributes_count等元数据字段以及source_type: opentelemetry与ingest_timestamp注入。legacy 命名空间下的扁平化字段布局则由receive_grpc_logs_legacy_namespace测试验证同文件 L335-L397。指标类型映射当use_otlp_decoding.metrics为false时OTLP 指标被转换为 Vector 原生指标。由于内部数据模型存在结构性差异指标支持属于实验性功能映射规则如下见 website/cue/reference/components/sources/opentelemetry.cue聚合临时性Aggregation Temporality决定 MetricKind若某指标类型支持临时性Delta对应 Vector 的Incremental增量否则为Absolute绝对值Gauge→ VectorGaugeSum→is_monotonic为true时映射为 VectorCounter为false时映射为 VectorGaugeHistogram→ VectorAggregatedHistogramExponential Histogram→ 同样映射为 VectorAggregatedHistogrambucket 边界从指数刻度scale重建Summary→ Vector 聚合Summary。这些映射在测试中均有对应用例例如receive_sum_metricis_monotonic: true Cumulative →CounterAbsolute、receive_sum_non_monotonic_metric→Gauge、receive_gauge_metric、receive_histogram_metric与receive_histogram_delta_metricCumulative→Absolute / Delta→Incremental、receive_exponential_histogram_metric等src/sources/opentelemetry/tests.rs 及后续。指标标签tags由资源属性、作用域属性与数据点属性共同构成测试中可见resource.service.name、scope.name、scope.version等标签前缀。链路追踪tracesVector 内部目前没有强类型的 trace 结构trace 事件以类似日志的 key/value map 形式存储因此 trace 支持属于实验性功能未来可能演进为结构化格式。当use_otlp_decoding.traces为false时OTLPSpan经into_event_iter转换为 Vector trace 事件从traces端口输出。启用 OTLP 解码时trace 保留 OTLP 结构事件体包含resourceSpans/scopeSpans/spans层级JSON 字段名定义见 lib/opentelemetry-proto/src/proto.rs。OTLP 批量事件计数当启用 OTLP 解码时单个事件可能包含整个 OTLP 批次batch为了让EventsReceived计数与其他 source 保持口径一致src/sources/opentelemetry/mod.rs 的count_otlp_items会深入事件结构统计scopeLogs.logRecords、scopeMetrics.metrics、scopeSpans.spans中的实际条数。实战场景一OTLP 日志直通Passthrough到 OTEL Collector使用use_otlp_decoding最典型的场景是将 OTLP 格式日志原样转发给下游 OTEL Collector全程无需remap转换。CUE 文档website/cue/reference/components/sources/opentelemetry.cue给出的推荐配置如下sources: otel: type: opentelemetry grpc: address: 0.0.0.0:4317 http: address: 0.0.0.0:4318 use_otlp_decoding: logs: true sinks: otel_sink: inputs: - otel.logs type: opentelemetry protocol: type: http uri: http://localhost:5318/v1/logs encoding: codec: otlp同一模式同样适用于 metrics 与 traces。但需再次强调OTLP 格式的指标无法转换为 Vector 指标格式因此启用use_otlp_decoding.metrics后OTLP 指标会以保留 OTLP 格式的日志事件形式呈现——这会禁止使用aggregate等 metric 转换器但能够便捷地直通到 OTEL Collector。实战场景二在 Kubernetes 中以 DaemonSet/Aggregator 形态部署由于opentelemetrysource 支持daemon与aggregator两种部署角色推荐部署形态为每个节点运行一个 Vector Agentdaemon 角色作为 OTLP 入口或部署独立的 Vector Aggregator 集中接收来自各节点/应用的 OTLP 数据。仓库中的 Helm chart 清单distribution/kubernetes/vector-agent 与 distribution/kubernetes/vector-aggregator提供了这两类部署的现成 YAML 清单参考。对于集群内 OTLP 上报SDK 侧通常将 OTLP endpoint 指向聚合器的 Service 地址与 4317/4318 端口。TLS 与安全配置Vector 使用 OpenSSL 处理 TLS 协议其成熟度是选型原因。可分别通过grpc.tls.*与http.tls.*选项启用并调节 TLS 行为或通过 OpenSSL 配置文件进行更细粒度控制。OpenSSL 配置文件默认路径为/usr/local/ssl/openssl.cnf也可通过OPENSSL_CONF环境变量指定。TlsEnableableConfig支持enabled、crt证书、key私钥等标准字段同时两个监听器还支持运行时热替换 TLS 接受器TlsAcceptorReloader见 src/sources/opentelemetry/config.rs 的build_with_tls_reloaders。sources: otel: type: opentelemetry grpc: address: 0.0.0.0:4317 tls: enabled: true crt: /etc/vector/tls/server.crt key: /etc/vector/tls/server.key http: address: 0.0.0.0:4318 tls: enabled: true crt: /etc/vector/tls/server.crt key: /etc/vector/tls/server.key可观测性指标opentelemetrysource 自带内部遥测指标见 website/cue/reference/components/sources/opentelemetry.cue可用于监控其健康状态指标说明grpc_server_handler_duration_secondsgRPC 服务处理器耗时分布grpc_server_messages_received_totalgRPC 接收消息总数grpc_server_messages_sent_totalgRPC 发送消息总数http_server_handler_duration_secondsHTTP 服务处理器耗时分布http_server_requests_received_totalHTTP 接收请求总数http_server_responses_sent_totalHTTP 发送响应总数此外内部事件EventsReceived含事件数与字节数与BytesReceived协议为 http/https在 src/sources/opentelemetry/http.rs 与 gRPC 的handle_events中被持续记录可用于吞吐量监控。请求解码失败会触发HttpBadRequest内部事件。源码速览与测试验证若希望深入理解该组件的实现建议按以下路径阅读配置与装配src/sources/opentelemetry/config.rs — 配置结构体、build_with_tls_reloaders双服务器装配、outputsschema 声明gRPC 服务src/sources/opentelemetry/grpc.rs — 三个 OTLP Collector 服务的实现与确认处理HTTP 服务src/sources/opentelemetry/http.rs — warp 路由、压缩解压、事件解码与错误响应元数据与生成文档website/cue/reference/components/sources/opentelemetry.cue 与 website/cue/reference/components/sources/generated/opentelemetry.cue单元测试src/sources/opentelemetry/tests.rs — 覆盖 gRPC/HTTP 双协议下 logs、各类 metricsSum/Gauge/Histogram/Exponential Histogram/Summary与 traces 的完整转换断言集成测试src/sources/opentelemetry/integration_tests.rs — 需要opentelemetry-integration-testsfeature 的真实环境验证。总结opentelemetrysource 是 Vector 与 OpenTelemetry 生态对接的关键入口它以符合 OTLP 规范的 gRPC4317与 HTTP4318双协议接收 logs、metrics、traces 三类信号既可将 OTLP 数据转换为 Vector 原生事件以接入 Vector 完整的转换与路由能力也可通过use_otlp_decoding保留原始 OTLP 格式实现到下游 OTEL Collector 的零转换直通。对于正在构建统一可观测性管道、希望以 Vector 作为 OTLP 摄取网关的团队理解本组件的配置语义、字段映射与双监听器实现是正确落地这一架构的前提。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考