Grafana Tempo 中的 gRPC 配置指南：深入 OpenTelemetry Collector configgrpc 客户端与服务端设置

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

导读

Grafana Tempo 的分布式追踪后端通过 OTLP gRPC 协议接收遥测数据，其底层网络配置正是由 OpenTelemetry Collector 的configgrpc配置包驱动。本文以vendor/go.opentelemetry.io/collector/config/configgrpc/README.md为骨架，完整解读 gRPC 客户端（Exporter）与服务端（Receiver）的每一项配置参数、Tempo 中的真实落地方式，并结合仓库源码揭示参数背后的实现机制，帮助你精准调优 Tempo 的 OTLP 接入链路。

一、configgrpc 是什么：gRPC 配置的统一抽象

gRPC 本身通过编程方式暴露了种类繁多的设置，而configgrpc将这些设置提炼为可声明式（YAML）配置，供 Collector 生态中的每个 Receiver 或 Exporter 复用。其设计原则是：绝大多数情况下，默认值已经足够，无需调整；只有当遇到连接保活、消息体过大、压缩、负载均衡等特定需求时，才需要显式配置。

在 Tempo 仓库中，该包位于 vendor/go.opentelemetry.io/collector/config/configgrpc，核心实现集中在 configgrpc.go，其中定义了三个核心结构：

• ClientConfig（客户端配置）：被 Exporter 使用，负责发起 gRPC 连接；
• ServerConfig（服务端配置）：被 Receiver 使用，负责监听和接收 gRPC 请求；
• 两类 Keepalive 相关结构：KeepaliveClientConfig与KeepaliveServerConfig（含ServerParameters、EnforcementPolicy）。

对应地，config.schema.yaml 完整描述了这些配置项的 JSON Schema，是 IDE 校验与配置生成的依据。

二、客户端（Exporter）配置详解

在 OpenTelemetry Collector 体系中，Exporter 使用客户端配置。Tempo 的分布式架构中，各种 Agent、Exporter（如 OTLP Exporter）正是通过这套配置向 Tempo 的 Distributor 推送 Span。

2.1 客户端配置参数总览

2.2 一个完整的最小客户端配置示例

原文档给出了 OTLP gRPC Exporter 的典型配置，直接可复制运行：

exporters: otlp_grpc: endpoint: otelcol2:55690 auth: authenticator: some-authenticator-extension tls: ca_file: ca.pem cert_file: cert.pem key_file: key.pem headers: test1: "value1" "test 2": "value 2"

• endpoint不需要携带协议前缀，直接写host:port；
• headers的 key 可含空格，用引号包裹即可；
• auth.authenticator指向一个已注册的认证扩展。

2.3 关于balancer_name的迁移说明

原文档特别强调了一个易踩的坑：在 Collectorv0.103.0 之前，默认负载均衡策略是pick_first；v0.103.0 起默认改为round_robin。如需恢复旧行为，显式设置：

exporters: otlp_grpc: balancer_name: pick_first

在源码层面，configgrpc.go 中定义了DefaultBalancerName = "round_robin"，且NewDefaultClientConfig()将BalancerName初始化为该值；当显式配置了balancer_name时，最终通过grpc.WithDefaultServiceConfig将其写入服务配置（见源码 L444-L446）。

2.4 客户端配置的源码级实现机制

从 getGrpcDialOptions 可以看出配置项如何被翻译成真实的 gRPCDialOption：

• 压缩：Compression.IsCompressed()为真时，通过getGRPCCompressionName解析出 gRPC 注册表中的压缩器名称，并追加grpc.WithDefaultCallOptions(grpc.UseCompressor(cp))；
• TLS：先cc.TLS.LoadTLSConfig(ctx)加载证书；若未配置 TLS，则使用insecure.NewCredentials()；当 endpoint 以https://开头时，会自动启用系统默认 TLS 证书（L397-L407）；
• Keepalive：客户端默认值为time: 10s、timeout: 10s（见NewDefaultKeepaliveClientConfig），映射为grpc.WithKeepaliveParams；
• Headers 注入：addHeadersIfAbsent的实现表明，只有上下文 outgoing metadata 中尚不存在的 key 才会被追加（L371-L380），且该行为通过一元/流式拦截器同时作用于普通 RPC 与流式 RPC；
• 可观测性：无论客户端还是服务端，都会自动挂载otelgrpc的 StatsHandler，把 gRPC 调用纳入 OpenTelemetry 指标与追踪（L452-L459）。

