企业官网建设流程全解析

• 后端
• 可观测性
• 链路追踪

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 创建的处理器，无论处理哪种信号，都会共享同一套内部遥测指标命名体系，这为下游监控与故障定位提供了统一的查询维度。

二、三项内部遥测指标总览

原文档以表格形式给出了全部三项指标，这里完整继承并补充来源文件引用：

从 internal/metadata/generated_telemetry.go 可以看到生成代码将三者分别实现为：

• ProcessorIncomingItems：metric.Int64Counter，Counter 语义，对应"单调递增"；
• ProcessorInternalDuration：metric.Float64Histogram，直方图语义，单位s；
• ProcessorOutgoingItems：metric.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 的recordInternalDuration：

duration := 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.go（TelemetryBuilder实现），两者头部都带有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，值为"processor"；otel.signal的取值来自 Collector 的 pipeline 信号枚举（如traces、metrics、logs）。这意味着在 Prometheus 等监控系统中，同一组指标可以按processor与otel.signal两个维度做标签级筛选与聚合，例如单独查看"名为batch的处理器在 traces 信号下的处理耗时"。

5.2 信号包装器的完整处理流程（以 traces 为例）

traces.go 中的NewTraces展示了内部遥测与处理逻辑的完整交织：

1. 从 context 中取出当前 span，写入"Start processing."事件（附加processor=<ID>属性）；
2. startTime := time.Now()开始计时，同时统计spansIn := td.SpanCount()；
3. 调用用户提供的ProcessTracesFunc得到处理后的td与错误；
4. 无论成败都调用recordInternalDuration记录耗时，并写入"End processing."事件；
5. 出错时recordInOut(ctx, spansIn, 0)；若错误为ErrSkipProcessingData则静默返回；
6. 成功时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 处理器性能观测的底层语言。

• 后端
• 可观测性
• 链路追踪