gRPC结合OpenTelemetry实现全链路度量监控

grpc服务未上报指标需检查otelgrpc.unaryserverinterceptor是否漏注册，服务端必须显式配置unaryserverinterceptor和streamserverinterceptor两个拦截器，且需在最外层；若指标缺失label，应启用withmessageevents；status=unknown需自定义withstatushandler；本地调试需确认otlp endpoint、超时及tls配置。

gRPC服务没上报指标？检查 otelgrpc.UnaryServerInterceptor 是否漏注册

OpenTelemetry 的 gRPC 插件不会自动埋点，必须显式注入拦截器。常见错误是只加了客户端拦截器，服务端完全没配，结果只有出向调用有数据，入向请求全无踪迹。

实操上，服务端启动时需在 grpc.Server 初始化阶段传入拦截器：

srv := grpc.NewServer(     grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()),     grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor()), )

• 注意：两个拦截器（UnaryServerInterceptor 和 StreamServerInterceptor）要一起加，否则流式 RPC 不会上报
• 如果用了自定义拦截器链（比如鉴权、日志），得把 OpenTelemetry 拦截器按顺序插入，且确保它在最外层——否则可能错过 span 创建时机
• Go 版本低于 1.21 且用 net/http 封装 gRPC-Web 的场景，需额外配置 otelhttp，不能只靠 gRPC 插件

指标显示为 0 或缺失 label？确认 otelgrpc.WithMessageEvents 和 otelgrpc.WithSpanOptions 的组合使用

默认情况下，OpenTelemetry gRPC 插件只记录 RPC 状态和延迟，不采集请求/响应体大小、消息计数等度量维度。这些需要手动开启事件捕获，否则 prometheus 里看到的 grpc_server_handled_total 没有 message_type 或 compression 标签。

正确做法是在拦截器中加入选项：

grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor(     otelgrpc.WithMessageEvents(otelgrpc.ReceivedEvents, otelgrpc.SentEvents),     otelgrpc.WithSpanOptions(trace.WithAttributes(attribute.String("service.role", "backend"))), ))

• WithMessageEvents 是开关，不加就永远看不到 message.type 标签；但开了会增加 CPU 和内存开销，高吞吐服务慎用
• WithSpanOptions 可追加自定义属性，但别往里面塞大对象或敏感字段，span 属性有默认大小限制（通常 8KB），超限会被截断
• 客户端和服务端拦截器要分别配置，且选项不共享——服务端加了不代表客户端自动生效

为什么 grpc_client_completed_rpcs 指标里 status=Unknown？查 otelgrpc.WithStatusHandler

gRPC 客户端指标中的 status label 常常是 Unknown，不是因为网络问题，而是 OpenTelemetry 默认用 status.FromError(err) 解析错误，而很多 gRPC 错误没带标准 codes.Code，导致 fallback 到 Unknown。

解决方式是提供自定义状态处理器：

otelgrpc.WithStatusHandler(func(ctx context.Context, err error, code codes.Code) codes.Code {     if errors.Is(err, context.DeadlineExceeded) {         return codes.DeadlineExceeded     }     if code == codes.Unknown && err != nil {         return codes.Internal     }     return code })

• 这个函数在每次 RPC 结束时被调用，影响所有指标和 trace 中的 status 字段
• 别直接返回 codes.OK 来“掩盖”错误，这会让告警失效；优先修复上游错误构造逻辑
• 如果用了 gRPC 的 WithBlock() 或重试中间件，status 可能被多次覆盖，需确保 handler 能处理重试后的最终状态

本地调试时指标一直不上报？重点看 otlpgrpc.NewClient 的 endpoint 和 timeout

开发机连不上远端 Collector 是最常见原因，但错误往往藏在细节里：比如 endpoint 写成 localhost:4317，但 Collector 实际监听 0.0.0.0:4317；或者没设 WithTimeout，导致第一次上报卡住 30 秒才超时，看起来像“没反应”。

推荐初始化方式：

exporter, err := otlpgrpc.NewClient(     otlpgrpc.WithEndpoint("localhost:4317"),     otlpgrpc.WithInsecure(), // 本地开发可关 TLS     otlpgrpc.WithTimeout(5 * time.Second), )

• WithInsecure() 必须显式加，否则默认走 TLS，连不上就静默失败
• endpoint 不支持 http:// 前缀，写 http://localhost:4317 会解析失败，报错类似 rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing dial tcp: address http://localhost:4317: too many colons in address"
• Collector 日志要打开 debug 级别，光看客户端没报错不等于数据真到了后端——很多 metric 是 batch 上报的，首次 flush 有延迟

真正难调的是跨语言链路对齐：Go 服务打出来的 span ID 格式和 Java 服务不一致，或者 tracestate 传递被中间网关剥离。这种问题没法靠改几行代码解决，得盯住 wire 协议层。