Grafana Tempo 中 OTLP 接收端配置问题解析与解决方案

问题背景

在分布式追踪系统的搭建过程中，Grafana Tempo 作为一款开源的分布式追踪后端，常与 OpenTelemetry 协议（OTLP）配合使用。然而在实际部署时，开发者经常会遇到 OTLP 接收端配置不当导致 404 错误的问题，特别是当尝试通过 HTTP 协议向 Tempo 发送追踪数据时。

核心问题分析

默认情况下，Grafana Tempo 2.7.0 版本中的 OTLP 接收器存在两个关键配置特性：

1. 监听地址限制：从 Tempo 2.7.0 版本开始，OTLP 接收器默认只绑定到 localhost 接口，这意味着容器外部无法直接访问。

2. 端点路径差异：Tempo 默认的 HTTP 接收路径为 /v1/traces，而许多开发者（特别是使用 Grafana Cloud 服务的用户）习惯性地认为路径应该是 /otlp/v1/traces，这种认知差异会导致请求失败。

详细解决方案

1. 正确配置 OTLP 接收器

在 Tempo 的配置文件 config.yaml 中，需要对 OTLP 接收器进行明确配置：

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: "0.0.0.0:4317"  # 明确指定监听所有接口
        http:
          endpoint: "0.0.0.0:4318"  # 明确指定监听所有接口
          traces_url_path: "/otlp/v1/traces"  # 自定义追踪数据接收路径

关键配置说明：

• endpoint 必须明确设置为 0.0.0.0 才能允许容器外访问
• traces_url_path 允许自定义接收路径，保持与云端服务的一致性

2. 客户端配置调整

在使用 Alloy 或其他 OpenTelemetry Collector 作为客户端时，需要确保导出器配置与 Tempo 接收端匹配：

otelcol.exporter.otlphttp "tempo" {
    client {
        endpoint = "http://tempo:4318/otlp"  # 注意此处只包含基础路径
    }
}

注意点：

• 端口必须与接收端配置一致（通常 4318 为 HTTP，4317 为 gRPC）
• 路径结构会自动拼接，只需提供基础路径 /otlp

配置原理深入

1. 路径处理机制：

   • OpenTelemetry Collector 的 OTLP HTTP 接收器默认使用 /v1/traces 路径
   • 通过 traces_url_path 可以覆盖这一默认值
   • 客户端配置的 endpoint 基础路径会与固定后缀拼接形成完整路径

2. 网络访问控制：

   • 2.7.0 版本的安全改进默认限制了网络访问
   • 生产环境中应考虑结合网络策略和认证机制，而非简单开放所有接口

3. 协议选择建议：

   • 对于性能敏感场景，推荐使用 gRPC 协议（端口 4317）
   • HTTP 协议（端口 4318）更适合简单调试和兼容性场景

最佳实践建议

1. 环境一致性：

   • 开发环境应尽量模拟生产环境配置
   • 路径前缀等配置应通过环境变量统一管理

2. 版本兼容性检查：

   • 升级 Tempo 版本时注意检查配置变更日志
   • 特别是安全相关的默认值变更

3. 健康检查机制：

   • 配置完善的健康检查确保服务可用性
   • 对 OTLP 接收端也应设置专门的健康检查

通过以上配置调整和原理理解，开发者可以顺利解决 Tempo 中 OTLP 接收端的 404 错误问题，并建立起更加健壮的追踪数据收集管道。