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 协议层。
