> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/messaging/gcp-pubsub/


# Google Cloud Pub/Subに関するセマンティック規約

**ステータス**: [Development][DocumentStatus]

[Google Cloud Pub/Sub](https://cloud.google.com/pubsub)に関するセマンティック規約は、[メッセージングに関するセマンティック規約](/works/otel-specs-ja/semconv/messaging/)を拡張し、上書きします。

> [!IMPORTANT]
>
> [この文書のv1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-spans.md)
> 以前のバージョンを使っている既存のメッセージング計装は、次に従うべきです。
>
> * メッセージングセマンティック規約が安定版として宣言されるまで、デフォルトで発行するメッセージング規約のバージョンを変更してはなりません（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）。

## Google Cloud Pub/Subスパン

### Create span

<!-- semconv span.messaging.gcp_pubsub.create.producer -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Google Cloud Pub/Subへの発行のために作成されるメッセージを記述します。

「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。「Create」スパンは、それにリンクするクライアントの「Send」スパン（`messaging.send.client`）と組み合わせてのみ使用されます。「Send」スパン自体が作成コンテキストとして機能する場合は、代わりにプロデューサーの「Send」スパン（`messaging.send.producer`）を使用し、「Create」スパンは省略してください。詳細は[Producer spans](/works/otel-specs-ja/semconv/messaging/messaging-spans/#producer-spans)を参照してください。

**Span kind** は `PRODUCER` であるべきです（SHOULD）。

**Span status** は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | メッセージング操作のシステム固有の名前。[1] | `create` |
| [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | クライアント計装によって識別されるメッセージングシステム。[2] | `gcp_pubsub` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `NOT_FOUND`; `RESOURCE_EXHAUSTED`; `UNAVAILABLE` |
| [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | string | メッセージの宛先名。[5] | `MyTopic` |
| [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | メッセージング宛先名の低カーディナリティな表現。[7] | `/customers/{customerId}` |
| [`messaging.gcp_pubsub.message.ordering_key`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` メッセージ種別に順序付けキーが設定されている場合。 | string | 与えられたメッセージの順序付けキー。この属性が存在しない場合、メッセージには順序付けキーがありません。 | `ordering_key` |
| [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[8] | `create` |
| [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。`messaging.destination.name` 内で一意です。 | `1` |
| [`messaging.message.conversation_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | `MyConversationId` |
| [`messaging.message.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | `452a7c7c7c7048c2f887f61572b18fc2` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | サーバーのポート番号。[10] | `80`; `8080`; `443` |
| [`messaging.message.body.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[11] | `1439` |
| [`messaging.message.envelope.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文とメタデータのバイト数。[12] | `2738` |

**[1] `messaging.operation.name`:** `create` に設定すべきです（SHOULD）。

**[2] `messaging.system`:** `"gcp_pubsub"` に設定しなければなりません（MUST）。

**[3] `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` を設定する

**[4] `messaging.destination.name`:** スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。

**[5] `messaging.destination.name`:** ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。

**[6] `messaging.destination.template`:** 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、`messaging.destination.name` をテンプレートとして使用してはなりません（MUST NOT）。

**[7] `messaging.destination.template`:** 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。

**[8] `messaging.operation.type`:** `create` に設定すべきです（SHOULD）。

**[9] `server.address`:** 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。

**[10] `server.port`:** クライアント側から観測し、かつ中継者を経由して通信している場合、`server.port` は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[11] `messaging.message.body.size`:** これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

**[12] `messaging.message.envelope.size`:** これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）**スパン作成時点**で提供すべきです（SHOULD）。

* [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`messaging.operation.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `create` | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `process` | 1つ以上のメッセージがConsumerによって処理されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `receive` | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `send` | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `settle` | 1つ以上のメッセージが決済されます。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`messaging.system` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `activemq` | Apache ActiveMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws.sns` | Amazon Simple Notification Service (SNS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventgrid` | Azure Event Grid | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventhubs` | Azure Event Hubs | ![Development](https://img.shields.io/badge/-development-blue) |
| `gcp_pubsub` | Google Cloud Pub/Sub | ![Development](https://img.shields.io/badge/-development-blue) |
| `jms` | Java Message Service | ![Development](https://img.shields.io/badge/-development-blue) |
| `kafka` | Apache Kafka | ![Development](https://img.shields.io/badge/-development-blue) |
| `pulsar` | Apache Pulsar | ![Development](https://img.shields.io/badge/-development-blue) |
| `rabbitmq` | RabbitMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `rocketmq` | Apache RocketMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `servicebus` | Azure Service Bus | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- endsemconv -->

### Send span (producer)

<!-- semconv span.messaging.gcp_pubsub.send.producer -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Producerが1つ以上のメッセージをGoogle Cloud Pub/Subに発行することを記述します。

個別の「Create」スパンが存在せず、「Send」スパンのコンテキストがメッセージへの作成コンテキストとして注入される場合に、このスパンを使用します。詳細は[Producer spans](/works/otel-specs-ja/semconv/messaging/messaging-spans/#producer-spans)を参照してください。

**Span kind** は `PRODUCER` であるべきです（SHOULD）。

**Span status** は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | メッセージング操作のシステム固有の名前。[1] | `send` |
| [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | クライアント計装によって識別されるメッセージングシステム。[2] | `gcp_pubsub` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `NOT_FOUND`; `RESOURCE_EXHAUSTED`; `UNAVAILABLE` |
| [`messaging.batch.message_count`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[5] | `0`; `1`; `2` |
| [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | メッセージの宛先名。[7] | `MyTopic` |
| [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [8] | string | メッセージング宛先名の低カーディナリティな表現。[9] | `/customers/{customerId}` |
| [`messaging.gcp_pubsub.message.ordering_key`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` メッセージ種別に順序付けキーが設定されている場合。 | string | 与えられたメッセージの順序付けキー。この属性が存在しない場合、メッセージには順序付けキーがありません。 | `ordering_key` |
| [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | `send` |
| [`messaging.client.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージを消費または生成するクライアントの一意な識別子。 | `client-5`; `myhost@8742@s8083jm` |
| [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。`messaging.destination.name` 内で一意です。 | `1` |
| [`messaging.message.conversation_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | `MyConversationId` |
| [`messaging.message.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | `452a7c7c7c7048c2f887f61572b18fc2` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[11] | `10.1.2.80`; `/tmp/my.sock` |
| [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` `network.peer.address` が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | `65123` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | サーバーのポート番号。[13] | `80`; `8080`; `443` |
| [`messaging.message.body.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[14] | `1439` |
| [`messaging.message.envelope.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文とメタデータのバイト数。[15] | `2738` |

**[1] `messaging.operation.name`:** `send` に設定すべきです（SHOULD）。

**[2] `messaging.system`:** `"gcp_pubsub"` に設定しなければなりません（MUST）。

**[3] `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` を設定する

**[4] `messaging.batch.message_count`:** スパンがメッセージのバッチに対する操作を記述する場合。

**[5] `messaging.batch.message_count`:** 計装は、単一のメッセージを操作するスパンに `messaging.batch.message_count` を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには `messaging.batch.message_count` を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。

**[6] `messaging.destination.name`:** スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。

**[7] `messaging.destination.name`:** ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。

**[8] `messaging.destination.template`:** 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、`messaging.destination.name` をテンプレートとして使用してはなりません（MUST NOT）。

**[9] `messaging.destination.template`:** 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。

**[10] `messaging.operation.type`:** `send` に設定すべきです（SHOULD）。

**[11] `network.peer.address`:** 個々のメッセージングシステムに関するセマンティック規約は、`network.peer.*` 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。

**[12] `server.address`:** 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。

**[13] `server.port`:** クライアント側から観測し、かつ中継者を経由して通信している場合、`server.port` は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[14] `messaging.message.body.size`:** これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

**[15] `messaging.message.envelope.size`:** これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）**スパン作成時点**で提供すべきです（SHOULD）。

* [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`messaging.operation.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `create` | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `process` | 1つ以上のメッセージがConsumerによって処理されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `receive` | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `send` | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `settle` | 1つ以上のメッセージが決済されます。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`messaging.system` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `activemq` | Apache ActiveMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws.sns` | Amazon Simple Notification Service (SNS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventgrid` | Azure Event Grid | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventhubs` | Azure Event Hubs | ![Development](https://img.shields.io/badge/-development-blue) |
| `gcp_pubsub` | Google Cloud Pub/Sub | ![Development](https://img.shields.io/badge/-development-blue) |
| `jms` | Java Message Service | ![Development](https://img.shields.io/badge/-development-blue) |
| `kafka` | Apache Kafka | ![Development](https://img.shields.io/badge/-development-blue) |
| `pulsar` | Apache Pulsar | ![Development](https://img.shields.io/badge/-development-blue) |
| `rabbitmq` | RabbitMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `rocketmq` | Apache RocketMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `servicebus` | Azure Service Bus | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- endsemconv -->

### Send span (client)

<!-- semconv span.messaging.gcp_pubsub.send.client -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Producerが1つ以上のメッセージをGoogle Cloud Pub/Subに発行することを記述します。

メッセージに対して「Create」スパン（またはカスタムの作成コンテキスト）が既に存在する場合に、このスパンを使用します。「Send」スパンは転送操作のみを記述し、メッセージに注入された作成コンテキストにリンクします。詳細は[Producer spans](/works/otel-specs-ja/semconv/messaging/messaging-spans/#producer-spans)を参照してください。

**Span kind** は `CLIENT` であるべきです（SHOULD）。

**Span status** は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | メッセージング操作のシステム固有の名前。[1] | `send` |
| [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | クライアント計装によって識別されるメッセージングシステム。[2] | `gcp_pubsub` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `NOT_FOUND`; `RESOURCE_EXHAUSTED`; `UNAVAILABLE` |
| [`messaging.batch.message_count`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[5] | `0`; `1`; `2` |
| [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | メッセージの宛先名。[7] | `MyTopic` |
| [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [8] | string | メッセージング宛先名の低カーディナリティな表現。[9] | `/customers/{customerId}` |
| [`messaging.gcp_pubsub.message.ordering_key`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` メッセージ種別に順序付けキーが設定されている場合。 | string | 与えられたメッセージの順序付けキー。この属性が存在しない場合、メッセージには順序付けキーがありません。 | `ordering_key` |
| [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | `send` |
| [`messaging.client.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージを消費または生成するクライアントの一意な識別子。 | `client-5`; `myhost@8742@s8083jm` |
| [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。`messaging.destination.name` 内で一意です。 | `1` |
| [`messaging.message.conversation_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | `MyConversationId` |
| [`messaging.message.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | `452a7c7c7c7048c2f887f61572b18fc2` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[11] | `10.1.2.80`; `/tmp/my.sock` |
| [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` `network.peer.address` が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | `65123` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | サーバーのポート番号。[13] | `80`; `8080`; `443` |
| [`messaging.message.body.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[14] | `1439` |
| [`messaging.message.envelope.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文とメタデータのバイト数。[15] | `2738` |

**[1] `messaging.operation.name`:** `send` に設定すべきです（SHOULD）。

**[2] `messaging.system`:** `"gcp_pubsub"` に設定しなければなりません（MUST）。

**[3] `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` を設定する

**[4] `messaging.batch.message_count`:** スパンがメッセージのバッチに対する操作を記述する場合。

**[5] `messaging.batch.message_count`:** 計装は、単一のメッセージを操作するスパンに `messaging.batch.message_count` を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには `messaging.batch.message_count` を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。

**[6] `messaging.destination.name`:** スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。

**[7] `messaging.destination.name`:** ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。

**[8] `messaging.destination.template`:** 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、`messaging.destination.name` をテンプレートとして使用してはなりません（MUST NOT）。

**[9] `messaging.destination.template`:** 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。

**[10] `messaging.operation.type`:** `send` に設定すべきです（SHOULD）。

**[11] `network.peer.address`:** 個々のメッセージングシステムに関するセマンティック規約は、`network.peer.*` 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。

**[12] `server.address`:** 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。

**[13] `server.port`:** クライアント側から観測し、かつ中継者を経由して通信している場合、`server.port` は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[14] `messaging.message.body.size`:** これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

**[15] `messaging.message.envelope.size`:** これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）**スパン作成時点**で提供すべきです（SHOULD）。

* [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`messaging.operation.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `create` | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `process` | 1つ以上のメッセージがConsumerによって処理されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `receive` | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `send` | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `settle` | 1つ以上のメッセージが決済されます。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`messaging.system` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `activemq` | Apache ActiveMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws.sns` | Amazon Simple Notification Service (SNS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventgrid` | Azure Event Grid | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventhubs` | Azure Event Hubs | ![Development](https://img.shields.io/badge/-development-blue) |
| `gcp_pubsub` | Google Cloud Pub/Sub | ![Development](https://img.shields.io/badge/-development-blue) |
| `jms` | Java Message Service | ![Development](https://img.shields.io/badge/-development-blue) |
| `kafka` | Apache Kafka | ![Development](https://img.shields.io/badge/-development-blue) |
| `pulsar` | Apache Pulsar | ![Development](https://img.shields.io/badge/-development-blue) |
| `rabbitmq` | RabbitMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `rocketmq` | Apache RocketMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `servicebus` | Azure Service Bus | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- endsemconv -->

### Receive span

<!-- semconv span.messaging.gcp_pubsub.receive.client -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Consumerが1つ以上のメッセージをGoogle Cloud Pub/Subから受信すること（pullベース）を記述します。

「Receive」スパンはpullベースのシナリオで作成されます。この場合、Consumerはメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。詳細は[Consumer spans](/works/otel-specs-ja/semconv/messaging/messaging-spans/#consumer-spans)を参照してください。

**Span kind** は `CLIENT` であるべきです（SHOULD）。

**Span status** は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | メッセージング操作のシステム固有の名前。[1] | `receive` |
| [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | クライアント計装によって識別されるメッセージングシステム。[2] | `gcp_pubsub` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `NOT_FOUND`; `RESOURCE_EXHAUSTED`; `UNAVAILABLE` |
| [`messaging.batch.message_count`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[5] | `0`; `1`; `2` |
| [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | メッセージの宛先名。[7] | `MyTopic` |
| [`messaging.destination.subscription.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | Google Pub/Subの[サブスクリプション名](https://cloud.google.com/pubsub/docs/subscription-overview)。 | `subscription-a` |
| [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [8] | string | メッセージング宛先名の低カーディナリティな表現。[9] | `/customers/{customerId}` |
| [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | `receive` |
| [`messaging.client.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージを消費または生成するクライアントの一意な識別子。 | `client-5`; `myhost@8742@s8083jm` |
| [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。`messaging.destination.name` 内で一意です。 | `1` |
| [`messaging.gcp_pubsub.message.ack_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | 与えられたメッセージのack ID。 | `ack_id` |
| [`messaging.gcp_pubsub.message.delivery_attempt`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | 与えられたメッセージの配送試行回数。 | `2` |
| [`messaging.message.conversation_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | `MyConversationId` |
| [`messaging.message.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | `452a7c7c7c7048c2f887f61572b18fc2` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[11] | `10.1.2.80`; `/tmp/my.sock` |
| [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` `network.peer.address` が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | `65123` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | サーバーのポート番号。[13] | `80`; `8080`; `443` |
| [`messaging.message.body.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[14] | `1439` |
| [`messaging.message.envelope.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文とメタデータのバイト数。[15] | `2738` |

**[1] `messaging.operation.name`:** `receive` に設定すべきです（SHOULD）。

**[2] `messaging.system`:** `"gcp_pubsub"` に設定しなければなりません（MUST）。

**[3] `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` を設定する

**[4] `messaging.batch.message_count`:** スパンがメッセージのバッチに対する操作を記述する場合。

**[5] `messaging.batch.message_count`:** 計装は、単一のメッセージを操作するスパンに `messaging.batch.message_count` を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには `messaging.batch.message_count` を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。

**[6] `messaging.destination.name`:** スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。

**[7] `messaging.destination.name`:** ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。

**[8] `messaging.destination.template`:** 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、`messaging.destination.name` をテンプレートとして使用してはなりません（MUST NOT）。

**[9] `messaging.destination.template`:** 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。

**[10] `messaging.operation.type`:** `receive` に設定すべきです（SHOULD）。

**[11] `network.peer.address`:** 個々のメッセージングシステムに関するセマンティック規約は、`network.peer.*` 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。

**[12] `server.address`:** 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。

**[13] `server.port`:** クライアント側から観測し、かつ中継者を経由して通信している場合、`server.port` は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[14] `messaging.message.body.size`:** これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

**[15] `messaging.message.envelope.size`:** これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）**スパン作成時点**で提供すべきです（SHOULD）。

* [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.subscription.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`messaging.operation.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `create` | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `process` | 1つ以上のメッセージがConsumerによって処理されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `receive` | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `send` | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `settle` | 1つ以上のメッセージが決済されます。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`messaging.system` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `activemq` | Apache ActiveMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws.sns` | Amazon Simple Notification Service (SNS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventgrid` | Azure Event Grid | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventhubs` | Azure Event Hubs | ![Development](https://img.shields.io/badge/-development-blue) |
| `gcp_pubsub` | Google Cloud Pub/Sub | ![Development](https://img.shields.io/badge/-development-blue) |
| `jms` | Java Message Service | ![Development](https://img.shields.io/badge/-development-blue) |
| `kafka` | Apache Kafka | ![Development](https://img.shields.io/badge/-development-blue) |
| `pulsar` | Apache Pulsar | ![Development](https://img.shields.io/badge/-development-blue) |
| `rabbitmq` | RabbitMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `rocketmq` | Apache RocketMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `servicebus` | Azure Service Bus | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- endsemconv -->

### Process span

<!-- semconv span.messaging.gcp_pubsub.process.consumer -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Consumerが1つ以上のメッセージをGoogle Cloud Pub/Subから処理すること（pushベース）を記述します。

「Process」スパンはpushベースのシナリオで作成されます。この場合、メッセージはコールバックやハンドラーを通じてアプリケーションに渡されます。詳細は[Consumer spans](/works/otel-specs-ja/semconv/messaging/messaging-spans/#consumer-spans)を参照してください。

単一メッセージのシナリオに限り、メッセージの作成コンテキストが親として使用される場合については、[Message creation context as parent of "Process" span](/works/otel-specs-ja/semconv/messaging/messaging-spans/#message-creation-context-as-parent-of-process-span)を参照してください。

**Span kind** は `CONSUMER` であるべきです（SHOULD）。

**Span status** は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | メッセージング操作のシステム固有の名前。[1] | `subscribe` |
| [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | クライアント計装によって識別されるメッセージングシステム。[2] | `gcp_pubsub` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `NOT_FOUND`; `RESOURCE_EXHAUSTED`; `UNAVAILABLE` |
| [`messaging.batch.message_count`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[5] | `0`; `1`; `2` |
| [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | メッセージの宛先名。[7] | `MyTopic` |
| [`messaging.destination.subscription.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | Google Pub/Subの[サブスクリプション名](https://cloud.google.com/pubsub/docs/subscription-overview)。 | `subscription-a` |
| [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [8] | string | メッセージング宛先名の低カーディナリティな表現。[9] | `/customers/{customerId}` |
| [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | `process` |
| [`messaging.client.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージを消費または生成するクライアントの一意な識別子。 | `client-5`; `myhost@8742@s8083jm` |
| [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。`messaging.destination.name` 内で一意です。 | `1` |
| [`messaging.gcp_pubsub.message.ack_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | 与えられたメッセージのack ID。 | `ack_id` |
| [`messaging.gcp_pubsub.message.delivery_attempt`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | 与えられたメッセージの配送試行回数。 | `2` |
| [`messaging.message.conversation_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | `MyConversationId` |
| [`messaging.message.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | `452a7c7c7c7048c2f887f61572b18fc2` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | サーバーのポート番号。[12] | `80`; `8080`; `443` |
| [`messaging.message.body.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文のバイト数。単一メッセージ操作を記述するスパンにのみ適用されます。[13] | `1439` |
| [`messaging.message.envelope.size`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | int | メッセージ本文とメタデータのバイト数。[14] | `2738` |

**[1] `messaging.operation.name`:** `subscribe` に設定すべきです（SHOULD）。これはメッセージが受信された後から、確認応答（ack）、否定応答（nack）、または期限切れになるまでの時間を表します。

**[2] `messaging.system`:** `"gcp_pubsub"` に設定しなければなりません（MUST）。

**[3] `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` を設定する

**[4] `messaging.batch.message_count`:** スパンがメッセージのバッチに対する操作を記述する場合。

**[5] `messaging.batch.message_count`:** 計装は、単一のメッセージを操作するスパンに `messaging.batch.message_count` を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには `messaging.batch.message_count` を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。

**[6] `messaging.destination.name`:** スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。

**[7] `messaging.destination.name`:** ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。

**[8] `messaging.destination.template`:** 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、`messaging.destination.name` をテンプレートとして使用してはなりません（MUST NOT）。

**[9] `messaging.destination.template`:** 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。

**[10] `messaging.operation.type`:** `process` に設定すべきです（SHOULD）。

**[11] `server.address`:** 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。

**[12] `server.port`:** クライアント側から観測し、かつ中継者を経由して通信している場合、`server.port` は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

**[13] `messaging.message.body.size`:** これは圧縮後または圧縮前のいずれの本文サイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

**[14] `messaging.message.envelope.size`:** これは圧縮後または圧縮前のいずれのサイズも指す場合があります。両方のサイズが分かっている場合、圧縮前のサイズを使用すべきです（SHOULD）。

次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）**スパン作成時点**で提供すべきです（SHOULD）。

* [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.subscription.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`messaging.operation.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `create` | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `process` | 1つ以上のメッセージがConsumerによって処理されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `receive` | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `send` | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `settle` | 1つ以上のメッセージが決済されます。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`messaging.system` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `activemq` | Apache ActiveMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws.sns` | Amazon Simple Notification Service (SNS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventgrid` | Azure Event Grid | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventhubs` | Azure Event Hubs | ![Development](https://img.shields.io/badge/-development-blue) |
| `gcp_pubsub` | Google Cloud Pub/Sub | ![Development](https://img.shields.io/badge/-development-blue) |
| `jms` | Java Message Service | ![Development](https://img.shields.io/badge/-development-blue) |
| `kafka` | Apache Kafka | ![Development](https://img.shields.io/badge/-development-blue) |
| `pulsar` | Apache Pulsar | ![Development](https://img.shields.io/badge/-development-blue) |
| `rabbitmq` | RabbitMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `rocketmq` | Apache RocketMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `servicebus` | Azure Service Bus | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- endsemconv -->

### Settle span

<!-- semconv span.messaging.gcp_pubsub.settle.client -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

Google Cloud Pub/Subの1つ以上のメッセージを決済（ack/nack/modack）することを記述します。

「Settle」スパンは、手動または自動でトリガーされるすべての決済操作について作成されます。詳細は[Consumer spans](/works/otel-specs-ja/semconv/messaging/messaging-spans/#consumer-spans)を参照してください。

**Span kind** は `CLIENT` であるべきです（SHOULD）。

**Span status** は、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | メッセージング操作のシステム固有の名前。[1] | `ack`; `nack`; `modack` |
| [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | クライアント計装によって識別されるメッセージングシステム。[2] | `gcp_pubsub` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` メッセージング操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `NOT_FOUND`; `RESOURCE_EXHAUSTED`; `UNAVAILABLE` |
| [`messaging.batch.message_count`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [4] | int | バッチ操作のスコープ内で送信、受信、または処理されたメッセージの数。[5] | `0`; `1`; `2` |
| [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [6] | string | メッセージの宛先名。[7] | `MyTopic` |
| [`messaging.destination.subscription.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | Google Pub/Subの[サブスクリプション名](https://cloud.google.com/pubsub/docs/subscription-overview)。 | `subscription-a` |
| [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` [8] | string | メッセージング宛先名の低カーディナリティな表現。[9] | `/customers/{customerId}` |
| [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` 該当する場合。 | string | メッセージング操作の種類を識別する文字列。[10] | `settle` |
| [`messaging.client.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージを消費または生成するクライアントの一意な識別子。 | `client-5`; `myhost@8742@s8083jm` |
| [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` 該当する場合。 | string | メッセージが送信される、または受信されるパーティションの識別子。`messaging.destination.name` 内で一意です。 | `1` |
| [`messaging.gcp_pubsub.message.ack_deadline`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | ack期限変更リクエストに設定されたack期限（秒）。 | `10` |
| [`messaging.gcp_pubsub.message.ack_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | 与えられたメッセージのack ID。 | `ack_id` |
| [`messaging.gcp_pubsub.message.delivery_attempt`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | 与えられたメッセージの配送試行回数。 | `2` |
| [`messaging.message.conversation_id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メッセージが属する会話を識別する会話ID（文字列として表現）。「Correlation ID」と呼ばれることもあります。 | `MyConversationId` |
| [`messaging.message.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` スパンが単一メッセージに対する操作を記述する場合。 | string | メッセージングシステムがメッセージの識別子として使用する値（文字列として表現）。 | `452a7c7c7c7048c2f887f61572b18fc2` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` このメッセージングシステムに該当する場合。 | string | 操作が実行されたメッセージング中継ノードのピアアドレス。[11] | `10.1.2.80`; `/tmp/my.sock` |
| [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` `network.peer.address` が設定されている場合に限る。 | int | 操作が実行されたメッセージング中継ノードのピアポート。 | `65123` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | 利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | サーバーのポート番号。[13] | `80`; `8080`; `443` |

**[1] `messaging.operation.name`:** Google Cloud Pub/Subの決済に対しては、次のよく知られた値の一覧があります。
いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

- メッセージを確認応答（ack）または否定応答（nack）する場合は `ack` と `nack`
- 単一メッセージまたはメッセージのバッチのリースを延長する場合は `modack`

**[2] `messaging.system`:** `"gcp_pubsub"` に設定しなければなりません（MUST）。

**[3] `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` を設定する

**[4] `messaging.batch.message_count`:** スパンがメッセージのバッチに対する操作を記述する場合。

**[5] `messaging.batch.message_count`:** 計装は、単一のメッセージを操作するスパンに `messaging.batch.message_count` を設定するべきではありません（SHOULD NOT）。メッセージングクライアントライブラリが同じ操作についてバッチ用APIと単一メッセージ用APIの両方をサポートする場合、計装はバッチ用APIには `messaging.batch.message_count` を使用すべきであり（SHOULD）、単一メッセージ用APIには使用するべきではありません（SHOULD NOT）。

**[6] `messaging.destination.name`:** スパンが単一メッセージに対する操作を記述する場合、またはその値がバッチ内のすべてのメッセージに当てはまる場合。

**[7] `messaging.destination.name`:** ブローカー内の特定のキュー、トピック、その他のエンティティを一意に識別すべきです（SHOULD）。ブローカーにそのような概念がない場合、ブローカー自体を一意に識別すべきです（SHOULD）。

**[8] `messaging.destination.template`:** 利用可能な場合。計装は、宛先名の低カーディナリティが保証されない限り、`messaging.destination.name` をテンプレートとして使用してはなりません（MUST NOT）。

**[9] `messaging.destination.template`:** 宛先名はテンプレートから構築される場合があります。例えば、ユーザー名や製品IDを含む宛先名が考えられます。この場合、宛先名自体は高カーディナリティですが、その背後にあるテンプレートは低カーディナリティであり、グループ化や集計に効果的に使用できます。

**[10] `messaging.operation.type`:** `settle` に設定すべきです（SHOULD）。

**[11] `network.peer.address`:** 個々のメッセージングシステムに関するセマンティック規約は、`network.peer.*` 属性が適用可能かどうかを文書化すべきです（SHOULD）。ネットワークピアのアドレスとポートは、アプリケーションが個々の中継ノードと直接やり取りする場合に重要です。メッセージング操作が複数のネットワーク呼び出しを伴う場合（例えば再試行）、最後に接続したノードのアドレスを使用すべきです（SHOULD）。

**[12] `server.address`:** 利用可能であればリバースDNSルックアップなしのブローカーのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。

**[13] `server.port`:** クライアント側から観測し、かつ中継者を経由して通信している場合、`server.port` は、利用可能であれば、その中継者（例えばプロキシ）の背後にあるサーバーポートを表すべきです（SHOULD）。

次の属性は、サンプリング判断に重要となりうるため、（いずれかが提供される場合）**スパン作成時点**で提供すべきです（SHOULD）。

* [`messaging.destination.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.partition.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.subscription.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.destination.template`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.operation.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`messaging.system`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/messaging/)
* [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)
* [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/)

---

`error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |

---

`messaging.operation.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `create` | メッセージが作成されます。「Create」スパンは常に単一のメッセージを指し、バッチ送信シナリオにおいてメッセージに一意な作成コンテキストを提供するために使用されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `process` | 1つ以上のメッセージがConsumerによって処理されます。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `receive` | 1つ以上のメッセージがConsumerによって要求されます。この操作はpullベースのシナリオを指し、Consumerがメッセージを受信するためにメッセージングSDKのメソッドを明示的に呼び出します。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `send` | 1つ以上のメッセージが中継者への送信のために提供されます。単一のメッセージが送信される場合、「Send」スパンのコンテキストを作成コンテキストとして使用でき、「Create」スパンを作成する必要はありません。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `settle` | 1つ以上のメッセージが決済されます。 | ![Development](https://img.shields.io/badge/-development-blue) |

---

`messaging.system` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `activemq` | Apache ActiveMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws.sns` | Amazon Simple Notification Service (SNS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `aws_sqs` | Amazon Simple Queue Service (SQS) | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventgrid` | Azure Event Grid | ![Development](https://img.shields.io/badge/-development-blue) |
| `eventhubs` | Azure Event Hubs | ![Development](https://img.shields.io/badge/-development-blue) |
| `gcp_pubsub` | Google Cloud Pub/Sub | ![Development](https://img.shields.io/badge/-development-blue) |
| `jms` | Java Message Service | ![Development](https://img.shields.io/badge/-development-blue) |
| `kafka` | Apache Kafka | ![Development](https://img.shields.io/badge/-development-blue) |
| `pulsar` | Apache Pulsar | ![Development](https://img.shields.io/badge/-development-blue) |
| `rabbitmq` | RabbitMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `rocketmq` | Apache RocketMQ | ![Development](https://img.shields.io/badge/-development-blue) |
| `servicebus` | Azure Service Bus | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- endsemconv -->

## 例

### 非同期バッチ発行の例

トピックTに対して2件のメッセージをバッチで非同期に発行するプロセスPの例です。

```mermaid
flowchart LR;
  subgraph PRODUCER
  direction LR
  CA[Span Create A]
  CB[Span Create B]
  P[Span Send A B]
  end
  CA-. link .-P;
  CB-. link .-P;

  classDef producer fill:green
  class P,CA,CB producer
  classDef normal fill:green
  class PA,PB,D1 normal
  linkStyle 0,1 color:green,stroke:green
```

| フィールドまたは属性 | Producer Span Create A | Producer Span Create B | Producer Span Send A B |
| --- | --- | --- | --- |
| Span name | `create T` | `create T` | `send T` |
| 親 | | | |
| リンク | | | Span Create A, Span Create B |
| SpanKind | `PRODUCER` | `PRODUCER` | `CLIENT` |
| ステータス | `Ok` | `Ok` | `Ok` |
| `messaging.batch.message_count` | | | 2 |
| `messaging.destination.name` | `"T"` | `"T"` | `"T"` |
| `messaging.operation.name` | `"create"` | `"create"` | `"send"` |
| `messaging.operation.type` | `"create"` | `"create"` | `"send"` |
| `messaging.message.id` | `"a1"` | `"a2"` | |
| `messaging.message.envelope.size` | `1` | `1` | |
| `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` |

### 単発pullの例

```mermaid
flowchart TD;
  subgraph CONSUMER
  direction LR
  R1[Receive A]
  SM1[Ack A]
  EM1[Modack A]
  end
  subgraph PRODUCER
  direction LR
  CM1[Create A]
  PM1[Send]
  end
  %% Link 0
  CM1-. link .-PM1;
  %% Link 1
  CM1-. link .-R1;
  %% Link 2
  R1-. link .-SM1;
  %% Link 3
  R1-. link .-EM1;

  %% Style the node and corresponding link
  %% Producer links and nodes
  classDef producer fill:green
  class PM1,CM1 producer
  linkStyle 0 color:green,stroke:green

  %% Consumer links and nodes
  classDef consumer fill:#49fcdc
  class R1 consumer
  linkStyle 1 color:#49fcdc,stroke:#49fcdc

  classDef ack fill:#577eb5
  class SM1 ack
  linkStyle 2 color:#577eb5,stroke:#577eb5

  classDef modack fill:#0560f2
  class EM1 modack
  linkStyle 3 color:#0560f2,stroke:#0560f2
```

| フィールドまたは属性 | Producer Span Create A | Producer Span Send | Consumer Span Receive A | Consumer Span Modack A | Consumer Span Ack A |
| --- | --- | --- | --- | --- | --- |
| Span name | `create T` | `send T` | `receive S` | `modack S` | `ack S` |
| 親 | | | | | |
| リンク | | Span Create A | Span Create A | Span Receive A | Span Receive A |
| SpanKind | `PRODUCER` | `CLIENT` | `CLIENT` | `CLIENT` | `CLIENT` |
| ステータス | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` |
| `messaging.destination.name` | `"T"` | `"T"` | `"S"` | `"S"` | `"S"` |
| `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` |
| `messaging.operation.name` | `"create"` | `"send"` | `"receive"` | `"modack"` | `"ack"` |
| `messaging.operation.type` | `"create"` | `"send"` | `"receive"` | | `"settle"` |
| `messaging.message.id` | `"a1"` | | `"a1"` | | |
| `messaging.message.envelope.size` | `1` | `1` | `1` | | |
| `messaging.gcp_pubsub.message.ack_id` | | | | `"ack_id1"` | `"ack_id1"` |
| `messaging.gcp_pubsub.message.delivery_attempt` | | | | `0` | |
| `messaging.gcp_pubsub.message.ack_deadline` | | | | | `0` |

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status