AWSにおける互換性の考慮事項

このページでは、aws-sdk、サードパーティライブラリ、または直接のHTTPリクエストを通じてAWSのマネージドサービスとやり取りする際に、OpenTelemetryの計装が考慮すべき互換性の事項をまとめます。

コンテキスト伝搬

AWS SDK、サードパーティライブラリ、または直接のHTTPリクエストを使ってAWSのマネージドサービスを呼び出す際は、その呼び出しから間接的に呼び出される他のサービスへコンテキストを伝搬できるように、AWSサービスがサポートする伝搬フォーマットを使って送信リクエストのHTTPヘッダーにコンテキスト伝搬を追加すべきです（SHOULD）。

計装は、その計装専用に別のプロパゲーターを明示的に設定できるようにしてもよいでしょう（例えば、明示的に指定するプロパゲーターや、すべての呼び出しあるいは特定の呼び出しに対してグローバルに設定されたプロパゲーターを使うオプションなど）。これは、SQSやSNSのメッセージ属性のように、サービス側がこれらのヘッダーを受信側まで伝送できるようにしている特定のケースで有用です。なお、これはこのオプションを提供する計装が、X-Rayプロパゲーターの呼び出しを単純に別のプロパゲーターの呼び出しに置き換えるだけでは済まないことも意味します（そうすると、APIのREST呼び出しでHTTPヘッダーが送信されるだけになり、受信側のAWSサービスによって即座に無視されてしまうためです）。そうではなく、サービスごとの呼び出しに応じた実装を必要な箇所（例えばSQSの送信と受信）に導入する必要があります。こうすることで、X-Rayではサポートされていないbaggageやtracestateといった追加のコンテキストを伝送できるようになったり、一部のレガシーな伝搬フォーマットをサポートできるようになったりします。ドキュメントでは、そのようにする場合には属性の上限や課金への影響が伴うことを明記すべきです（SHOULD）。

署名済みリクエストでエラーが起きないようにするため、伝搬用のヘッダーは署名を計算する前に追加しなければなりません（MUST）。リクエスト自体にヘッダーを注入する場合（単にHTTPヘッダーを追加するだけでない場合）は、追加の考慮事項が発生することがあります（例えば、.NET AWS SDKは送信する属性のハッシュを計算し、受信するMD5OfMessageAttributesと比較します）。

現在、AWSサービスがネイティブにサポートしている伝搬フォーマットは以下のとおりです。

AWS X-Ray

例えばS3 -> SNS -> SQS -> Lambdaのように、AWSのマネージドサービスを経由してコンテキストを伝搬するには、AWSサービスがサポートするコンテキスト伝搬が必要です。

（このコンテキスト伝搬がLambdaの計装でどのように利用されるかについては、aws-lambda sqs-eventのセマンティック規約を参照してください。）