Grafana Tempo 内嵌 OTel Collector 组件exporterhelper 内部遥测指标与 Feature Gate 完全指南【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本文以 Grafana Tempo 仓库内 vendored 的go.opentelemetry.io/collector/exporter/exporterhelper模块为对象系统梳理其内部遥测Internal Telemetry的全部 17 个指标与 1 个 Feature Gate。Tempo 以库的形式内嵌 OpenTelemetry Collector 生态组件见 go.mod 中exporter/exporterhelper v0.153.0、exporter/otlpexporter v0.153.0直接依赖以及 modules/distributor/receiver/shim.go 中通过otelcol构建 Collector 配置启动 receiver 的实现因此 exporterhelper 的遥测语义直接适用于 Tempo 及任何集成 OTel Collector exporter 的系统。读完本文你将掌握每个指标的含义、数据类型、稳定级别、采集实现原理以及发送队列、重试、超时等配置与指标之间的联动关系。exporterhelper 是什么一类被所有 exporter 复用的基础设施exporterhelper是 OpenTelemetry Collector 中为所有 exporter 提供通用能力的辅助包。正如其在 README.md 中所述该包为 exporter 提供可复用的实现当前包括**排队queuing、批处理batching、超时timeouts与重试retries**四类能力。在 Grafana Tempo 中Collector 生态并非以独立进程方式运行而是被直接以 Go 库的形式编译进二进制。例如 modules/distributor/receiver/shim.go 在创建 OTLP 等 receiver 时构造了一份包含receivers、exporters此处使用nopexporter 以避免报错与service.pipelines的 Collector 配置再通过otelcol.NewConfigProvider解析并启动。这意味着Tempo 的 trace 接收端就是 Collector 生态的 receiver/exporter 组件任何被启用的 exporter如 OTLP exporter在发送数据时其排队、批处理、超时、重试行为都由exporterhelper统一驱动与之配套的内部遥测指标全部由exporterhelper的观测层obsReportSender发出命名统一以otelcol_exporter_为前缀。内部遥测指标全景17 个指标的分类视图documentation.md定义的所有指标均由mdatagen从 metadata.yaml 自动生成可在 internal/metadata/generated_telemetry.go 中看到对应的TelemetryBuilder字段声明。按功能可划分为六组分组指标度量类型语义入队失败otelcol_exporter_enqueue_failed_{log_records,metric_points,profile_samples,spans}Sum未能进入发送队列而被丢弃的数据量在途请求otelcol_exporter_in_flight_requestsSumUpDown当前正在导出含重试退避的请求数批量发送otelcol_exporter_queue_batch_send_size、otelcol_exporter_queue_batch_send_size_bytesHistogram每次发出的批次规模单位数 / 字节数队列状态otelcol_exporter_queue_capacity、otelcol_exporter_queue_sizeGauge重试队列的固定容量与当前积压发送失败otelcol_exporter_send_failed_{log_records,metric_points,profile_samples,spans}Sum发往目标端失败的记录数发送成功otelcol_exporter_sent_{log_records,metric_points,profile_samples,spans}Sum成功送达目标端的记录数四类信号traces / metrics / logs / profiles各自的计数指标共享同一套模板仅 unit 与稳定性等级不同。下面逐组详解完整继承原始定义。入队失败类enqueue_failed_*数据在进入发送队列之前就被拒绝时例如队列已满、持久化队列底层存储不可写不会进入 exporter 的重试逻辑而是直接丢弃并由这组指标统计。Tempo 场景下这类指标是判断入口流量是否被背压丢数据的第一信号。otelcol_exporter_enqueue_failed_log_records未能加入发送队列的日志记录数。UnitMetric TypeValue TypeMonotonicStability{record}SumInttrueAlphaotelcol_exporter_enqueue_failed_metric_points未能加入发送队列的指标数据点数。UnitMetric TypeValue TypeMonotonicStability{datapoint}SumInttrueAlphaotelcol_exporter_enqueue_failed_profile_samples未能加入发送队列的 profile 样本数该指标仍处于 Development 阶段。UnitMetric TypeValue TypeMonotonicStability{sample}SumInttrueDevelopmentotelcol_exporter_enqueue_failed_spans未能加入发送队列的 span 数。UnitMetric TypeValue TypeMonotonicStability{span}SumInttrueAlpha在途请求otelcol_exporter_in_flight_requests当前处于“在途”状态的导出请求数包括重试退避期间等待中的请求。它是 UpDownCounterMonotonic 为 false会随请求开始与结束上下波动。该指标用于评估 exporter 的并发压力数值长期接近上限说明目标端处理不过来。UnitMetric TypeValue TypeMonotonicStability{request}SumIntfalseDevelopment批量发送直方图queue_batch_send_size 与 _bytesotelcol_exporter_queue_batch_send_size统计每次实际发出的批次包含的单位数span / 指标点 / 日志记录数可用于验证批处理配置min_size、max_size是否生效。UnitMetric TypeValue TypeStability{unit}HistogramIntDevelopmentotelcol_exporter_queue_batch_send_size_bytes统计发出的批次序列化后的字节数仅在 detailed 级别的遥测下可用。两个直方图的 bucket 边界定义在 metadata.yaml 中前者覆盖 10 到 100000后者覆盖 10 到 6000。UnitMetric TypeValue TypeStabilityByHistogramIntDevelopment队列状态queue_capacity 与 queue_sizeotelcol_exporter_queue_capacity重试队列的固定容量单位是批次batch。它由sending_queue.queue_size配置决定默认 1000 批是稳定的 Gauge。UnitMetric TypeValue TypeStability{batch}GaugeIntAlphaotelcol_exporter_queue_size重试队列当前积压的批次数量同样是 Gauge。它反映了瞬时背压水平queue_size / queue_capacity逼近 1 时意味着即将出现入队失败即enqueue_failed_*开始增长。UnitMetric TypeValue TypeStability{batch}GaugeIntAlpha发送失败类send_failed_*记录发往目标端的失败尝试中涉及的数据量。在 detailed 遥测级别下该组指标带有两个属性error.type遵循语义约定与error.permanent标识错误是否永久性、不可重试。error.permanent常量定义于 internal/obs_report_sender.goErrorPermanentKey error.permanent。永久性错误如数据格式非法不会被重试逻辑挽回可结合该属性对失败原因分类治理。otelcol_exporter_send_failed_log_records发往目标端失败的日志记录数。UnitMetric TypeValue TypeMonotonicStability{record}SumInttrueAlphaotelcol_exporter_send_failed_metric_points发往目标端失败的指标数据点数。UnitMetric TypeValue TypeMonotonicStability{datapoint}SumInttrueAlphaotelcol_exporter_send_failed_profile_samples发往目标端失败的 profile 样本数Development 阶段。UnitMetric TypeValue TypeMonotonicStability{sample}SumInttrueDevelopmentotelcol_exporter_send_failed_spans发往目标端失败的 span 数。UnitMetric TypeValue TypeMonotonicStability{span}SumInttrueAlpha发送成功类sent_*与失败类一一对应统计成功送达目标端的记录数。成功率 sent / (sent send_failed)两个指标均为单调递增的 Counter可在 Prometheus 中用rate()观察趋势。otelcol_exporter_sent_log_records成功发往目标端的日志记录数。UnitMetric TypeValue TypeMonotonicStability{record}SumInttrueAlphaotelcol_exporter_sent_metric_points成功发往目标端的指标数据点数。UnitMetric TypeValue TypeMonotonicStability{datapoint}SumInttrueAlphaotelcol_exporter_sent_profile_samples成功发往目标端的 profile 样本数Development 阶段。UnitMetric TypeValue TypeMonotonicStability{sample}SumInttrueDevelopmentotelcol_exporter_sent_spans成功发往目标端的 span 数。UnitMetric TypeValue TypeMonotonicStability{span}SumInttrueAlpha指标背后的实现观测链路与 sender 链理解这些指标的发出位置有助于在实际排障时定位问题出自哪一层。sender 链的构建顺序在 internal/base_exporter.go 的NewBaseExporter中发送链路按以下顺序包装数据从内向外依次经过Consumer Sender真正的导出逻辑调用目标 exporterTimeout Sender仅当timeout非 0 时启用控制单次导出尝试的时间上限Retry Sender仅当retry_on_failure.enabled时启用负责指数退避重试ObsReport Sender总是启用负责采集发送成功 / 失败 / 在途指标Queue Sender仅当配置了sending_queue时启用负责排队与批处理并把数据交给firstSender。因此指标采集ObsReport位于重试与队列之间入队失败enqueue_failed发生在进入 Queue Sender 之前不会到达重试逻辑发送失败 / 成功send_failed / sent与在途in_flight则由 ObsReport 在重试之外统计。观测实现细节obsReportSender见 internal/obs_report_sender.go为每个 exporter 与信号组合创建 span命名格式为exporter/exporter_id/signal并附带exporter、data_type属性。TelemetryBuildergenerated_telemetry.go通过NewTelemetryBuilder从组件级TelemetrySettings的MeterProvider创建所有计数器、直方图与可观测 Gauge两个队列 Gaugequeue_capacity/queue_size通过RegisterExporterQueueCapacityCallback/RegisterExporterQueueSizeCallback注册异步回调采集。Feature Gateexporter.PersistRequestContextdocumentation.md的 Feature Gates 部分定义了一个与持久化队列相关的开关Feature GateStageDescriptionFrom VersionTo Versionexporter.PersistRequestContextstable控制是否将 context 与请求一起存储进持久化队列v0.128.0v0.154.0该开关的元数据同时登记在 metadata.yaml 中对应 OpenTelemetry Collector PR #13188。含义要点启用后请求的 context含 client metadata 与 span context会随数据一并持久化重启后恢复导出的数据仍能保留这些上下文信息但需要注意Auth 扩展写入 context 的鉴权信息不会被持久化详见 README.md因此持久化队列恢复出的数据不携带认证上下文该开关从 v0.128.0 引入、v0.154.0 后行为固化stable阶段当前仓库 vendored 的版本为 v0.153.0正处于该开关的有效窗口内。更完整的 Feature Gate 机制说明见 Collector 的featuregate包文档。配置与指标联动从 README 继承的完整参数表exporterhelper的 README 给出了与上述指标直接相关的全部配置项理解它们才能正确解读指标。以下参数均可在使用 Collector exporter 的配置或 Tempo 内嵌 collector 组件的构造代码中设置。失败重试 retry_on_failure参数默认值说明enabledtrue是否在导出失败后重试initial_interval5s首次失败后的等待时间enabledfalse时忽略max_interval30s退避间隔上限enabledfalse时忽略max_elapsed_time300s发送单个批次累计花费的最大时间设为 0 表示永不停止重试enabledfalse时忽略multiplier1.5每次重试间隔的放大倍数enabledfalse时忽略对应的默认值与校验逻辑位于 vendor/go.opentelemetry.io/collector/config/configretry/backoff.go默认间隔 5s、间隔上限 30s、最大累计时间 5 分钟校验规则要求max_elapsed_time不小于initial_interval与max_interval。重试采用指数退避cenkalti/backoff并带随机化因子randomization_factor默认在 [0,1] 内。这些重试行为与otelcol_exporter_in_flight_requests退避期间仍算在途以及send_failed_*的error.permanent属性直接相关。发送队列 sending_queue参数默认值说明enabledtrue是否启用发送队列num_consumers10从队列取批次的消费者数量enabledfalse时忽略wait_for_resultfalse入队请求是否阻塞等待处理结果block_on_overflowfalse队列满时是否阻塞等待空位为 false 则立即拒绝数据sizerrequests队列与批处理的计量方式requests按请求/批次数性能最佳、items按最小数据单元数、bytes按序列化字节数性能最差queue_size1000队列可容纳的最大批次数量单位由sizer决定batch禁用批处理配置见下失败行为数据无法进入发送队列时通常被丢弃——包括队列达到容量上限或持久化队列底层存储无法写入磁盘空间不足、I/O 错误。启用block_on_overflow后调用方可能等待空位并在超时前成功入队。被拒数据不会进入重试逻辑由otelcol_exporter_enqueue_failed_*统计——这正是解读该组指标的关键前提见 README.md。批量设置 batch默认关闭显式写batch: {}可启用默认值参数默认值说明flush_timeout200ms批次达到该时间即发出必须非 0min_size8192批次的单位数下限若batch::sizer与sending_queue::sizer相同则应不大于queue_sizemax_size0批次单位数上限支持拆分超大批次0 表示无上限sizer继承父级items或bytes未设置时取父结构值父级也未设置则默认itemspartition空批次分区metadata_keys为client.Metadata键列表按键值组合分派到不同 batcher空值/未设置视为独立分区键不区分大小写重复项触发校验错误批次的最终规模反映在otelcol_exporter_queue_batch_send_size与_bytes直方图中可用其分位数验证min_size/max_size设置的实际效果。超时 timeout参数默认值说明timeout5s每次向目标端发送数据的单次尝试等待时间initial_interval、max_interval、max_elapsed_time与timeout均接受 Go duration 字符串如5s、1m合法时间单位包括ns、us或µs、ms、s、m、h。持久化队列Persistent Queue启用持久化队列只需设置sending_queue.storage指向某个 storage 扩展如 filestorage此时不再使用内存队列磁盘上缓存的批次上限同样由queue_size控制默认 1000 批。Collector 进程被杀死时队列中残留的批次会在重启后继续导出。README 给出了完整示例配置receivers: otlp: protocols: grpc: exporters: otlp_grpc: endpoint: ENDPOINT sending_queue: storage: file_storage/otc extensions: file_storage/otc: directory: /var/lib/storage/otc timeout: 10s service: extensions: [file_storage] pipelines: metrics: receivers: [otlp] exporters: [otlp] logs: receivers: [otlp] exporters: [otlp] traces: receivers: [otlp] exporters: [otlp]对应的队列状态queue_capacity/queue_size与批次大小直方图在持久化模式下同样有效可用于监控磁盘队列积压与消费速度。运维实践用这些指标定位导出链路问题综合上述定义可形成以下排障路径以 trace 信号为例otelcol_exporter_sent_spans的rate()与otelcol_exporter_enqueue_failed_spans对比如果入队失败持续增长而发送成功平稳问题在队列容量或持久化存储如磁盘满而不是目标端otelcol_exporter_queue_size / otelcol_exporter_queue_capacity逼近 1队列接近打满优先扩容queue_size或增加num_consumers并检查block_on_overflow设置以避免静默丢弃otelcol_exporter_in_flight_requests长期处于高位目标端吞吐不足重试退避中的请求也计入该值需检查retry_on_failure的退避参数与目标端健康otelcol_exporter_send_failed_spans增长按error.permanent属性区分永久性失败与可重试失败永久性失败如数据格式错误应在上游治理可重试失败则可调整initial_interval/max_interval/max_elapsed_time批次直方图形态异常otelcol_exporter_queue_batch_send_size若始终贴近min_size且flush_timeout频繁触发说明流量稀疏可下调min_size以降低延迟。上述全部指标的定义源文件为 documentation.md指标元数据含直方图 bucket 边界与稳定性声明可在 metadata.yaml 中查阅生成代码位于 internal/metadata/generated_telemetry.go。需要留意的是各指标的 Stability 差异Alpha / Development意味着其 API 与语义在 Collector 演进中可能调整升级版本时应回归核对告警规则。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考