2.5 关于per_rpc_auth的重要变更

原文档提醒：曾经的per_rpc_auth（允许为每个 RPC 发送凭据）已迁移为独立扩展bearertokenauthextension。它与在headers中配置authorization头有本质区别：

• headers中的认证头只在初始连接时发送；
• per_rpc_auth/ 认证扩展在已建立连接的每一次 RPC上都会携带凭据。

因此涉及逐 RPC 认证的场景，应使用认证扩展而不是静态 headers。

三、服务端（Receiver）配置详解

Receiver 使用服务端配置。在 Tempo 中，Distributor 的 OTLP gRPC Receiver 正是服务端配置的典型消费者。

3.1 服务端配置参数总览

3.2 Keepalive 服务端配置结构

服务端 keepalive 分为两层，源码中对应KeepaliveServerConfig（configgrpc.go）：

• server_parameters（对应keepalive.ServerParameters）：
  • max_connection_age：连接最大存活时长；
  • max_connection_age_grace：连接超龄后的宽限期；
  • max_connection_idle：空闲连接最大时长；
  • time：服务端发送 keepalive ping 的间隔；
  • timeout：等待 ping 确认的超时。
• enforcement_policy（对应keepalive.EnforcementPolicy）：
  • min_time：客户端两次 ping 的最小间隔，低于此值会被视为违规；
  • permit_without_stream：是否允许在没有活跃流时发送 ping。

需要注意：这些参数的默认值由 grpc-go 服务端内部统一施加，源码注释（L578-L605）明确指出代码不需要对零值做填充——未配置的字段保持零值直接透传即可。

3.3 服务端配置的源码级实现机制

getGrpcServerOptions 展示了服务端选项的组装顺序：

1. TLS：sc.TLS.Get().LoadTLSConfig(ctx)后通过grpc.Creds挂载；
2. 消息与并发限制：MaxRecvMsgSizeMiB * 1024 * 1024换算为字节，MaxConcurrentStreams直接透传；
3. 拦截器链：按“先 client 信息增强、后 auth”的顺序组合：
   • enhanceWithClientInformation把对端地址写入client.Info；当include_metadata为真时，还会把入站 metadata（并智能地用:authority兜底hostname）注入上下文（L665-L696）；
   • authUnaryServerInterceptor/authStreamServerInterceptor从入站 metadata 提取请求头调用Authenticate，认证失败统一返回codes.Unauthenticated（L698-L736）；
4. 可观测性：与客户端一致挂载otelgrpcStatsHandler，并链式注册所有一元/流式拦截器。

四、压缩算法对比与选择

原文档内置了基于 configgrpc_benchmark_test.go 的完整基准数据，测试环境为 AWS m5.large（Intel Xeon Platinum 8259CL @ 2.50GHz），对 log/trace/metric 三类小、中、大负载分别用gzip、snappy、zstd压缩。下表为文档原始数据的整理：

（小负载如sm_*行中，压缩后体积甚至可能超过原始字节——例如sm_log_request在 gzip 下压缩比仅 0.99、snappy 下为 0.90，负的“MB saved / second”意味着小消息压缩反而“亏本”，详见原文档表格。）

结论与选型建议（原文观点）：

1. 实际压缩比高度依赖数据的信息熵，不同负载差异巨大；
2. 压缩速率取决于 CPU 速度与负载大小——小负载无法摊销固定计算开销，压缩速率相对更慢；
3. gzip是OTLP 服务器唯一强制要求的压缩算法，天然首选：速率不如 snappy，但压缩比更好、性能合理；
4. 若 Collector 是CPU 瓶颈且 OTLP 服务器支持，可改用snappy（速度快一个数量级）；
5. 若 Collector CPU 吃紧且网络链路极快，可考虑直接禁用压缩——不压缩本就是默认行为。

