# トレースエクスポーター - Zipkin

> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/trace/sdk_exporters/zipkin/


**ステータス**: [Deprecated](/works/otel-specs-ja/spec/document-status/)

Zipkinエクスポーターのサポートは、2026年12月にOpenTelemetry仕様書から削除される予定です。

> [!NOTE]
> このドキュメントは後方互換性のためにここに残されており、将来のバージョンで削除されます。既存の安定版Zipkinエクスポーターは、[SDKの安定性の保証](/works/otel-specs-ja/spec/versioning-and-stability/#sdk-supportsdkサポート)に従い、アーティファクトが非推奨になってから最低1年間はサポートを継続しなければなりません（MUST）。新しいSDKでZipkinエクスポーターを実装することは求められません。
>
> 利用者は、[Zipkinエクスポーター](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/zipkinexporter)Collectorコンポーネントや、[zipkin-otel](https://github.com/openzipkin-contrib/zipkin-otel)のZipkinサーバーモジュールを使ってもかまいません。

このドキュメントは、OpenTelemetryとZipkinのスパン間の変換を定義します。ここで指定されている[汎用の変換規則](/works/otel-specs-ja/spec/common/mapping-to-non-otlp/)も適用されます。特定の汎用変換規則とこのドキュメントの規則が矛盾する場合は、このドキュメントの規則を使わなければなりません（MUST）。

Zipkinのv2 APIは[zipkin.proto](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto)で定義されています。

## Summary

以下の表は、OpenTelemetryとZipkinの間の主要な変換をまとめたものです。

| OpenTelemetry              | Zipkin           | 注記                                                                                                                 |
| --------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Span.TraceId               | Span.trace_id    |                                                                                                                       |
| Span.ParentId              | Span.parent_id   |                                                                                                                       |
| Span.SpanId                | Span.id          |                                                                                                                       |
| Span.TraceState            | TBD              | TBD                                                                                                                   |
| Span.Name                  | Span.name        |                                                                                                                       |
| Span.Kind                  | Span.kind        | 値のマッピングについては[SpanKind](#spankind)を参照                                                                          |
| Span.StartTime             | Span.timestamp   | [時刻の単位](#unit-of-time)を参照                                                                                     |
| Span.EndTime               | Span.duration    | Durationは、StartTimeとEndTimeに基づいて算出されます。[時刻の単位](#unit-of-time)も参照                                         |
| Span.Attributes            | Span.tagsに追加 | マッピングにおけるデータ型については[Attributes](/works/otel-specs-ja/spec/common/#attribute)を参照                                    |
| Span.DroppedAttributesCount| Span.tagsに追加 | 使用すべきタグ名については[Dropped Attributes Count](/works/otel-specs-ja/spec/common/mapping-to-non-otlp/#dropped-attributes-count)を参照     |
| Span.Events                | Span.annotations | マッピング形式については[Events](#events)を参照                                                                          |
| Span.DroppedEventsCount    | Span.tagsに追加 | 使用すべきタグ名については[Dropped Events Count](/works/otel-specs-ja/spec/common/mapping-to-non-otlp/#dropped-events-count)を参照             |
| Span.Links                 | TBD              | TBD                                                                                                                   |
| Span.DroppedLinksCount     | Span.tagsに追加 | 使用すべきタグ名については[Dropped Links Count](/works/otel-specs-ja/spec/common/mapping-to-non-otlp/#dropped-links-count)を参照               |
| Span.Status                | Span.tagsに追加 | 使用すべきタグ名については[Status](#status)を参照                                                                           |

TBD：これは進行中のドキュメントであり、現時点では以下のフィールドについてのマッピングを指定していません。

OpenTelemetry側のフィールド。

- リソース属性
- Tracestate
- Links

Zipkin側のフィールド。

- local_endpoint
- debug
- shared

## Mappings

このセクションでは、OpenTelemetryとZipkinの間の変換の詳細を説明します。

### Service name

Zipkinのservice nameは、[リソース属性](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md)`service.name`の値に設定しなければなりません（MUST）。Spanのリソースに`service.name`が含まれていない場合、[デフォルト](/works/otel-specs-ja/spec/resource/sdk/#sdkが提供するリソース属性)の`Resource`から設定されなければなりません（MUST）。

Zipkinでは、ローカルルート内のすべてのスパンでservice nameが一貫していることが重要です。一貫していない場合、サービスグラフや集約が正しく機能しません。OpenTelemetryはこの一貫性を保証しません。エクスポーターは、Zipkinでのユーザー体験を向上させるため、ローカルルートスパンに基づいてservice nameの値を上書きするように選択してもかまいません。

属性`service.namespace`はZipkinのservice nameに使ってはならず（MUST NOT）、Zipkinのタグとして送信すべきです（SHOULD）。

### 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`に設定）しなければならない |

### Remote endpoint

#### OTLP -> Zipkin

Zipkinの`SpanKind`が`SpanKind.CLIENT`または`SpanKind.PRODUCER`に解決される場合、サービスはremote endpointを指定すべきです（SHOULD）。指定しない場合、Zipkinはそのスパンを依存関係として扱いません。`peer.service`が優先される属性ですが、常に利用できるわけではありません。以下の表は、`remoteEndpoint`に使える属性を優先順位付きで示しています。

|順位|属性名|理由|
|---|---|---|
|1|peer.service|[リモートサービスを表すOpenTelemetryの採用属性。](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)|
|2|server.address|[リモートのホスト名などを表すOpenTelemetryの採用属性。](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)|
|3|net.peer.name|[リモートのホスト名などを表すレガシーなOpenTelemetryの採用属性。](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/span-general.md#general-network-connection-attributes)|
|4|network.peer.address & network.peer.port|[ピアのリモートソケットアドレスを表すOpenTelemetryの採用属性。](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)|
|5|server.socket.domain|[ピアのリモートソケットのホスト名を表すレガシーなOpenTelemetryの採用属性。](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/docs/general/general-attributes.md#server-and-client-attributes)|
|6|server.socket.address & server.socket.port|[ピアのリモートソケットアドレスを表すレガシーなOpenTelemetryの採用属性。](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/docs/general/general-attributes.md#server-and-client-attributes)|
|7|net.sock.peer.name|[ピアのリモートソケットのホスト名を表すレガシーなOpenTelemetryの採用属性。](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/span-general.md#general-network-connection-attributes)|
|8|net.sock.peer.addr & net.sock.peer.port|[ピアのリモートソケットアドレスを表すレガシーなOpenTelemetryの採用属性。](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/span-general.md#general-network-connection-attributes)|
|9|peer.hostname|OpenTracing仕様で定義されたリモートホスト名。|
|10|peer.address|OpenTracing仕様で定義されたリモートアドレス。|
|11|db.name|DBのSpanで一般的に使われるデータベース名の属性。|

* 選択の順序は順位によって決まるべきです（SHOULD）。例えば`server.address`（順位2）は`peer.address`（順位11）より先に選択されるべきです（SHOULD）。
* `network.peer.address`はそれ単体で`remoteEndpoint`として使えますが、`network.peer.port`も存在する場合はそれと組み合わせるべきです（SHOULD）。

#### Zipkin -> OTLP

Zipkinから OTLPへマッピングする場合、`peer.service`タグが明示的に定義されていない限り、`remoteEndpoint`から`peer.service`タグを設定します。

### Attribute

OpenTelemetryのSpanの`Attribute`は、Zipkinの`tags`として報告しなければなりません（MUST）。

[セマンティック規約](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md)ドキュメントで定義されている一部の属性は、Zipkinのスパンの強く型付けされたフィールドにマッピングされます。

プリミティブ型は、en-USのカルチャ設定を使って文字列に変換しなければなりません（MUST）。ブーリアン値は、小文字の文字列`"true"`と`"false"`を使わなければなりません（MUST）。

配列の値は、[セマンティック規約](/works/otel-specs-ja/spec/overview/#セマンティック規約)で言及されているように、JSONリストのような文字列にシリアライズしなければなりません（MUST）。

TBD：例を追加する。

### Status

このセクションは、[汎用のStatusマッピング規則](/works/otel-specs-ja/spec/common/mapping-to-non-otlp/#span-status)を上書きします。

Spanの`Status`は、`UNSET`でない限り、Zipkinの`tags`内のキーと値の組として報告しなければなりません（MUST）。`UNSET`の場合は報告してはなりません（MUST NOT）。

以下の表は、OpenTelemetryの`Status`からZipkinの`tags`へのマッピングを定義しています。

| Status | タグキー | タグの値 |
| --- | --- | ---- |
| Code | `otel.status_code` | コードの名前。`OK`または`ERROR`のいずれか。コードが`UNSET`の場合は設定してはならない（MUST NOT）。 |
| Description | `error` | `Status`の説明。コードが`ERROR`の場合は設定しなければならず（MUST）、Descriptionに値がない場合は空文字列を使う。`OK`と`UNSET`のコードには設定してはならない（MUST NOT）。 |

注記：`error`タグは、`Status`が`Error`の場合にのみ設定すべきです（SHOULD）。ブーリアン形式の値（`{"error":false}`や`{"error":"false"}`）が存在する場合は、それを取り除くべきです（SHOULD）。Zipkinは`error`が送信されたスパンをすべて失敗として扱います。

### Events

OpenTelemetryの`Event`は、Zipkinがサポートしないオプションの`Attribute`を持てます。Eventは、次のように属性値を含む名前を持つAnnotationに変換しなければなりません（MUST）。

```
"my-event-name": { "key1" : "value1", "key2": "value2" }
```

### Unit of Time

Zipkinの`timestamp`、`duration`、`annotation.timestamp`のような時刻は、整数のマイクロ秒で報告しなければなりません（MUST）。例えば1234ナノ秒の`duration`は1マイクロ秒として表現されます。

## Request Payload

パフォーマンス上の理由から、値が空であるフィールドについては、OpenTelemetryの`Span`で空である場合、Zipkinのペイロードから省略すべきです（SHOULD）。

例えば、`Event`を1つも持たないOpenTelemetryの`Span`は、Zipkinのペイロードに`annotations`フィールドを持つべきではありません（SHOULD NOT）。

## Considerations for Legacy (v1) Format

Zipkinのv2の[json](https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml)形式は2017年に定義され、続いて2018年に[protobuf](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto)形式が定義されました。

それ以前に作られたフレームワークは、より複雑なv1の[Thrift](https://github.com/openzipkin/zipkin-api/blob/master/thrift/zipkinCore.thrift)形式や[json](https://github.com/openzipkin/zipkin-api/blob/master/zipkin-api.yaml)形式を使っており、これらはBinary Annotationのような用語を使い、各属性にエンドポイント情報を繰り返す点で明確に異なっています。

v1モデルをOpenTelemetryへ変換するための参考実装として、[V1SpanConverter.java](https://github.com/openzipkin/zipkin/blob/master/zipkin/src/main/java/zipkin2/v1/V1SpanConverter.java)の利用を検討してください。

スパンのtimestampとdurationは、V1形式に後から追加されたものです。上記のコードへのリンクにあるように、annotationからヒューリスティックにこれらを導出できます。