OpenTelemetry 到 Zipkin 转换
状态: 已弃用
Zipkin 导出器支持将于 2026 年 12 月从 OpenTelemetry 规范中移除。
本文档保留用于向后兼容，将来版本将删除。根据 SDK 稳定性保证 versioning-and-stability.md#sdk-support)，现有稳定的 Zipkin 导出器在工件被弃用后仍必须支持至少一年。新 SDK 不需要实现 Zipkin 导出器。
用户可以使用 Zipkin 导出器 收集器组件或 zipkin-otel Zipkin 服务器模块。
本文档定义了 OpenTelemetry 和 Zipkin Span 之间的转换。此处指定的通用转换 规则 也适用。如果某个通用转换规则与本文档中的规则相冲突，则必须使用本文档中的规则。
Zipkin 的 v2 API 在 zipkin.proto 中定义
摘要
下表总结了 OpenTelemetry 和 Zipkin 之间的主要转换。
| OpenTelemetry | Zipkin | 注意 |
|---|---|---|
| Span.TraceId | Span.trace_id | |
| Span.ParentId | Span.parent_id | |
| Span.SpanId | Span.id | |
| Span.TraceState | 待定 | 待定 |
| Span.Name | Span.name | |
| Span.Kind | Span.kind | 值映射请参阅 SpanKind |
| Span.StartTime | Span.timestamp | 请参阅 时间单位 |
| Span.EndTime | Span.duration | 持续时间根据 StartTime 和 EndTime 计算。另请参阅 时间单位 |
| Span.Attributes | 添加到 Span.tags | 有关映射的数据类型，请参阅 Attributes。 |
| Span.DroppedAttributesCount | 添加到 Span.tags | 要使用的标签名称，请参阅 Dropped Attributes Count。 |
| Span.Events | Span.annotations | 映射格式请参阅 Events。 |
| Span.DroppedEventsCount | 添加到 Span.tags | 要使用的标签名称，请参阅 Dropped Events Count。 |
| Span.Links | 待定 | 待定 |
| Span.DroppedLinksCount | 添加到 Span.tags | 要使用的标签名称，请参阅 Dropped Links Count。 |
| Span.Status | 添加到 Span.tags | 要使用的标签名称，请参阅 Status。 |
待定：本文档仍在进行中，目前尚未指定这些字段的映射
OpenTelemetry 字段
- 资源属性
- Tracestate
- 链接
Zipkin 字段
- local_endpoint
- debug
- shared
映射
本节讨论 OpenTelemetry 和 Zipkin 之间转换的详细信息。
服务名称
Zipkin 服务名称必须设置为 资源属性：service.name 的值。如果 Span 的 Resource 中不包含 service.name，则必须从 默认 Resource 中填充。在 Zipkin 中，服务名称对于本地根中的所有 span 保持一致非常重要。否则，服务图和聚合将无法正常工作。OpenTelemetry 不提供此一致性保证。导出器可能会根据本地根 span 覆盖服务名称的值，以改善 Zipkin 用户体验。
请注意，属性 service.namespace 不得用于 Zipkin 服务名称，而应作为 Zipkin 标签发送。
SpanKind
下表列出了 OpenTelemetry 和 Zipkin 之间所有 SpanKind 的映射。
| OpenTelemetry | Zipkin | 注意 |
|---|---|---|
SpanKind.CLIENT | SpanKind.CLIENT | |
SpanKind.SERVER | SpanKind.SERVER | |
SpanKind.CONSUMER | SpanKind.CONSUMER | |
SpanKind.PRODUCER | SpanKind.PRODUCER | |
SpanKind.INTERNAL | null | 必须省略（设置为 null） |
远程端点
OTLP -> Zipkin
如果 Zipkin SpanKind 解析为 SpanKind.CLIENT 或 SpanKind.PRODUCER，则服务应指定远程端点，否则 Zipkin 将不会将 Span 视为依赖项。peer.service 是首选属性，但并非始终可用。下表按首选排名列出了 remoteEndpoint 的可能属性
| 排名 | 属性名称 | 原因 |
|---|---|---|
| 1 | peer.service | OpenTelemetry 采用的远程服务属性。 |
| 2 | server.address | OpenTelemetry 采用的远程主机名或类似属性。 |
| 3 | net.peer.name | 遗留 OpenTelemetry 采用的远程主机名或类似属性。 |
| 4 | network.peer.address & network.peer.port | OpenTelemetry 采用的远程套接字地址属性。 |
| 5 | server.socket.domain | 遗留 OpenTelemetry 采用的远程套接字主机名属性。 |
| 6 | server.socket.address & server.socket.port | 遗留 OpenTelemetry 采用的远程套接字地址属性。 |
| 7 | net.sock.peer.name | 遗留 OpenTelemetry 采用的远程套接字主机名属性。 |
| 8 | net.sock.peer.addr & net.sock.peer.port | 遗留 OpenTelemetry 采用的远程套接字地址属性。 |
| 9 | peer.hostname | OpenTracing 规范中定义的远程主机名。 |
| 10 | peer.address | OpenTracing 规范中定义的远程地址。 |
| 11 | db.name | 数据库 Span 中常用的数据库名称属性。 |
- 排名应控制选择顺序。例如，
server.address(排名 2) 应在peer.address(排名 11) 之前选择。 network.peer.address可单独用作remoteEndpoint，但如果network.peer.port也存在，则应与其结合使用。
Zipkin -> OTLP
从 Zipkin 映射到 OTLP 时，应将 peer.service 标签从 remoteEndpoint 设置，除非明确定义了 peer.service 标签。
属性
OpenTelemetry Span 的 Attribute (S) 必须作为 tags 报告给 Zipkin。
semantic convention 文档中定义的一些属性会映射到 Zipkin span 的强类型字段。
基元类型必须使用 en-US 区域设置转换为字符串。布尔值必须使用小写字符串 "true" 和 "false"。
数组值必须如 语义约定 所述，序列化为字符串，形式为 JSON 列表。
待定：添加示例
状态
本节覆盖 通用 Status 映射规则。
Span Status 必须作为键值对报告在 Zipkin 的 tags 中，除非其为 UNSET。后一种情况则必须不报告。
下表定义了 OpenTelemetry Status 到 Zipkin tags 的映射。
| 状态 | 标签键 | 标签值 |
|---|---|---|
| Code | otel.status_code | 代码名称，为 OK 或 ERROR。如果代码为 UNSET，则不得设置。 |
| 描述 | 错误 | Status 的描述。如果代码为 ERROR，则必须设置；如果 Description 没有值，则使用空字符串。不得为 OK 和 UNSET 代码设置。 |
注意：仅当 Status 为 Error 时才应设置 error 标签。如果存在布尔版本（{"error":false} 或 {"error":"false"}），则应将其删除。Zipkin 将任何发送了 error 的 span 都视为失败。
事件
OpenTelemetry Event 具有可选的 Attribute(s)，Zipkin 不支持。Events 必须转换为 Annotations，其名称将包含属性值，如下所示
"my-event-name": { "key1" : "value1", "key2": "value2" }
时间单位
Zipkin 的时间，如 timestamp、duration 和 annotation.timestamp，必须以微秒为单位报告为整数。例如，1234 纳秒的 duration 将表示为 1 微秒。
请求载荷
出于性能考虑，当 Zipkin 字段在 OpenTelemetry Span 中为空时，应将其从载荷中省略。
例如，一个没有 Event 的 OpenTelemetry Span 在 Zipkin 载荷中不应包含 annotations 字段。
关于遗留 (v1) 格式的注意事项
Zipkin 的 v2 json 格式定义于 2017 年，随后在 2018 年发布了 protobuf 格式。
在此之前的框架使用更复杂的 v1 Thrift 或 json 格式，其显著区别在于使用了诸如 Binary Annotation 等术语，并在每个属性上重复端点信息。
考虑使用 V1SpanConverter.java 作为将 v1 模型转换为 OpenTelemetry 的参考实现。
Span 的时间戳和持续时间是 V1 格式的后期添加项。如上面的代码链接所示，可以从注解中推导出它们。