后端可观测性链路追踪【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址https://gitcode.com/GitHub_Trending/tempo1/tempo点击查看免费下载processorhelper 是 OpenTelemetry Collector 为信号处理器Processor提供的通用包装框架开发者只需实现一个针对 traces、metrics 或 logs 的处理函数由它统一负责上下文传播、生命周期管理与遥测记录。在 Grafana Tempo 的 vendor 依赖树中Collector 以 v0.153.0 版本引入见 vendor/modules.txt本文以其自动生成的遥测文档 documentation.md 为主体结合同包源码逐项剖析otelcol_processor_incoming_items、otelcol_processor_internal_duration、otelcol_processor_outgoing_items三项内部遥测指标的定义、记录时机、属性标签与观测方式。读完本文你将理解 Collector 处理器遥测的完整契约并能据此监控任何基于 processorhelper 构建的处理组件。一、processorhelper 与 Internal Telemetry文档的定位与来源documentation.md开头即标注Code generated by mdatagen. DO NOT EDIT.说明它不是手写文档而是由 OpenTelemetry 官方代码生成器 mdatagen 从组件的metadata.yaml自动产出的「内部遥测Internal Telemetry」说明书。这意味着文档中每一行内容都与 metadata.yaml 中的声明一一对应metadata.yaml才是这三项指标的单一事实来源Single Source of Truth。processorhelper 之所以需要统一的遥测是因为它在 processor.go 中为各信号提供了工厂函数NewTraces、NewMetrics、NewLogs以及扩展包xprocessorhelper中的NewProfiles这些工厂在包装用户处理函数的同时天然具备插入观测逻辑的钩子位置。从源码结构可以推断所有由 processorhelper 创建的处理器无论处理哪种信号都会共享同一套内部遥测指标命名体系这为下游监控与故障定位提供了统一的查询维度。二、三项内部遥测指标总览原文档以表格形式给出了全部三项指标这里完整继承并补充来源文件引用指标名说明Unit单位指标类型值类型单调递增稳定性otelcol_processor_incoming_items传递给处理器的条目数量{item}SumInttrueAlphaotelcol_processor_internal_duration处理器处理一批遥测数据所耗费的时长sHistogramDouble—直方图Alphaotelcol_processor_outgoing_items处理器发出的条目数量{item}SumInttrueAlpha从 internal/metadata/generated_telemetry.go 可以看到生成代码将三者分别实现为ProcessorIncomingItemsmetric.Int64CounterCounter 语义对应单调递增ProcessorInternalDurationmetric.Float64Histogram直方图语义单位sProcessorOutgoingItemsmetric.Int64Counter。指标统一由TelemetryBuilder持有其 Meter 的完整标识为go.opentelemetry.io/collector/processor/processorhelper。所有指标的稳定性等级均为Alpha即命名与语义仍可能在后续版本中调整接入监控告警时需要注意这一前提。三、指标逐一解析语义与源码记录位置3.1 otelcol_processor_incoming_items进入处理器的条目数该指标统计有多少条目被交给当前处理器单位{item}。注意条目的具体口径随信号类型不同而不同在 traces.go 中对应td.SpanCount()Span 数在 metrics.go 中对应md.DataPointCount()数据点个数在 logs.go 中对应ld.LogRecordCount()日志记录条数。它在 obsreport.go 的recordInOut方法中通过ProcessorIncomingItems.Add(ctx, int64(incoming), otelAttrs)记录。从三个信号包装器的流程看该指标无论处理成功还是失败都会被记录处理函数返回错误时incoming 依然累加而 outgoing 记为 0从而形成只进不出的缺口便于统计处理失败导致的条目丢失。3.2 otelcol_processor_internal_duration单批处理耗时该指标以直方图形式记录处理一批遥测数据所耗费的时长单位s是评估处理器性能瓶颈的核心指标。其值类型为 Double由 generated_telemetry.go 中的Float64Histogram承载。记录逻辑同样位于 obsreport.go 的recordInternalDurationduration : time.Since(startTime) or.telemetryBuilder.ProcessorInternalDuration.Record(ctx, duration.Seconds(), or.otelAttrs)结合 traces.go 等包装器可还原完整时序处理开始前调用time.Now()取起始时间处理函数返回后无论成败立即计算time.Since(startTime)并记录随后才向 span 写入 End processing. 事件。因此该指标覆盖的是处理函数本身的开销不包含下游消费的时间。实际观测时可通过直方图分位数如 p50/p99判断是否存在慢处理器实例。3.3 otelcol_processor_outgoing_items处理成功后下发的条目数该指标统计处理器发出转发给下一个组件的条目数量单位{item}同样随信号不同而对应 Span 数、数据点或日志记录数。需要特别强调其记录条件在三个包装器中只有当处理函数未返回错误时才读取pointsOut/spansOut/recordsOut并累加该指标一旦出错recordInOut(ctx, pointsIn, 0)会把 outgoing 记为 0。此外包装器对processorhelper.ErrSkipProcessingData定义于 processor.go做了特殊处理当处理函数返回这个哨兵错误时表示数据被有意丢弃例如与管道无关的数据包装器会静默返回 nil 而不向管道上游传播错误。因此incoming - outgoing的差值可以粗略反映被处理器过滤、丢弃或处理失败的数据量是判断处理器数据损耗的重要依据。四、metadata.yaml指标定义的单一事实来源与生成工作流machine-readable 的 metadata.yaml 完整声明了上述三项指标是理解整条生成链路的钥匙type: processorhelper github_project: open-telemetry/opentelemetry-collector status: class: pkg stability: beta: [traces, metrics, logs] telemetry: metrics: processor_incoming_items: enabled: true stability: alpha description: Number of items passed to the processor. unit: {item} sum: value_type: int monotonic: true processor_internal_duration: enabled: true stability: alpha description: Duration of time taken to process a batch of telemetry data through the processor. unit: s histogram: async: false value_type: double processor_outgoing_items: enabled: true stability: alpha description: Number of items emitted from the processor. unit: {item} sum: value_type: int monotonic: true几点值得注意的细节指标 YAML 中的processor_incoming_items与最终指标名otelcol_processor_incoming_items存在otelcol_前缀差异这正是 mdatagen 生成时统一添加的 Collector 命名空间前缀sum.monotonic: true决定了最终落地为Int64Counter而非 UpDownCounter意味着该指标只增不减histogram.async: false表示该直方图为同步Sync记录由组件在调用路径中主动Record而非依赖异步回调采集该包整体稳定性为beta面向 traces/metrics/logs 信号而三项遥测指标自身的稳定性仅为alpha说明功能可用但指标契约仍可变化。生成工作流的产出物即documentation.md本文所依据的文档与 internal/metadata/generated_telemetry.goTelemetryBuilder实现两者头部都带有DO NOT EDIT注释。因此任何对指标语义的修改都应改在metadata.yaml中进行并重新运行 mdatagen而不是直接改动生成文件。五、源码级观测链路obsreport 与三个信号的包装器5.1 观测报告器的属性标签obsreport.go 中的newObsReport为每条指标记录附加了两个固定属性用于区分不同处理器实例与信号类型attribute.String(internal.ProcessorKey, set.ID.String()) // key processor attribute.String(signalKey, signal.String()) // key otel.signal其中internal.ProcessorKey常量定义于 vendor/go.opentelemetry.io/collector/processor/internal/obsmetrics.go值为processorotel.signal的取值来自 Collector 的 pipeline 信号枚举如traces、metrics、logs。这意味着在 Prometheus 等监控系统中同一组指标可以按processor与otel.signal两个维度做标签级筛选与聚合例如单独查看名为batch的处理器在 traces 信号下的处理耗时。5.2 信号包装器的完整处理流程以 traces 为例traces.go 中的NewTraces展示了内部遥测与处理逻辑的完整交织从 context 中取出当前 span写入Start processing.事件附加processorID属性startTime : time.Now()开始计时同时统计spansIn : td.SpanCount()调用用户提供的ProcessTracesFunc得到处理后的td与错误无论成败都调用recordInternalDuration记录耗时并写入End processing.事件出错时recordInOut(ctx, spansIn, 0)若错误为ErrSkipProcessingData则静默返回成功时recordInOut(ctx, spansIn, spansOut)并调用nextConsumer.ConsumeTraces传给下游。metrics.go 与 logs.go 的NewMetrics、NewLogs结构完全一致仅将计数口径替换为DataPointCount/LogRecordCount。而 processor.go 提供的WithStart、WithShutdown、WithCapabilities三个 Option 则用于定制生命周期行为其中默认能力为MutatesData: true处理器默认允许修改数据。5.3 一个值得注意的差异profiles 信号不记录这三项指标扩展包 xprocessorhelper/profiles.go 提供了面向 profiles性能剖析信号的NewProfiles。从源码看它的实现不创建 obsReport也不记录上述三项指标仅做错误处理与ErrSkipProcessingData的静默跳过。因此在使用场景上可以明确本文三项遥测指标只覆盖 traces、metrics、logs 三种主信号profiles 处理器的遥测契约不在其中。六、稳定性说明与观测实践6.1 Alpha 稳定性的含义三项指标均标记为 Alpha依据 OpenTelemetry Collector 的稳定性约定这表示指标名称、单位、语义可能在后续版本中变更或移除面向生产环境使用时建议先在小流量上验证指标语义与告警阈值避免升级 Collector 版本后出现断点。6.2 如何观测这些指标由处理器组件在运行期通过 OTel SDK 的 Meter标识为go.opentelemetry.io/collector/processor/processorhelper输出Collector 自身暴露的/metrics端点或配置的 Prometheus exporter 即可抓取。典型查询维度包括sum(rate(otelcol_processor_incoming_items{processor名称}[5m]))处理器入口吞吐otelcol_processor_internal_duration_bucket或直方图分位数处理延迟(otelcol_processor_incoming_items - otelcol_processor_outgoing_items)单位时间内的数据损耗/丢弃量。配合processor与otel.signal两个标签可在同一面板中横向对比不同信号、不同处理器实例的负载差异。七、该文档在 Tempo 仓库中的角色Grafana Tempo 自身并不直接调用processorhelper在 modules 与 pkg 目录中检索不到对processorhelper.的引用它作为 OpenTelemetry Collector v0.153.0 的传递依赖被打入 vendor 目录证据见 vendor/modules.txt 中go.opentelemetry.io/collector/processor/processorhelper v0.153.0一行。从依赖结构看这套内部遥测指标属于 Collector 生态处理器的通用契约Tempo 引入 Collector 相关库构建接收、处理链路时凡基于 processorhelper 构建的处理器组件都会自动产出这三项指标运维人员可据此获得与官方 Collector 完全一致的处理器可观测性口径。需要强调的是本文所有指标语义均以 Tempo 仓库内 vendored 的 documentation.md 与 metadata.yaml 为准若未来升级 vendor 版本请以新版本生成的文档为最终依据。结语otelcol_processor_incoming_items、otelcol_processor_internal_duration、otelcol_processor_outgoing_items构成了 processorhelper 对外的可观测性三件套入口吞吐、处理延迟、出口流量。借助metadata.yaml→ mdatagen →generated_telemetry.go的生成链路与obsreport.go中统一的属性标签任何基于该框架的处理器都能以一致的指标口径融入现有监控体系。理解这份自动生成的遥测文档也就掌握了 Collector 处理器性能观测的底层语言。赞分享后端可观测性链路追踪【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址https://gitcode.com/GitHub_Trending/tempo1/tempo点击查看免费下载相关推荐Grafana Tempo 内嵌 OpenTelemetry Collector Service内部遥测指标与 Feature Gates 深度解析Grafana Tempo 内嵌 OpenTelemetry Collector Service内部遥测指标与 Feature Gates 深度解析 Graf后端可观测性链路追踪OpenTelemetry Collector processorhelper 内部遥测指标详解incoming/duration/outgoing 三件套的采集机制与观测实践OpenTelemetry Collector processorhelper 内部遥测指标详解incoming/duration/outgoing 三件套的可观测性后端运维观测Grafana Tempo 中的 receiverhelper 内部遥测指标与 Feature Gate 深度解析Grafana Tempo 中的 receiverhelper 内部遥测指标与 Feature Gate 深度解析 本文以 Grafana Tempo 仓库 v后端可观测性链路追踪创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考