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

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/trace/sdk_exporters/zipkin/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: Deprecated

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

[!NOTE] このドキュメントは後方互換性のためにここに残されており、将来のバージョンで削除されます。既存の安定版Zipkinエクスポーターは、SDKの安定性の保証に従い、アーティファクトが非推奨になってから最低1年間はサポートを継続しなければなりません（MUST）。新しいSDKでZipkinエクスポーターを実装することは求められません。
利用者は、ZipkinエクスポーターCollectorコンポーネントや、zipkin-otelのZipkinサーバーモジュールを使ってもかまいません。

このドキュメントは、OpenTelemetryとZipkinのスパン間の変換を定義します。ここで指定されている汎用の変換規則も適用されます。特定の汎用変換規則とこのドキュメントの規則が矛盾する場合は、このドキュメントの規則を使わなければなりません（MUST）。

Zipkinのv2 APIは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を参照
Span.StartTime	Span.timestamp	時刻の単位を参照
Span.EndTime	Span.duration	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	TBD	TBD
Span.DroppedLinksCount	Span.tagsに追加	使用すべきタグ名についてはDropped Links Countを参照
Span.Status	Span.tagsに追加	使用すべきタグ名についてはStatusを参照

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

OpenTelemetry側のフィールド。

リソース属性
Tracestate
Links

Zipkin側のフィールド。

local_endpoint
debug
shared

Mappings

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

Service name

Zipkinのservice nameは、リソース属性service.nameの値に設定しなければなりません（MUST）。Spanのリソースにservice.nameが含まれていない場合、デフォルトの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の採用属性。
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	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）。

セマンティック規約ドキュメントで定義されている一部の属性は、Zipkinのスパンの強く型付けされたフィールドにマッピングされます。

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

配列の値は、セマンティック規約で言及されているように、JSONリストのような文字列にシリアライズしなければなりません（MUST）。

TBD：例を追加する。

Status

このセクションは、汎用の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形式は2017年に定義され、続いて2018年にprotobuf形式が定義されました。

それ以前に作られたフレームワークは、より複雑なv1のThrift形式やjson形式を使っており、これらはBinary Annotationのような用語を使い、各属性にエンドポイント情報を繰り返す点で明確に異なっています。

v1モデルをOpenTelemetryへ変換するための参考実装として、V1SpanConverter.javaの利用を検討してください。

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