AWS SNSに関するセマンティック規約

ステータス: Development

AWS SNSに関するセマンティック規約は、このページで説明する規約に加えて、共通のAWS SDK属性を記述する一般的なAWS SDKに関するセマンティック規約を拡張します。

AWS SNSスパン

AWS SNSは、一般的なメッセージングスパンを特化させたものです。

Sendスパン（プロデューサー）

Status:

このスパンは、Producerが1つ以上のメッセージをAmazon SNSに発行することを表します。

別途"Create"スパンが存在せず、“Send"スパンのコンテキストがメッセージの生成コンテキストとしてメッセージに注入される場合に、このスパンを使用します。詳細はProducerスパンを参照してください。

Span kind は PRODUCER にすべきです（SHOULD）。

Span status は、エラーの記録の文書に従うべきです（SHOULD）。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`messaging.operation.name`	`Required`	string	メッセージング操作のシステム固有の名前。	`send`; `publish`
`messaging.system`	`Required`	string	クライアント計装によって識別されたメッセージングシステム。[1]	`aws.sns`
`error.type`	`Conditionally Required` メッセージング操作が失敗した場合に限る。	string	操作が終了したエラーのクラスを記述します。[2]	`AuthorizationError`; `EndpointDisabled`; `Throttled`
`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.operation.type`	`Conditionally Required` 適用可能な場合。	string	メッセージング操作の種別を識別する文字列。[9]	`send`
`aws.request_id`	`Recommended`	string	レスポンスヘッダー `x-amzn-requestid`、`x-amzn-request-id`、または `x-amz-request-id` として返されるAWSリクエストID。	`79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ`
`aws.sns.topic.arn`	`Recommended`	string	AWS SNSトピックのARN。Amazon SNSのトピックは、通信チャネルとして機能する論理的なアクセスポイントです。	`arn:aws:sns:us-east-1:123456789012:mystack-mytopic-NZJ5JSMVGFIE`
`messaging.client.id`	`Recommended`	string	メッセージを消費または生成するクライアントの一意な識別子。	`client-5`; `myhost@8742@s8083jm`
`messaging.destination.partition.id`	`Recommended` 適用可能な場合。	string	メッセージが送信または受信されるパーティションの識別子。`messaging.destination.name` の中で一意です。	`1`
`messaging.message.conversation_id`	`Recommended`	string	メッセージが属する会話を識別する会話ID。文字列として表現されます。「Correlation ID」と呼ばれることもあります。	`MyConversationId`
`messaging.message.id`	`Recommended` スパンが単一のメッセージに対する操作を表す場合。	string	メッセージングシステムがメッセージの識別子として使用する値。文字列として表現されます。	`452a7c7c7c7048c2f887f61572b18fc2`
`network.peer.address`	`Recommended` このメッセージングシステムに適用可能な場合。	string	操作が実行されたメッセージングIntermediaryノードのピアアドレス。[10]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended` `network.peer.address` が設定されている場合に限る。	int	操作が実行されたメッセージングIntermediaryノードのピアポート。	`65123`
`server.address`	`Recommended`	string	利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[11]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`server.port`	`Recommended`	int	サーバーのポート番号。[12]	`80`; `8080`; `443`
`messaging.message.body.size`	`Opt-In`	int	メッセージ本文のバイト数。単一メッセージの操作を表すスパンにのみ適用されます。[13]	`1439`
`messaging.message.envelope.size`	`Opt-In`	int	メッセージ本文とメタデータの合計バイト数。[14]	`2738`

[1] messaging.system: "aws.sns" に設定しなければなりません（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: send に設定すべきです（SHOULD）。

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

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

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

[13] messaging.message.body.size: 圧縮後・圧縮前のいずれのボディサイズも指す場合があります。両方のサイズがわかっている場合は、圧縮前のボディサイズを使用すべきです。

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

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

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つ以上のメッセージがIntermediaryへの送信のために提供されます。単一のメッセージが送信される場合、“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