在 Tempo 中，compression参数作用于 Distributor OTLP 接入时的消息传输：Tempo 的 receiver/shim.go 直接复用了otlpreceiver工厂与configgrpc配置体系，因此这里关于压缩的选择同样适用于 Tempo 的 OTLP gRPC 接入。

4.1 压缩参数在源码中的映射

configgrpc.go 的getGRPCCompressionName只接受三种注册过的压缩器名：

• gzip→google.golang.org/grpc/encoding/gzip（通过 gzip.go 的匿名导入自动注册）；
• snappy→ Collector 内部实现的 snappy；
• zstd→ Collector 内部实现的 zstd；

其他值一律返回unsupported compression type错误。此外，compressiontype.go 定义了完整的压缩类型枚举（还包含zlib、deflate、x-snappy-framed、lz4等），并区分“是否启用压缩”（none/空字符串视为不压缩）。

五、在 Grafana Tempo 中的真实落地

5.1 Distributor 的 OTLP gRPC 接收器

Tempo 的 Distributor 通过 modules/distributor/receiver/shim.go 将 OpenTelemetry Collector 的 Receiver 嵌入自身进程。从源码可见其关键路径：

• 注册了otlpreceiver、jaegerreceiver、zipkinreceiver、kafkareceiver四个工厂（L173-L178），其中OTLP Receiver 承载 gRPC/HTTP 双协议；
• 将 Tempo 的 YAML 配置转换为 Collector 配置映射后交给configgrpc解析；
• 对 OTLP 接收器，还显式把 HTTP 协议的IncludeMetadata置为true，以保证认证所需的请求头进入上下文（L263-L269）——这正是 3.3 节include_metadata参数在 Tempo 中的实际用途。

5.2 Tempo 配置中的 gRPC 协议段

单二进制部署的 example/docker-compose/single-binary/tempo.yaml 展示了标准写法：

distributor: receivers: otlp: protocols: grpc: endpoint: "tempo:4317" http: endpoint: "tempo:4318"

其中protocols.grpc下所有可配置字段（endpoint、tls、keepalive、max_recv_msg_size_mib、auth等）均由ServerConfig驱动；endpoint对应confignet.AddrConfig，支持tcp（默认）与unix两种传输。默认端口4317是 OTLP gRPC 的行业标准端口，4318为 OTLP HTTP 端口。

5.3 集成测试验证 gRPC 收发路径

receiver/shim_test.go 的TestShim_integration提供了一个可直接参考的端到端模式：

• 用map[string]interface{}{"otlp": {"protocols": {"grpc": nil}}}启动 Tempo 侧接收器；
• 用otlpexporter配合configgrpc.ClientConfig（Endpoint: "127.0.0.1:4317"、TLS: {Insecure: true}）向 Tempo 推送 5 条随机 trace；
• 断言tempo_receiver_accepted_spans指标带transport="grpc"标签。

这说明：endpoint、tls、headers等客户端配置参数在真实链路中逐一生效，并反映在tempo_receiver_accepted_spans、tempo_receiver_refused_spans等监控指标上（对应receiver/shim.go中注册的receiver_enabled_otlp等 usage 统计）。

六、常见调优场景速查

结语

configgrpc把 grpc-go 庞大而零散的能力封装成一组声明式配置，是 Tempo OTLP gRPC 接入链路的“神经中枢”。掌握客户端/服务端配置的分工、Keepalive 的层级结构、压缩算法的取舍，以及balancer_name等易变默认值，就能在 Tempo 的高吞吐追踪场景中做到精准调优。更进一步，你可以直接阅读 configgrpc.go 观察配置到grpc.ServerOption/grpc.DialOption的翻译过程，或运行 configgrpc_benchmark_test.go 在自己的 CPU 上重新测量压缩性能，从而用数据指导生产环境的参数决策。

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