この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/messaging/kafka/
翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）
Kafkaに関するセマンティック規約
ステータス: Development
Apache Kafkaに関するセマンティック規約は、メッセージングに関するセマンティック規約を拡張し、上書きします。
[!IMPORTANT]
この文書のv1.24.0 以前のバージョンを使っている既存のメッセージング計装は、次に従うべきです。
- メッセージングセマンティック規約が安定版として宣言されるまで、デフォルトで発行するメッセージング規約のバージョンを変更してはなりません（SHOULD NOT）。 規約には、属性、メトリクス名、スパン名、Span kind、計測単位などが含まれますが、これらに限定されません。
- 既存のメジャーバージョンにおいて、カテゴリー別の値をカンマ区切りで列挙するリストとして環境変数
OTEL_SEMCONV_STABILITY_OPT_INを導入すべきです（SHOULD） （例: http、databases、messaging）。値の一覧は次のとおりです。
messaging- 新しい安定版のメッセージング規約を発行し、それまで計装が発行していた古い実験的なメッセージング規約の発行を停止します。messaging/dup- 古い規約と安定版の規約の両方を発行し、円滑な移行を可能にします。- これらの値がいずれも指定されていない場合のデフォルトの動作は、その計装がそれまで発行していた古い実験的なメッセージング規約のバージョンをそのまま発行し続けることです。
- 注記: 両方の値が指定されている場合、
messaging/dupはmessagingよりも優先されます。- 両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持すべきです（SHOULD）。
- 次のメジャーバージョンでは、この環境変数を削除すべきです（SHOULD）。
- リストに
messaging/dupが含まれる場合、スパン名やSpan kindなど「単一の」値を持つ概念については、新しい安定版の値を発行すべきです（SHOULD）。
Kafkaスパン
Create span
Status:
Apache Kafkaへの送信のために作成されるメッセージを記述します。
「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。「Create」スパンは、それにリンクするクライアントの「Send」スパン（messaging.send.client）と組み合わせてのみ使用されます。「Send」スパン自体が作成コンテキストとして機能する場合は、代わりにプロデューサーの「Send」スパン（messaging.send.producer）を使用し、「Create」スパンは省略してください。詳細はProducer spansを参照してください。
Span kind は PRODUCER であるべきです（SHOULD）。
Span status は、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
messaging.operation.name |  | Required | string | メッセージング操作のシステム固有の名前。 | create |
messaging.system | | Required | string | クライアント計装によって識別されるメッセージングシステム。[1] | kafka |
error.type |  | Conditionally Required メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | UNKNOWN_TOPIC_OR_PARTITION; KAFKA_STORAGE_ERROR; NOT_ENOUGH_REPLICAS |
messaging.destination.name | | Conditionally Required [3] | string | メッセージの宛先名。[4] | MyTopic |
messaging.destination.template | | Conditionally Required [5] | string | メッセージング宛先名の低カーディナリティな表現。[6] | /customers/{customerId} |
messaging.kafka.message.tombstone | | Conditionally Required [7] | boolean | メッセージがトゥームストーンである場合にtrueとなるブール値。 | |
messaging.operation.type | | Conditionally Required 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[8] | create |
messaging.destination.partition.id | | Recommended 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。messaging.destination.name 内で一意です。 | 1 |
messaging.kafka.message.key | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | Kafkaにおけるメッセージキーは、同種のメッセージをグループ化し、同じパーティションで処理されるようにするために使用されます。messaging.message.id とは異なり、一意ではありません。キーが null の場合、この属性を設定してはなりません（MUST NOT）。[9] | myKey |
messaging.message.conversation_id | | Recommended | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | MyConversationId |
messaging.message.id | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | 452a7c7c7c7048c2f887f61572b18fc2 |
server.address | | Recommended | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[10] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Recommended | int | サーバーのポート番号。[11] | 80; 8080; 443 |
messaging.message.body.size | | Opt-In | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[12] | 1439 |
messaging.message.envelope.size | | Opt-In | int | メッセージ本文とメタデータのバイト数。[13] | 2738 |
[1] messaging.system: "kafka" に設定しなければなりません（MUST）。
[2] error.type: error.type は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。
error.type を型（例外の型など）に設定する場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。
記録されたエラー型が失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部エラーの型を使用してもかまいません（MAY）。例えばGoでは、%w を使って fmt.Errorf で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、アンラップされてもかまいません（MAY）。
計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。
1つの計装ライブラリ内での error.type のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には error.type が高カーディナリティになることを想定しておくべきです。
操作が正常に完了した場合、計装は error.type を設定するべきではありません（SHOULD NOT）。
特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。
- ドメイン固有の属性を使用する
- ドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように
error.typeを設定する
[3] messaging.destination.name: スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。
[4] messaging.destination.name: ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。
[5] messaging.destination.template: 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、messaging.destination.name をテンプレートとして使用してはなりません（MUST NOT）。
[6] messaging.destination.template: 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。
[7] messaging.kafka.message.tombstone: 値が true の場合。存在しない場合、値は false であるとみなされます。
[8] messaging.operation.type: create に設定すべきです（SHOULD）。
[9] messaging.kafka.message.key: キーの型が文字列でない場合、この属性にはその文字列表現を指定する必要があります。キーに一意で正規な文字列表現がない場合、その値を含めないでください。
[10] server.address: 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。
[11] server.port: クライアント側から観測し、かつ中継者を経由して通信している場合、server.port は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。
[12] messaging.message.body.size: これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
[13] messaging.message.envelope.size: これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）スパン作成時点で提供すべきです（SHOULD）。
messaging.destination.namemessaging.destination.partition.idmessaging.destination.templatemessaging.operation.namemessaging.operation.typemessaging.systemserver.addressserver.port
error.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | |
messaging.operation.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
create | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | |
process | 1つ以上のメッセージがConsumerによって処理されます。 | |
receive | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | |
send | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | |
settle | 1つ以上のメッセージが決済されます。 | |
messaging.system には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Send span (producer)
Status:
Producerが1つ以上のメッセージをApache Kafkaに送信することを記述します。
個別の「Create」スパンが存在せず、「Send」スパンのコンテキストがメッセージへの作成コンテキストとして注入される場合に、このスパンを使用します。詳細はProducer spansを参照してください。
Span kind は PRODUCER であるべきです（SHOULD）。
Span status は、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | Required | string | メッセージング操作のシステム固有の名前。 | send; publish |
messaging.system | | Required | string | クライアント計装によって識別されるメッセージングシステム。[1] | kafka |
error.type | | Conditionally Required メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | UNKNOWN_TOPIC_OR_PARTITION; KAFKA_STORAGE_ERROR; NOT_ENOUGH_REPLICAS |
messaging.batch.message_count | | Conditionally Required [3] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[4] | 0; 1; 2 |
messaging.destination.name | | Conditionally Required [5] | string | メッセージの宛先名。[6] | MyTopic |
messaging.destination.template | | Conditionally Required [7] | string | メッセージング宛先名の低カーディナリティな表現。[8] | /customers/{customerId} |
messaging.kafka.message.tombstone | | Conditionally Required [9] | boolean | メッセージがトゥームストーンである場合にtrueとなるブール値。 | |
messaging.operation.type | | Conditionally Required 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | send |
messaging.client.id | | Recommended | string | メッセージを消費または生成するクライアントの一意な識別子。 | client-5; myhost@8742@s8083jm |
messaging.destination.partition.id | | Recommended 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。messaging.destination.name 内で一意です。 | 1 |
messaging.kafka.cluster.id | | Recommended | string | Kafkaクライアント（またはAdminClient）APIを通じて公開されるブローカーのメタデータから取得されるKafkaクラスターID。[11] | MkU3OEVBNTcwNTJENDM2Qk |
messaging.kafka.message.key | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | Kafkaにおけるメッセージキーは、同種のメッセージをグループ化し、同じパーティションで処理されるようにするために使用されます。messaging.message.id とは異なり、一意ではありません。キーが null の場合、この属性を設定してはなりません（MUST NOT）。[12] | myKey |
messaging.kafka.offset | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | int | 対応するKafkaパーティションにおけるレコードのオフセット。 | 42 |
messaging.message.conversation_id | | Recommended | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | MyConversationId |
messaging.message.id | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | 452a7c7c7c7048c2f887f61572b18fc2 |
network.peer.address | | Recommended このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[13] | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended network.peer.address が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | 65123 |
server.address | | Recommended | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[14] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Recommended | int | サーバーのポート番号。[15] | 80; 8080; 443 |
messaging.message.body.size | | Opt-In | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[16] | 1439 |
messaging.message.envelope.size | | Opt-In | int | メッセージ本文とメタデータのバイト数。[17] | 2738 |
[1] messaging.system: "kafka" に設定しなければなりません（MUST）。
[2] error.type: error.type は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。
error.type を型（例外の型など）に設定する場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。
記録されたエラー型が失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部エラーの型を使用してもかまいません（MAY）。例えばGoでは、%w を使って fmt.Errorf で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、アンラップされてもかまいません（MAY）。
計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。
1つの計装ライブラリ内での error.type のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には error.type が高カーディナリティになることを想定しておくべきです。
操作が正常に完了した場合、計装は error.type を設定するべきではありません（SHOULD NOT）。
特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。
- ドメイン固有の属性を使用する
- ドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように
error.typeを設定する
[3] messaging.batch.message_count: スパンがメッセージのバッチに対する操作を記述する場合。
[4] messaging.batch.message_count: 計装は、単一のメッセージを操作するスパンに messaging.batch.message_count を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには messaging.batch.message_count を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。
[5] messaging.destination.name: スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。
[6] messaging.destination.name: ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。
[7] messaging.destination.template: 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、messaging.destination.name をテンプレートとして使用してはなりません（MUST NOT）。
[8] messaging.destination.template: 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。
[9] messaging.kafka.message.tombstone: 値が true の場合。存在しない場合、値は false であるとみなされます。
[10] messaging.operation.type: send に設定すべきです（SHOULD）。
[11] messaging.kafka.cluster.id: クラスターIDはKafkaブローカーが報告する一意な識別子です。クライアントが接続するように設定されている個々のブローカーとは独立にクラスターを識別し、ブローカーのホスト名、IPアドレス、ポートが変わっても安定して同じ値を保ちます。
[12] messaging.kafka.message.key: キーの型が文字列でない場合、この属性にはその文字列表現を指定する必要があります。キーに一意で正規な文字列表現がない場合、その値を含めないでください。
[13] network.peer.address: 個々のメッセージングシステムに関するセマンティック規約は、network.peer.* 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。
[14] server.address: 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。
[15] server.port: クライアント側から観測し、かつ中継者を経由して通信している場合、server.port は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。
[16] messaging.message.body.size: これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
[17] messaging.message.envelope.size: これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）スパン作成時点で提供すべきです（SHOULD）。
messaging.destination.namemessaging.destination.partition.idmessaging.destination.templatemessaging.operation.namemessaging.operation.typemessaging.systemserver.addressserver.port
error.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | |
messaging.operation.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
create | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | |
process | 1つ以上のメッセージがConsumerによって処理されます。 | |
receive | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | |
send | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | |
settle | 1つ以上のメッセージが決済されます。 | |
messaging.system には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Send span (client)
Status:
Producerが1つ以上のメッセージをApache Kafkaに送信することを記述します。
メッセージに対して「Create」スパン（またはカスタムの作成コンテキスト）が既に存在する場合に、このスパンを使用します。「Send」スパンは転送操作のみを記述し、メッセージに注入された作成コンテキストにリンクします。詳細はProducer spansを参照してください。
Span kind は CLIENT であるべきです（SHOULD）。
Span status は、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | Required | string | メッセージング操作のシステム固有の名前。 | send; publish |
messaging.system | | Required | string | クライアント計装によって識別されるメッセージングシステム。[1] | kafka |
error.type | | Conditionally Required メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | UNKNOWN_TOPIC_OR_PARTITION; KAFKA_STORAGE_ERROR; NOT_ENOUGH_REPLICAS |
messaging.batch.message_count | | Conditionally Required [3] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[4] | 0; 1; 2 |
messaging.destination.name | | Conditionally Required [5] | string | メッセージの宛先名。[6] | MyTopic |
messaging.destination.template | | Conditionally Required [7] | string | メッセージング宛先名の低カーディナリティな表現。[8] | /customers/{customerId} |
messaging.kafka.message.tombstone | | Conditionally Required [9] | boolean | メッセージがトゥームストーンである場合にtrueとなるブール値。 | |
messaging.operation.type | | Conditionally Required 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | send |
messaging.client.id | | Recommended | string | メッセージを消費または生成するクライアントの一意な識別子。 | client-5; myhost@8742@s8083jm |
messaging.destination.partition.id | | Recommended 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。messaging.destination.name 内で一意です。 | 1 |
messaging.kafka.cluster.id | | Recommended | string | Kafkaクライアント（またはAdminClient）APIを通じて公開されるブローカーのメタデータから取得されるKafkaクラスターID。[11] | MkU3OEVBNTcwNTJENDM2Qk |
messaging.kafka.message.key | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | Kafkaにおけるメッセージキーは、同種のメッセージをグループ化し、同じパーティションで処理されるようにするために使用されます。messaging.message.id とは異なり、一意ではありません。キーが null の場合、この属性を設定してはなりません（MUST NOT）。[12] | myKey |
messaging.kafka.offset | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | int | 対応するKafkaパーティションにおけるレコードのオフセット。 | 42 |
messaging.message.conversation_id | | Recommended | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | MyConversationId |
messaging.message.id | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | 452a7c7c7c7048c2f887f61572b18fc2 |
network.peer.address | | Recommended このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[13] | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended network.peer.address が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | 65123 |
server.address | | Recommended | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[14] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Recommended | int | サーバーのポート番号。[15] | 80; 8080; 443 |
messaging.message.body.size | | Opt-In | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[16] | 1439 |
messaging.message.envelope.size | | Opt-In | int | メッセージ本文とメタデータのバイト数。[17] | 2738 |
[1] messaging.system: "kafka" に設定しなければなりません（MUST）。
[2] error.type: error.type は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。
error.type を型（例外の型など）に設定する場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。
記録されたエラー型が失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部エラーの型を使用してもかまいません（MAY）。例えばGoでは、%w を使って fmt.Errorf で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、アンラップされてもかまいません（MAY）。
計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。
1つの計装ライブラリ内での error.type のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には error.type が高カーディナリティになることを想定しておくべきです。
操作が正常に完了した場合、計装は error.type を設定するべきではありません（SHOULD NOT）。
特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。
- ドメイン固有の属性を使用する
- ドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように
error.typeを設定する
[3] messaging.batch.message_count: スパンがメッセージのバッチに対する操作を記述する場合。
[4] messaging.batch.message_count: 計装は、単一のメッセージを操作するスパンに messaging.batch.message_count を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには messaging.batch.message_count を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。
[5] messaging.destination.name: スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。
[6] messaging.destination.name: ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。
[7] messaging.destination.template: 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、messaging.destination.name をテンプレートとして使用してはなりません（MUST NOT）。
[8] messaging.destination.template: 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。
[9] messaging.kafka.message.tombstone: 値が true の場合。存在しない場合、値は false であるとみなされます。
[10] messaging.operation.type: send に設定すべきです（SHOULD）。
[11] messaging.kafka.cluster.id: クラスターIDはKafkaブローカーが報告する一意な識別子です。クライアントが接続するように設定されている個々のブローカーとは独立にクラスターを識別し、ブローカーのホスト名、IPアドレス、ポートが変わっても安定して同じ値を保ちます。
[12] messaging.kafka.message.key: キーの型が文字列でない場合、この属性にはその文字列表現を指定する必要があります。キーに一意で正規な文字列表現がない場合、その値を含めないでください。
[13] network.peer.address: 個々のメッセージングシステムに関するセマンティック規約は、network.peer.* 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。
[14] server.address: 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。
[15] server.port: クライアント側から観測し、かつ中継者を経由して通信している場合、server.port は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。
[16] messaging.message.body.size: これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
[17] messaging.message.envelope.size: これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）スパン作成時点で提供すべきです（SHOULD）。
messaging.destination.namemessaging.destination.partition.idmessaging.destination.templatemessaging.operation.namemessaging.operation.typemessaging.systemserver.addressserver.port
error.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | |
messaging.operation.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
create | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | |
process | 1つ以上のメッセージがConsumerによって処理されます。 | |
receive | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | |
send | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | |
settle | 1つ以上のメッセージが決済されます。 | |
messaging.system には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Receive span
Status:
Consumerが1つ以上のメッセージをApache Kafkaから受信すること（pullベース）を記述します。
「Receive」スパンはpullベースのシナリオで作成されます。この場合、Consumerはメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。詳細はConsumer spansを参照してください。
Span kind は CLIENT であるべきです（SHOULD）。
Span status は、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | Required | string | メッセージング操作のシステム固有の名前。 | receive; poll |
messaging.system | | Required | string | クライアント計装によって識別されるメッセージングシステム。[1] | kafka |
error.type | | Conditionally Required メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | UNKNOWN_TOPIC_OR_PARTITION; KAFKA_STORAGE_ERROR; NOT_ENOUGH_REPLICAS |
messaging.batch.message_count | | Conditionally Required [3] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[4] | 0; 1; 2 |
messaging.consumer.group.name | | Conditionally Required 該当する場合。 | string | KafkaのコンシューマーグループID。 | my-group; indexer |
messaging.destination.name | | Conditionally Required [5] | string | メッセージの宛先名。[6] | MyTopic |
messaging.destination.template | | Conditionally Required [7] | string | メッセージング宛先名の低カーディナリティな表現。[8] | /customers/{customerId} |
messaging.kafka.message.tombstone | | Conditionally Required [9] | boolean | メッセージがトゥームストーンである場合にtrueとなるブール値。 | |
messaging.operation.type | | Conditionally Required 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | receive |
messaging.client.id | | Recommended | string | メッセージを消費または生成するクライアントの一意な識別子。 | client-5; myhost@8742@s8083jm |
messaging.destination.partition.id | | Recommended 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。messaging.destination.name 内で一意です。 | 1 |
messaging.kafka.cluster.id | | Recommended | string | Kafkaクライアント（またはAdminClient）APIを通じて公開されるブローカーのメタデータから取得されるKafkaクラスターID。[11] | MkU3OEVBNTcwNTJENDM2Qk |
messaging.kafka.message.key | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | Kafkaにおけるメッセージキーは、同種のメッセージをグループ化し、同じパーティションで処理されるようにするために使用されます。messaging.message.id とは異なり、一意ではありません。キーが null の場合、この属性を設定してはなりません（MUST NOT）。[12] | myKey |
messaging.kafka.offset | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | int | 対応するKafkaパーティションにおけるレコードのオフセット。 | 42 |
messaging.message.conversation_id | | Recommended | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | MyConversationId |
messaging.message.id | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | 452a7c7c7c7048c2f887f61572b18fc2 |
network.peer.address | | Recommended このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[13] | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended network.peer.address が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | 65123 |
server.address | | Recommended | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[14] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Recommended | int | サーバーのポート番号。[15] | 80; 8080; 443 |
messaging.message.body.size | | Opt-In | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[16] | 1439 |
messaging.message.envelope.size | | Opt-In | int | メッセージ本文とメタデータのバイト数。[17] | 2738 |
[1] messaging.system: "kafka" に設定しなければなりません（MUST）。
[2] error.type: error.type は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。
error.type を型（例外の型など）に設定する場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。
記録されたエラー型が失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部エラーの型を使用してもかまいません（MAY）。例えばGoでは、%w を使って fmt.Errorf で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、アンラップされてもかまいません（MAY）。
計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。
1つの計装ライブラリ内での error.type のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には error.type が高カーディナリティになることを想定しておくべきです。
操作が正常に完了した場合、計装は error.type を設定するべきではありません（SHOULD NOT）。
特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。
- ドメイン固有の属性を使用する
- ドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように
error.typeを設定する
[3] messaging.batch.message_count: スパンがメッセージのバッチに対する操作を記述する場合。
[4] messaging.batch.message_count: 計装は、単一のメッセージを操作するスパンに messaging.batch.message_count を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには messaging.batch.message_count を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。
[5] messaging.destination.name: スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。
[6] messaging.destination.name: ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。
[7] messaging.destination.template: 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、messaging.destination.name をテンプレートとして使用してはなりません（MUST NOT）。
[8] messaging.destination.template: 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。
[9] messaging.kafka.message.tombstone: 値が true の場合。存在しない場合、値は false であるとみなされます。
[10] messaging.operation.type: receive に設定すべきです（SHOULD）。
[11] messaging.kafka.cluster.id: クラスターIDはKafkaブローカーが報告する一意な識別子です。クライアントが接続するように設定されている個々のブローカーとは独立にクラスターを識別し、ブローカーのホスト名、IPアドレス、ポートが変わっても安定して同じ値を保ちます。
[12] messaging.kafka.message.key: キーの型が文字列でない場合、この属性にはその文字列表現を指定する必要があります。キーに一意で正規な文字列表現がない場合、その値を含めないでください。
[13] network.peer.address: 個々のメッセージングシステムに関するセマンティック規約は、network.peer.* 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。
[14] server.address: 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。
[15] server.port: クライアント側から観測し、かつ中継者を経由して通信している場合、server.port は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。
[16] messaging.message.body.size: これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
[17] messaging.message.envelope.size: これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）スパン作成時点で提供すべきです（SHOULD）。
messaging.consumer.group.namemessaging.destination.namemessaging.destination.partition.idmessaging.destination.templatemessaging.operation.namemessaging.operation.typemessaging.systemserver.addressserver.port
error.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | |
messaging.operation.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
create | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | |
process | 1つ以上のメッセージがConsumerによって処理されます。 | |
receive | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | |
send | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | |
settle | 1つ以上のメッセージが決済されます。 | |
messaging.system には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Process span
Status:
Consumerが1つ以上のメッセージをApache Kafkaから処理すること（pushベース）を記述します。
「Process」スパンはpushベースのシナリオで作成されます。この場合、メッセージはコールバックやハンドラーを通じてアプリケーションに渡されます。詳細はConsumer spansを参照してください。
単一メッセージのシナリオに限り、メッセージの作成コンテキストが親として使用される場合については、Message creation context as parent of “Process” spanを参照してください。
Span kind は CONSUMER であるべきです（SHOULD）。
Span status は、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | Required | string | メッセージング操作のシステム固有の名前。 | process; consume |
messaging.system | | Required | string | クライアント計装によって識別されるメッセージングシステム。[1] | kafka |
error.type | | Conditionally Required メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | UNKNOWN_TOPIC_OR_PARTITION; KAFKA_STORAGE_ERROR; NOT_ENOUGH_REPLICAS |
messaging.batch.message_count | | Conditionally Required [3] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[4] | 0; 1; 2 |
messaging.consumer.group.name | | Conditionally Required 該当する場合。 | string | KafkaのコンシューマーグループID。 | my-group; indexer |
messaging.destination.name | | Conditionally Required [5] | string | メッセージの宛先名。[6] | MyTopic |
messaging.destination.template | | Conditionally Required [7] | string | メッセージング宛先名の低カーディナリティな表現。[8] | /customers/{customerId} |
messaging.kafka.message.tombstone | | Conditionally Required [9] | boolean | メッセージがトゥームストーンである場合にtrueとなるブール値。 | |
messaging.operation.type | | Conditionally Required 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | process |
messaging.client.id | | Recommended | string | メッセージを消費または生成するクライアントの一意な識別子。 | client-5; myhost@8742@s8083jm |
messaging.destination.partition.id | | Recommended | string | メッセージ（またはバッチ）が受信されたパーティションIDの文字列表現。 | 1 |
messaging.kafka.cluster.id | | Recommended | string | Kafkaクライアント（またはAdminClient）APIを通じて公開されるブローカーのメタデータから取得されるKafkaクラスターID。[11] | MkU3OEVBNTcwNTJENDM2Qk |
messaging.kafka.message.key | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | Kafkaにおけるメッセージキーは、同種のメッセージをグループ化し、同じパーティションで処理されるようにするために使用されます。messaging.message.id とは異なり、一意ではありません。キーが null の場合、この属性を設定してはなりません（MUST NOT）。[12] | myKey |
messaging.kafka.offset | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | int | 対応するKafkaパーティションにおけるレコードのオフセット。 | 42 |
messaging.message.conversation_id | | Recommended | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | MyConversationId |
messaging.message.id | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | 452a7c7c7c7048c2f887f61572b18fc2 |
server.address | | Recommended | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[13] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Recommended | int | サーバーのポート番号。[14] | 80; 8080; 443 |
messaging.message.body.size | | Opt-In | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[15] | 1439 |
messaging.message.envelope.size | | Opt-In | int | メッセージ本文とメタデータのバイト数。[16] | 2738 |
[1] messaging.system: "kafka" に設定しなければなりません（MUST）。
[2] error.type: error.type は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。
error.type を型（例外の型など）に設定する場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。
記録されたエラー型が失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部エラーの型を使用してもかまいません（MAY）。例えばGoでは、%w を使って fmt.Errorf で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、アンラップされてもかまいません（MAY）。
計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。
1つの計装ライブラリ内での error.type のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には error.type が高カーディナリティになることを想定しておくべきです。
操作が正常に完了した場合、計装は error.type を設定するべきではありません（SHOULD NOT）。
特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。
- ドメイン固有の属性を使用する
- ドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように
error.typeを設定する
[3] messaging.batch.message_count: スパンがメッセージのバッチに対する操作を記述する場合。
[4] messaging.batch.message_count: 計装は、単一のメッセージを操作するスパンに messaging.batch.message_count を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには messaging.batch.message_count を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。
[5] messaging.destination.name: スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。
[6] messaging.destination.name: ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。
[7] messaging.destination.template: 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、messaging.destination.name をテンプレートとして使用してはなりません（MUST NOT）。
[8] messaging.destination.template: 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。
[9] messaging.kafka.message.tombstone: 値が true の場合。存在しない場合、値は false であるとみなされます。
[10] messaging.operation.type: process に設定すべきです（SHOULD）。
[11] messaging.kafka.cluster.id: クラスターIDはKafkaブローカーが報告する一意な識別子です。クライアントが接続するように設定されている個々のブローカーとは独立にクラスターを識別し、ブローカーのホスト名、IPアドレス、ポートが変わっても安定して同じ値を保ちます。
[12] messaging.kafka.message.key: キーの型が文字列でない場合、この属性にはその文字列表現を指定する必要があります。キーに一意で正規な文字列表現がない場合、その値を含めないでください。
[13] server.address: 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。
[14] server.port: クライアント側から観測し、かつ中継者を経由して通信している場合、server.port は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。
[15] messaging.message.body.size: これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
[16] messaging.message.envelope.size: これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。
次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）スパン作成時点で提供すべきです（SHOULD）。
messaging.consumer.group.namemessaging.destination.namemessaging.destination.partition.idmessaging.destination.templatemessaging.operation.namemessaging.operation.typemessaging.systemserver.addressserver.port
error.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | |
messaging.operation.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
create | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | |
process | 1つ以上のメッセージがConsumerによって処理されます。 | |
receive | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | |
send | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | |
settle | 1つ以上のメッセージが決済されます。 | |
messaging.system には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Settle span
Status:
Consumerが1つ以上のメッセージのオフセットをコミットする（決済する）ことをApache Kafkaにおいて記述します。
「Settle」スパンは、手動または自動でトリガーされるすべての決済操作について作成されます。詳細はConsumer spansを参照してください。
Span kind は CLIENT であるべきです（SHOULD）。
Span status は、エラーの記録の文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | Required | string | メッセージング操作のシステム固有の名前。 | ack; nack; settle |
messaging.system | | Required | string | クライアント計装によって識別されるメッセージングシステム。[1] | kafka |
error.type | | Conditionally Required メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | UNKNOWN_TOPIC_OR_PARTITION; KAFKA_STORAGE_ERROR; NOT_ENOUGH_REPLICAS |
messaging.batch.message_count | | Conditionally Required [3] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[4] | 0; 1; 2 |
messaging.consumer.group.name | | Conditionally Required 該当する場合。 | string | KafkaのコンシューマーグループID。 | my-group; indexer |
messaging.destination.name | | Conditionally Required [5] | string | メッセージの宛先名。[6] | MyTopic |
messaging.destination.template | | Conditionally Required [7] | string | メッセージング宛先名の低カーディナリティな表現。[8] | /customers/{customerId} |
messaging.operation.type | | Conditionally Required 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[9] | settle |
messaging.client.id | | Recommended | string | メッセージを消費または生成するクライアントの一意な識別子。 | client-5; myhost@8742@s8083jm |
messaging.destination.partition.id | | Recommended 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。messaging.destination.name 内で一意です。 | 1 |
messaging.kafka.cluster.id | | Recommended | string | Kafkaクライアント（またはAdminClient）APIを通じて公開されるブローカーのメタデータから取得されるKafkaクラスターID。[10] | MkU3OEVBNTcwNTJENDM2Qk |
messaging.kafka.offset | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | int | 対応するKafkaパーティションにおけるレコードのオフセット。 | 42 |
messaging.message.conversation_id | | Recommended | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | MyConversationId |
messaging.message.id | | Recommended スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | 452a7c7c7c7048c2f887f61572b18fc2 |
network.peer.address | | Recommended このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[11] | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended network.peer.address が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | 65123 |
server.address | | Recommended | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[12] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Recommended | int | サーバーのポート番号。[13] | 80; 8080; 443 |
[1] messaging.system: "kafka" に設定しなければなりません（MUST）。
[2] error.type: error.type は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。
error.type を型（例外の型など）に設定する場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。
記録されたエラー型が失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部エラーの型を使用してもかまいません（MAY）。例えばGoでは、%w を使って fmt.Errorf で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、アンラップされてもかまいません（MAY）。
計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。
1つの計装ライブラリ内での error.type のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には error.type が高カーディナリティになることを想定しておくべきです。
操作が正常に完了した場合、計装は error.type を設定するべきではありません（SHOULD NOT）。
特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。
- ドメイン固有の属性を使用する
- ドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように
error.typeを設定する
[3] messaging.batch.message_count: スパンがメッセージのバッチに対する操作を記述する場合。
[4] messaging.batch.message_count: 計装は、単一のメッセージを操作するスパンに messaging.batch.message_count を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには messaging.batch.message_count を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。
[5] messaging.destination.name: スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。
[6] messaging.destination.name: ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。
[7] messaging.destination.template: 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、messaging.destination.name をテンプレートとして使用してはなりません（MUST NOT）。
[8] messaging.destination.template: 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。
[9] messaging.operation.type: settle に設定すべきです（SHOULD）。
[10] messaging.kafka.cluster.id: クラスターIDはKafkaブローカーが報告する一意な識別子です。クライアントが接続するように設定されている個々のブローカーとは独立にクラスターを識別し、ブローカーのホスト名、IPアドレス、ポートが変わっても安定して同じ値を保ちます。
[11] network.peer.address: 個々のメッセージングシステムに関するセマンティック規約は、network.peer.* 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。
[12] server.address: 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。
[13] server.port: クライアント側から観測し、かつ中継者を経由して通信している場合、server.port は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。
次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）スパン作成時点で提供すべきです（SHOULD）。
messaging.consumer.group.namemessaging.destination.namemessaging.destination.partition.idmessaging.destination.templatemessaging.operation.namemessaging.operation.typemessaging.systemserver.addressserver.port
error.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | |
messaging.operation.type には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
create | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | |
process | 1つ以上のメッセージがConsumerによって処理されます。 | |
receive | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | |
send | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | |
settle | 1つ以上のメッセージが決済されます。 | |
messaging.system には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Apache KafkaのProducerでは、peer.serviceを、メッセージの送信先となるブローカーまたはサービスの名前に設定すべきです（SHOULD）。メッセージが別のサービスに直接渡される場合、ConsumerのResourceの service.name は、Producerの peer.service と一致すべきです（SHOULD）。中継ブローカーが存在する場合、service.name と peer.service は同じ値にはなりません。
messaging.client.id は、個々のインスタンスごとに一意な、ConsumerまたはProducerのクライアント名に設定すべきです（SHOULD）。
例
QuarkusまたはSpring Bootを使ったApache Kafkaの例
この例では、ProducerがApache Kafka上のトピックTにメッセージを発行します。Consumerはそのメッセージを受信し、処理してオフセットをコミットします。
QuarkusやSpring Bootなどのフレームワークは、処理用コールバックを設定・計装できるKafkaとの統合を提供しています。そのため、対応する計装は、ポーリング呼び出し用にKafka計装が作成する「Receive」スパンに加えて、「Process」スパンも作成すべきです（SHOULD）。
flowchart LR;
subgraph PRODUCER
P[Span Send]
end
subgraph CONSUMER
direction TB
R1[Span Poll]
R2[Span Process]
R3[Span Commit]
end
P-. link .-R1;
P-. link .-R2;
R2-- parent ---R3;
classDef normal fill:green
class P,R1,R2,R3 normal
linkStyle 0 color:green,stroke:green
linkStyle 1 color:green,stroke:green
| フィールドまたは属性 | Producer | Consumer Span Poll | Consumer Span Process | Consumer Span Commit T |
|---|---|---|---|---|
| Span name | "send T" | "poll T" | "process T" | "commit T" |
| 親 | (省略可) Span Send | Span Process | ||
| リンク | Span Send | Span Send | ||
| SpanKind | PRODUCER | CLIENT | CONSUMER | CLIENT |
| ステータス | UNSET | UNSET | UNSET | UNSET |
messaging.system | "kafka" | "kafka" | "kafka" | "kafka" |
messaging.destination.name | "T" | "T" | "T" | "T" |
messaging.consumer.group.name | "my-group" | "my-group" | "my-group" | |
messaging.destination.partition.id | "1" | "1" | "1" | "1" |
messaging.operation.name | "send" | "poll" | "process" | "commit" |
messaging.operation.type | "send" | "receive" | "process" | "settle" |
messaging.client.id | "5" | "8" | "8" | "8" |
messaging.kafka.cluster.id | "MkU3OEVBNTcwNTJENDM2Qk" | "MkU3OEVBNTcwNTJENDM2Qk" | "MkU3OEVBNTcwNTJENDM2Qk" | "MkU3OEVBNTcwNTJENDM2Qk" |
messaging.kafka.message.key | "myKey" | "myKey" | "myKey" | |
messaging.kafka.offset | "12" | "12" | "12" |