OpenTelemetry Rust 中 HTTP/JSON 导出器的链接序列化问题解析

在 OpenTelemetry Rust 实现中，HTTP/JSON 导出器在处理链路追踪数据时存在一个重要的序列化问题。这个问题主要影响链路追踪数据中链接(Link)和示例(Exemplar)的标识字段格式。

问题现象

当使用 HTTP/JSON 导出器发送追踪数据时，生成的 JSON 数据中链接(Link)的 traceId 和 spanId 字段被错误地序列化为整数数组。例如：

"links": [
  {
    "traceId": [157,48,54,48,139,160,71,67,152,135,40,155,119,66,113,189],
    "spanId": [233,128,29,199,119,206,74,251]
  }
]

规范要求

根据 OpenTelemetry 协议(OTLP)规范 1.3.2 版本，traceId 和 spanId 应该被编码为十六进制字符串，而不是整数数组。规范明确指出：

• traceId 和 spanId 字节数组应表示为不区分大小写的十六进制编码字符串
• 不应使用标准 Protobuf JSON 映射中定义的 base64 编码
• 这种十六进制编码适用于所有 OTLP Protobuf 消息中的 traceId 和 spanId 字段

正确的格式应该如下所示：

"traceId": "5B8EFFF798038103D269B633813FC60C"

影响范围

这个问题不仅影响链路追踪中的 Link 结构，同样也影响指标数据中的 Exemplar 结构。这两个数据结构都包含 traceId 和 spanId 字段，因此都会受到相同的序列化问题影响。

技术背景

在 OpenTelemetry 的实现中，traceId 和 spanId 在内存中通常以字节数组的形式存储。当需要序列化为 JSON 格式时，需要进行适当的编码转换。问题出在当前的实现直接使用了 Protobuf 的默认 JSON 序列化方式，而没有按照 OTLP 规范的特殊要求进行处理。

解决方案

要解决这个问题，需要在 JSON 序列化过程中对 traceId 和 spanId 字段进行特殊处理：

1. 将字节数组转换为十六进制字符串
2. 确保字符串使用大写或小写字母（规范不区分大小写）
3. 在反序列化时，需要将十六进制字符串转换回字节数组

这种处理方式需要在导出器的 JSON 序列化层实现，而不是依赖默认的 Protobuf JSON 序列化机制。

总结

OpenTelemetry Rust 实现中的这个序列化问题会导致生成的 JSON 数据不符合 OTLP 规范，可能影响与后端系统的兼容性。开发人员在使用 HTTP/JSON 导出器时应当注意这个问题，特别是在与严格要求符合 OTLP 规范的后端系统集成时。这个问题已经在后续版本中得到修复，使用最新版本可以避免此类兼容性问题。